@stll/folio-core 0.50.0 → 0.51.0

package/dist/ai-edits/word-diff.js

@@ -836,6 +836,137 @@ const orderDeletionsFirst = (runs) => {
 	flush();
 	return ordered;
 };
+const WORD_CHARACTER = /^[\p{L}\p{N}\p{M}]$/u;
+const LINE_BREAK = /^[\n\r\p{Zl}\p{Zp}]$/u;
+/**
+* How well a change edge between two code points reads, after
+* diff-match-patch's semantic score: the string's edge (an empty side), then
+* a line break, then the gap after a sentence or clause mark, then any space,
+* then any other mark; inside a word is worst.
+*/
+const boundaryScore = (previous, next) => {
+	if (previous.length === 0 || next.length === 0) return 6;
+	if (LINE_BREAK.test(previous) || LINE_BREAK.test(next)) return 4;
+	const previousIsSpace = WHITESPACE.test(previous);
+	const nextIsSpace = WHITESPACE.test(next);
+	if (!previousIsSpace && !WORD_CHARACTER.test(previous) && nextIsSpace) return 3;
+	if (previousIsSpace || nextIsSpace) return 2;
+	return WORD_CHARACTER.test(previous) && WORD_CHARACTER.test(next) ? 0 : 1;
+};
+/** True when `position` falls between the two halves of a surrogate pair. */
+const splitsSurrogatePair = (text, position) => {
+	const low = text.charCodeAt(position);
+	const high = text.charCodeAt(position - 1);
+	return low >= 56320 && low <= 57343 && high >= 55296 && high <= 56319;
+};
+/**
+* Where, among the lossless positions of one change, it reads best. The
+* change may slide by one character whenever the character it gives up
+* equals the one it takes on, which keeps both strings intact. Only the
+* window decides the result, so an insertion and the deletion that undoes it
+* land on the same text; the leftmost of equally good positions wins.
+*/
+const bestSlideStart = (window) => {
+	const { text, start, length, minimumStart, maximumEnd } = window;
+	const scoreAt = (position) => boundaryScore(position === 0 ? window.outsideBefore : codePointBefore(text, position), position === text.length ? window.outsideAfter : codePointAt(text, position));
+	let leftmost = start;
+	while (leftmost > minimumStart && text[leftmost - 1] === text[leftmost + length - 1]) leftmost--;
+	let best = start;
+	let bestScore = -1;
+	for (let candidate = leftmost; candidate + length <= maximumEnd; candidate++) {
+		const end = candidate + length;
+		if (!splitsSurrogatePair(text, candidate) && !splitsSurrogatePair(text, end)) {
+			const startScore = scoreAt(candidate);
+			const endScore = scoreAt(end);
+			if (!(candidate !== start && (startScore === 0 || endScore === 0)) && startScore + endScore > bestScore) {
+				best = candidate;
+				bestScore = startScore + endScore;
+			}
+		}
+		if (end === text.length || text[candidate] !== text[end]) break;
+	}
+	return best;
+};
+/**
+* Whether a change may end up directly beside `neighbour` once the equality
+* between them empties: always beside nothing, an equality or its own kind,
+* and a deletion may precede an insertion; an insertion before a deletion
+* would break deletion-first order.
+*/
+const mayAbut = (first, second) => first === void 0 || second === void 0 || first === "equal" || second === "equal" || first === second || first === "del" && second === "ins";
+/** The code point nearest `index`, walking by `step`, on the side `type` belongs to. */
+const sideCodePoint = (segments, { from, step }, type) => {
+	for (let index = from; index >= 0 && index < segments.length; index += step) {
+		const segment = segments[index];
+		if (segment === void 0 || segment.text.length === 0) continue;
+		if (segment.type === "equal" || segment.type === type) return step === 1 ? codePointAt(segment.text, 0) : codePointBefore(segment.text, segment.text.length);
+	}
+	return "";
+};
+const mergeAdjacentSegments = (segments) => {
+	const merged = [];
+	for (const segment of segments) {
+		const last = merged.at(-1);
+		if (segment.text.length === 0) continue;
+		if (last?.type === segment.type) {
+			last.text += segment.text;
+			continue;
+		}
+		merged.push(segment);
+	}
+	return merged;
+};
+/**
+* Slide every insertion or deletion that sits between equalities to the
+* position that reads best.
+*
+* An LCS places a change arbitrarily among equally long alignments: an
+* appended sentence can be marked as `". New sentence"` before the old
+* sentence's full stop, not `" New sentence."` after it. The redline then
+* marks a stop the author never touched and leaves the new sentence's own
+* unmarked. Sliding moves only where a change's edges fall, so both strings
+* still reconstruct.
+*/
+const slideChangesToReadableBoundaries = (segments) => {
+	const slid = [
+		{
+			type: "equal",
+			text: ""
+		},
+		...segments.map((segment) => ({ ...segment })),
+		{
+			type: "equal",
+			text: ""
+		}
+	];
+	for (let index = 1; index < slid.length - 1; index++) {
+		const change = slid[index];
+		const previous = slid[index - 1];
+		const next = slid[index + 1];
+		if (change === void 0 || previous === void 0 || next === void 0 || change.type === "equal" || previous.type !== "equal" || next.type !== "equal") continue;
+		const text = previous.text + change.text + next.text;
+		const start = bestSlideStart({
+			text,
+			start: previous.text.length,
+			length: change.text.length,
+			minimumStart: mayAbut(slid[index - 2]?.type, change.type) ? 0 : 1,
+			maximumEnd: mayAbut(change.type, slid[index + 2]?.type) ? text.length : text.length - 1,
+			outsideBefore: sideCodePoint(slid, {
+				from: index - 2,
+				step: -1
+			}, change.type),
+			outsideAfter: sideCodePoint(slid, {
+				from: index + 2,
+				step: 1
+			}, change.type)
+		});
+		const end = start + change.text.length;
+		previous.text = text.slice(0, start);
+		change.text = text.slice(start, end);
+		next.text = text.slice(end);
+	}
+	return mergeAdjacentSegments(slid);
+};
 const wholeStringReplacement = (before, after) => {
 	const segments = [];
 	if (before.length > 0) segments.push({
@@ -903,7 +1034,9 @@ const diffWordSegmentsWithBudget = (before, after, options, budget) => {
 		const monotoneRuns = alignMonotoneChange(before, after, beforeTokens, afterTokens, normalization, monotoneDirection);
 		marked = whitespaceIsSignificant ? separateWhitespaceChanges(monotoneRuns) : monotoneRuns;
 	}
-	return toSegments(orderDeletionsFirst(marked));
+	const segments = toSegments(orderDeletionsFirst(marked));
+	const equalRunsAreExact = requestedNormalization.case !== true && requestedNormalization.whitespace !== true;
+	return granularity === "word" && equalRunsAreExact ? slideChangesToReadableBoundaries(segments) : segments;
 };
 /**
 * One internal comparison/apply scope. Every diff shares the same quadratic

package/dist/compare/content-alignment.js

@@ -260,6 +260,44 @@ const pairByUniqueExactText = ({ base, revised, baseFrom, baseTo, revisedFrom, r
 	}
 	return pairs.toReversed();
 };
+/**
+* Unique exact text anchors, then again inside every sub-gap they leave:
+* wording repeated elsewhere in a document is still identity evidence within
+* the one gap where it is unique, so a section's pairing does not depend on
+* whether a neighbouring section happens to repeat it. Each nested pass is
+* charged to the structural allowance; a refused pass leaves its sub-gap to
+* the similarity pairing.
+*/
+const pairByNestedUniqueExactText = ({ workSession, ...gap }) => {
+	const anchors = [];
+	const pending = [gap];
+	for (let current = pending.pop(); current !== void 0; current = pending.pop()) {
+		const found = pairByUniqueExactText(current);
+		if (found.length === 0) continue;
+		anchors.push(...found);
+		let baseFrom = current.baseFrom;
+		let revisedFrom = current.revisedFrom;
+		for (const anchor of [...found, {
+			baseIndex: current.baseTo,
+			revisedIndex: current.revisedTo
+		}]) {
+			const size = anchor.baseIndex - baseFrom + (anchor.revisedIndex - revisedFrom);
+			if (anchor.baseIndex > baseFrom && anchor.revisedIndex > revisedFrom && size <= workSession.remainingStructuralTokenLookups) {
+				workSession.remainingStructuralTokenLookups -= size;
+				pending.push({
+					...current,
+					baseFrom,
+					baseTo: anchor.baseIndex,
+					revisedFrom,
+					revisedTo: anchor.revisedIndex
+				});
+			}
+			baseFrom = anchor.baseIndex + 1;
+			revisedFrom = anchor.revisedIndex + 1;
+		}
+	}
+	return anchors.toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
+};
 const pairsInAnchorGaps = ({ baseLength, revisedLength, anchors, pairGap }) => {
 	const pairs = [];
 	let baseFrom = 0;
@@ -312,9 +350,122 @@ const crossedExactTextBlocks = ({ base, revised, anchors, canPair }) => {
 		revised: crossedRevised
 	};
 };
+/**
+* Minimum multiset Dice similarity for two blocks to pair inside a gap. At
+* 0.5 a paragraph still pairs after gaining up to twice its own length
+* (2n / (n + 3n)); below it, more of the pair would read as changed than
+* kept, which a removal beside an insertion says better.
+*/
+const GAP_PAIR_SIMILARITY_THRESHOLD = .5;
+/**
+* Gap similarities are compared as integers, so a tie is exact rather than an
+* accident of floating-point summation, and a tie-break can sit below the
+* smallest similarity step.
+*/
+const GAP_PAIR_SIMILARITY_SCALE = 1e3;
+/**
+* Words as case-folded runs of letters, marks and digits: punctuation glued to
+* a word ("paragraph." against "paragraph") and a capital at a sentence start
+* would otherwise count a kept word as changed.
+*/
+const gapBlockTokens = (text) => {
+	const counts = /* @__PURE__ */ new Map();
+	let total = 0;
+	for (const match of text.toLowerCase().matchAll(/[\p{L}\p{M}\p{N}]+/gu)) {
+		total += 1;
+		counts.set(match[0], (counts.get(match[0]) ?? 0) + 1);
+	}
+	return {
+		counts,
+		total
+	};
+};
+const gapBlockSimilarity = (base, revised, workSession) => {
+	if (base.total === 0 && revised.total === 0) return {
+		status: "measured",
+		value: 1
+	};
+	if (base.total === 0 || revised.total === 0) return {
+		status: "measured",
+		value: GAP_PAIR_SIMILARITY_THRESHOLD
+	};
+	const [tokens, counterparts] = base.counts.size <= revised.counts.size ? [base.counts, revised.counts] : [revised.counts, base.counts];
+	if (tokens.size > workSession.remainingStructuralTokenLookups) return { status: "budget-exceeded" };
+	workSession.remainingStructuralTokenLookups -= tokens.size;
+	let shared = 0;
+	for (const [token, count] of tokens) shared += Math.min(count, counterparts.get(token) ?? 0);
+	return {
+		status: "measured",
+		value: 2 * shared / (base.total + revised.total)
+	};
+};
+/**
+* The order-preserving pairs of one gap that maximise their summed
+* similarity, each at least `GAP_PAIR_SIMILARITY_THRESHOLD`; offsets are into
+* the gap's slices. Pairing by position instead fuses an inserted block with
+* the neighbour it pushed down, and every block after it with the next one's
+* wording. Null when the work budget refuses the gap.
+*/
+const pairGapBySimilarity = ({ base, revised, canPair, workSession }) => {
+	const baseCount = base.length;
+	const revisedCount = revised.length;
+	if (!claimFolioContentAlignmentCells(baseCount, revisedCount, workSession)) return null;
+	const revisedTokens = revised.map((block) => gapBlockTokens(block.block.text));
+	const similarityStep = Math.min(baseCount, revisedCount) + 1;
+	const similarity = new Float64Array(baseCount * revisedCount).fill(-1);
+	const candidateBase = /* @__PURE__ */ new Set();
+	const candidateRevised = /* @__PURE__ */ new Set();
+	for (const [baseOffset, baseBlock] of base.entries()) {
+		const baseTokens = gapBlockTokens(baseBlock.block.text);
+		for (const [revisedOffset, revisedBlock] of revised.entries()) {
+			if (!canPair(baseBlock, revisedBlock)) continue;
+			const tokens = revisedTokens[revisedOffset] ?? panic("A gap block has no token profile");
+			const measured = baseBlock.block.text === revisedBlock.block.text ? {
+				status: "measured",
+				value: 1
+			} : gapBlockSimilarity(baseTokens, tokens, workSession);
+			if (measured.status === "budget-exceeded") return null;
+			if (measured.value >= GAP_PAIR_SIMILARITY_THRESHOLD) {
+				const sameLabel = baseBlock.block.displayLabel !== void 0 && baseBlock.block.displayLabel === revisedBlock.block.displayLabel;
+				similarity[baseOffset * revisedCount + revisedOffset] = Math.round(measured.value * GAP_PAIR_SIMILARITY_SCALE) * similarityStep + (sameLabel ? 1 : 0);
+				candidateBase.add(baseOffset);
+				candidateRevised.add(revisedOffset);
+			}
+		}
+	}
+	const width = revisedCount + 1;
+	const scores = new Float64Array((baseCount + 1) * width);
+	const cellSimilarity = (baseOffset, revisedOffset) => similarity[baseOffset * revisedCount + revisedOffset] ?? -1;
+	const score = (row, column) => scores[row * width + column] ?? 0;
+	for (let row = baseCount - 1; row >= 0; row--) for (let column = revisedCount - 1; column >= 0; column--) {
+		const cell = cellSimilarity(row, column);
+		scores[row * width + column] = Math.max(score(row + 1, column), score(row, column + 1), cell < 0 ? 0 : score(row + 1, column + 1) + cell);
+	}
+	const pairs = [];
+	let row = 0;
+	let column = 0;
+	while (row < baseCount && column < revisedCount) {
+		const cell = cellSimilarity(row, column);
+		if (cell >= 0 && score(row, column) === score(row + 1, column + 1) + cell) {
+			pairs.push({
+				baseIndex: row,
+				revisedIndex: column
+			});
+			row += 1;
+			column += 1;
+		} else if (score(row, column) === score(row + 1, column)) row += 1;
+		else column += 1;
+	}
+	return {
+		pairs,
+		candidateBase,
+		candidateRevised
+	};
+};
 const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 	const stableIdMismatch = options.stableIdMismatch ?? "separate";
 	const idStability = options.idStability ?? folioContentIdStability;
+	const workSession = options.workSession ?? createFolioContentAlignmentWorkSession();
 	const prepared = prepareAlignmentBlocks({
 		baseBlocks,
 		revisedBlocks,
@@ -335,14 +486,15 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		baseLength: prepared.base.length,
 		revisedLength: prepared.revised.length,
 		anchors: stableIdAnchors,
-		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByUniqueExactText({
+		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByNestedUniqueExactText({
 			base: prepared.base,
 			revised: prepared.revised,
 			baseFrom,
 			baseTo,
 			revisedFrom,
 			revisedTo,
-			canPair
+			canPair,
+			workSession
 		})
 	});
 	const exactAndStableAnchors = [...stableIdAnchors, ...exactTextAnchors].toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
@@ -368,12 +520,13 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		canPair
 	});
 	const events = [];
+	const fusesACrossing = (baseBlock, revisedBlock) => baseBlock.block.text !== revisedBlock.block.text && crossed.base.has(baseBlock.index) && crossed.revised.has(revisedBlock.index);
 	const emitPositionalGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
 		const pairedCount = Math.min(baseTo - baseFrom, revisedTo - revisedFrom);
 		for (let offset = 0; offset < pairedCount; offset++) {
 			const baseBlock = prepared.base[baseFrom + offset];
 			const revisedBlock = prepared.revised[revisedFrom + offset];
-			if (baseBlock && revisedBlock) if (baseBlock.block.text !== revisedBlock.block.text && crossed.base.has(baseBlock.index) && crossed.revised.has(revisedBlock.index) || !canPair(baseBlock, revisedBlock)) {
+			if (baseBlock && revisedBlock) if (fusesACrossing(baseBlock, revisedBlock) || !canPair(baseBlock, revisedBlock)) {
 				events.push({
 					type: "baseOnly",
 					block: baseBlock.block
@@ -403,10 +556,72 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 			});
 		}
 	};
+	/**
+	* A gap's blocks pair by similarity, whether or not its sides are equal in
+	* length: an equal gap can hide an insertion beside a deletion, and pairing
+	* it by position reads each kept block as a rewrite of its neighbour. The
+	* similar pairs anchor the rest; blocks between two anchors pair by position
+	* only when neither side offered any candidate and the counts match, which
+	* reads a block rewritten beyond recognition as the modification it is.
+	*/
+	const emitGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
+		const pairing = pairGapBySimilarity({
+			base: prepared.base.slice(baseFrom, baseTo),
+			revised: prepared.revised.slice(revisedFrom, revisedTo),
+			canPair: (baseBlock, revisedBlock) => !fusesACrossing(baseBlock, revisedBlock) && canPair(baseBlock, revisedBlock),
+			workSession
+		});
+		if (pairing === null) {
+			emitPositionalGap(baseFrom, baseTo, revisedFrom, revisedTo);
+			return;
+		}
+		const { pairs, candidateBase, candidateRevised } = pairing;
+		let baseCursor = baseFrom;
+		let revisedCursor = revisedFrom;
+		const hasCandidate = (candidates, from, to) => {
+			for (let offset = from; offset < to; offset++) if (candidates.has(offset)) return true;
+			return false;
+		};
+		const emitUnpairedUntil = (baseEnd, revisedEnd) => {
+			if (baseEnd - baseCursor === revisedEnd - revisedCursor && !hasCandidate(candidateBase, baseCursor - baseFrom, baseEnd - baseFrom) && !hasCandidate(candidateRevised, revisedCursor - revisedFrom, revisedEnd - revisedFrom)) {
+				emitPositionalGap(baseCursor, baseEnd, revisedCursor, revisedEnd);
+				baseCursor = baseEnd;
+				revisedCursor = revisedEnd;
+				return;
+			}
+			for (; baseCursor < baseEnd; baseCursor++) {
+				const block = prepared.base[baseCursor]?.block;
+				if (block) events.push({
+					type: "baseOnly",
+					block
+				});
+			}
+			for (; revisedCursor < revisedEnd; revisedCursor++) {
+				const block = prepared.revised[revisedCursor]?.block;
+				if (block) events.push({
+					type: "revisedOnly",
+					block
+				});
+			}
+		};
+		for (const pair of pairs) {
+			emitUnpairedUntil(baseFrom + pair.baseIndex, revisedFrom + pair.revisedIndex);
+			const baseBlock = prepared.base[baseCursor]?.block;
+			const revisedBlock = prepared.revised[revisedCursor]?.block;
+			if (baseBlock && revisedBlock) events.push({
+				type: "pair",
+				baseBlock,
+				revisedBlock
+			});
+			baseCursor += 1;
+			revisedCursor += 1;
+		}
+		emitUnpairedUntil(baseTo, revisedTo);
+	};
 	let baseCursor = 0;
 	let revisedCursor = 0;
 	for (const anchor of anchors) {
-		emitPositionalGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
+		emitGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
 		const baseBlock = prepared.base[anchor.baseIndex]?.block;
 		const revisedBlock = prepared.revised[anchor.revisedIndex]?.block;
 		if (baseBlock && revisedBlock) events.push({
@@ -417,7 +632,7 @@ const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 		baseCursor = anchor.baseIndex + 1;
 		revisedCursor = anchor.revisedIndex + 1;
 	}
-	emitPositionalGap(baseCursor, prepared.base.length, revisedCursor, prepared.revised.length);
+	emitGap(baseCursor, prepared.base.length, revisedCursor, prepared.revised.length);
 	return events;
 };
 const alignFolioContentBlocks = (baseBlocks, revisedBlocks, options = {}) => alignFolioContentBlocksInScope(baseBlocks, revisedBlocks, {

package/dist/compare/content.d.ts

@@ -186,6 +186,7 @@ type ParagraphMarkPlan<Block extends FolioContentBlock> = {
   revisedBlock: Block;
   separator: string;
 };
+/** Plans keyed by their first step; each consumes the step after it. */
 declare const detectFolioContentParagraphMarkPlans: <Block extends FolioContentBlock>(steps: readonly FolioContentAlignmentStep<Block>[]) => ReadonlyMap<number, ParagraphMarkPlan<Block>>;
 type MovePair<Block extends FolioContentBlock> = {
   baseBlock: Block;

package/dist/compare/content.js

@@ -431,30 +431,61 @@ const separatorBetween = (whole, head, tail) => {
 	const separator = whole.slice(head.length, whole.length - tail.length);
 	return separator.length === 0 || /^\s+$/u.test(separator) ? separator : null;
 };
+const splitPlan = ({ baseBlock, head, tail }) => {
+	const separator = separatorBetween(baseBlock.text, head.text, tail.text);
+	return separator !== null && contentBlocksShareContainer(head, tail) ? {
+		type: "split",
+		baseBlock,
+		revisedBlocks: [head, tail],
+		offset: head.text.length,
+		separator
+	} : null;
+};
+const mergePlan = ({ revisedBlock, head, tail }) => {
+	const separator = separatorBetween(revisedBlock.text, head.text, tail.text);
+	return separator !== null && contentBlocksShareContainer(head, tail) ? {
+		type: "merge",
+		baseBlocks: [head, tail],
+		revisedBlock,
+		separator
+	} : null;
+};
+/**
+* A pair next to a one-sided block its text spells together with the pair's
+* other side. Alignment pairs a split paragraph with whichever half reads more
+* like it, so the unpaired half may stand before the pair or after it.
+*/
+const paragraphMarkPlan = (step, next) => {
+	if (step.type === "pair" && next.type === "revisedOnly") return splitPlan({
+		baseBlock: step.baseBlock,
+		head: step.revisedBlock,
+		tail: next.block
+	});
+	if (step.type === "pair" && next.type === "baseOnly") return mergePlan({
+		revisedBlock: step.revisedBlock,
+		head: step.baseBlock,
+		tail: next.block
+	});
+	if (step.type === "revisedOnly" && next.type === "pair") return splitPlan({
+		baseBlock: next.baseBlock,
+		head: step.block,
+		tail: next.revisedBlock
+	});
+	if (step.type === "baseOnly" && next.type === "pair") return mergePlan({
+		revisedBlock: next.revisedBlock,
+		head: step.block,
+		tail: next.baseBlock
+	});
+	return null;
+};
+/** Plans keyed by their first step; each consumes the step after it. */
 const detectFolioContentParagraphMarkPlans = (steps) => {
 	const plans = /* @__PURE__ */ new Map();
 	for (const [index, step] of steps.entries()) {
 		const next = steps[index + 1];
-		if (step.type !== "pair" || next === void 0) continue;
-		if (next.type === "revisedOnly") {
-			const separator = separatorBetween(step.baseBlock.text, step.revisedBlock.text, next.block.text);
-			if (separator !== null && contentBlocksShareContainer(step.revisedBlock, next.block)) plans.set(index, {
-				type: "split",
-				baseBlock: step.baseBlock,
-				revisedBlocks: [step.revisedBlock, next.block],
-				offset: step.revisedBlock.text.length,
-				separator
-			});
-			continue;
-		}
-		if (next.type !== "baseOnly") continue;
-		const separator = separatorBetween(step.revisedBlock.text, step.baseBlock.text, next.block.text);
-		if (separator !== null && contentBlocksShareContainer(step.baseBlock, next.block)) plans.set(index, {
-			type: "merge",
-			baseBlocks: [step.baseBlock, next.block],
-			revisedBlock: step.revisedBlock,
-			separator
-		});
+		if (next === void 0 || plans.has(index - 1)) continue;
+		const plan = paragraphMarkPlan(step, next);
+		if (plan !== null) plans.set(index, plan);
 	}
 	return plans;
 };

package/dist/docx/selectiveSave.d.ts

@@ -3,7 +3,7 @@ import { document_d_exports } from "../types/document.js";
 type SelectiveSaveOptions = {
   /** Changed paragraph IDs to selectively patch */
   changedParaIds: Set<string>;
-  /** Whether structural changes occurred (paragraph add/delete) */
+  /** Whether paragraph membership, order, or block structure changed. */
   structuralChange: boolean;
   /** Whether any changes affected paragraphs without paraId */
   hasUntrackedChanges: boolean;

package/dist/docx/selectiveSave.js

@@ -8,12 +8,13 @@ import { isUnsafePackagePath } from "./packageParts.js";
 import { RELATIONSHIP_TYPES } from "./relsParser.js";
 import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
 import "./selectiveSaveFlags.js";
-import { buildPatchedDocumentXml, buildPatchedNoteXml, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
+import { buildPatchedDocumentXml, buildPatchedNoteXml, collectAddedNumberingDefs, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
 import { planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
 import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
+import { buildStructuralDocumentPatch } from "./structuralXmlPatch.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/selectiveSave.ts
 /**
@@ -174,7 +175,6 @@ const queueSettingsUpdates = async (zip, updates) => {
 async function attemptSelectiveSave(doc, originalBuffer, options) {
 	const { changedParaIds, structuralChange, hasUntrackedChanges } = options;
 	const maxBytes = options.maxBytes ?? 104857600;
-	if (structuralChange) return null;
 	if (hasUntrackedChanges) return null;
 	if (originalBuffer.byteLength > maxBytes) return null;
 	const content = doc.package.document.content;
@@ -197,22 +197,32 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
 		const updates = /* @__PURE__ */ new Map();
-		if (changedParaIds.size > 0) {
+		if (changedParaIds.size > 0 || structuralChange) {
 			const docXmlFile = zip.file("word/document.xml");
 			if (!docXmlFile) return null;
 			const originalDocXml = await docXmlFile.async("text");
 			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml));
 			const bodyParaIds = collectParaIds(serializedDocXml);
+			const originalBodyParaIds = structuralChange ? collectParaIds(originalDocXml) : void 0;
+			if (structuralChange && doc.package.numbering) {
+				const numberingFile = findZipEntryCaseInsensitive(zip, "word/numbering.xml");
+				const added = collectAddedNumberingDefs(numberingFile ? serializeNumberingXml(parseNumbering(await numberingFile.async("text")).definitions) : "", serializeNumberingXml(doc.package.numbering));
+				if (added.abstractNums.size > 0 || added.nums.size > 0) return null;
+			}
 			const bodyChangedIds = /* @__PURE__ */ new Set();
 			const noteCandidateIds = /* @__PURE__ */ new Set();
-			for (const id of changedParaIds) if (bodyParaIds.has(id)) bodyChangedIds.add(id);
+			for (const id of changedParaIds) if (bodyParaIds.has(id) || originalBodyParaIds?.has(id)) bodyChangedIds.add(id);
 			else noteCandidateIds.add(id);
 			if (noteCandidateIds.size > 0) {
 				const unrouted = await patchNoteParts(zip, doc, noteCandidateIds, updates);
 				if (unrouted === null || unrouted.size > 0) return null;
 			}
-			if (bodyChangedIds.size > 0) {
-				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializedDocXml, bodyChangedIds);
+			if (bodyChangedIds.size > 0 || structuralChange) {
+				const patchedDocXml = structuralChange ? buildStructuralDocumentPatch({
+					originalXml: originalDocXml,
+					serializedXml: serializedDocXml,
+					changedIds: bodyChangedIds
+				}) : buildPatchedDocumentXml(originalDocXml, serializedDocXml, bodyChangedIds);
 				if (!patchedDocXml) return null;
 				updates.set("word/document.xml", patchedDocXml);
 			}

package/dist/docx/structuralXmlPatch.d.ts

@@ -0,0 +1,14 @@
+//#region src/docx/structuralXmlPatch.d.ts
+type StructuralPatchOptions = {
+  originalXml: string;
+  serializedXml: string;
+  changedIds: ReadonlySet<string>;
+};
+/**
+ * Insert/delete direct body paragraphs between surviving paragraph/table anchors.
+ * Tables are opaque barriers: their modeled content and order must stay identical.
+ * Id-less sources need an explicit ensureParaIds ingest before structural editing.
+ */
+declare const buildStructuralDocumentPatch: ({ originalXml, serializedXml, changedIds }: StructuralPatchOptions) => string | null;
+//#endregion
+export { buildStructuralDocumentPatch };

package/dist/docx/structuralXmlPatch.js

@@ -0,0 +1,209 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { parseDocumentBody } from "./documentParser.js";
+import { paraIdAttribute } from "./paraIdAttribute.js";
+import { spliceXml } from "./selectiveXmlPatch.js";
+import { readRootNamespaceBindings, serializePartElement } from "./serializer/partNamespaces.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+//#region src/docx/structuralXmlPatch.ts
+/** Conservative body-paragraph splices; source offsets never come from reserialization. */
+const isWordElement = (element, name) => getLocalName(element.name) === name && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "");
+/** Match XML tokens, skipping quoted delimiters, comments, CDATA and processing instructions. */
+const XML_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<(?:"[^"]*"|'[^']*'|[^'">])*>/gu;
+const readBody = (xml) => {
+	const root = parseXmlDocument(xml);
+	if (!root || !isWordElement(root, "document")) return null;
+	if (getNamespaceUri(root) !== NAMESPACES.w) return null;
+	const body = getChildElements(root).find((child) => isWordElement(child, "body"));
+	if (!body) return null;
+	const children = getChildElements(body);
+	const blocks = [];
+	const stack = [];
+	let bodyDepth = -1;
+	let bodyEnd = -1;
+	let start = -1;
+	for (const token of xml.matchAll(XML_TOKEN)) {
+		const tag = token[0];
+		if (tag.startsWith("<!") || tag.startsWith("<?")) continue;
+		const closing = tag.startsWith("</");
+		const name = tag.slice(closing ? 2 : 1).split(/[\s/>]/u).at(0);
+		if (!name) return null;
+		if (closing) {
+			if (stack.pop() !== name) return null;
+			if (stack.length === bodyDepth) {
+				const element = children[blocks.length];
+				if (!element || start < 0) return null;
+				blocks.push({
+					element,
+					start,
+					end: token.index + tag.length
+				});
+				start = -1;
+			}
+			if (name === body.name && stack.length === bodyDepth - 1) bodyEnd = token.index;
+			continue;
+		}
+		if (name === body.name && stack.length === 1) bodyDepth = 2;
+		if (stack.length === bodyDepth) {
+			if (children[blocks.length]?.name !== name) return null;
+			start = token.index;
+			if (tag.endsWith("/>")) {
+				const element = children[blocks.length];
+				if (!element) return null;
+				blocks.push({
+					element,
+					start,
+					end: token.index + tag.length
+				});
+				start = -1;
+			}
+		}
+		if (!tag.endsWith("/>")) stack.push(name);
+	}
+	if (stack.length > 0 || blocks.length !== children.length || bodyEnd < 0) return null;
+	return {
+		root,
+		blocks,
+		bodyEnd
+	};
+};
+function* descendants(element) {
+	yield element;
+	for (const child of getChildElements(element)) yield* descendants(child);
+}
+/** Cross-paragraph ranges require a wider edit contract than paragraph identity. */
+const RANGE_ELEMENTS = /* @__PURE__ */ new Set([
+	"commentRangeStart",
+	"commentRangeEnd",
+	"commentReference",
+	"bookmarkStart",
+	"bookmarkEnd",
+	"permStart",
+	"permEnd",
+	"fldChar",
+	"moveFromRangeStart",
+	"moveFromRangeEnd",
+	"moveToRangeStart",
+	"moveToRangeEnd"
+]);
+const DEPENDENT_ELEMENTS = /* @__PURE__ */ new Set([
+	"sectPr",
+	"footnoteReference",
+	"endnoteReference",
+	"drawing",
+	"pict",
+	"object"
+]);
+const paragraphIsSafe = (element, touched) => {
+	for (const child of descendants(element)) {
+		if (!WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) continue;
+		const name = getLocalName(child.name);
+		if (touched && DEPENDENT_ELEMENTS.has(name)) return false;
+	}
+	return true;
+};
+const paragraphIds = (root) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const element of descendants(root)) {
+		if (!isWordElement(element, "p")) continue;
+		const id = paraIdAttribute(element);
+		if (!id || !/^[0-9a-f]{8}$/iu.test(id) || /^0+$/u.test(id) || ids.has(id.toUpperCase())) return null;
+		ids.add(id.toUpperCase());
+	}
+	return ids;
+};
+/** Bind fragment prefixes locally: the source root may use entirely different aliases. */
+const paragraphFragment = ({ xml, block, bindings }) => {
+	const fragment = xml.slice(block.start, block.end);
+	const openEnd = fragment.indexOf(">");
+	const name = block.element.name ?? "w:p";
+	const selfClosing = fragment[openEnd - 1] === "/";
+	return serializePartElement({
+		partPath: "word/document.xml",
+		rootName: name,
+		rootAttributes: fragment.slice(name.length + 1, selfClosing ? openEnd - 1 : openEnd).trim(),
+		baselinePrefixes: [],
+		sourceBindings: bindings,
+		body: selfClosing ? "" : fragment.slice(openEnd + 1, fragment.lastIndexOf("</"))
+	});
+};
+/**
+* Insert/delete direct body paragraphs between surviving paragraph/table anchors.
+* Tables are opaque barriers: their modeled content and order must stay identical.
+* Id-less sources need an explicit ensureParaIds ingest before structural editing.
+*/
+const buildStructuralDocumentPatch = ({ originalXml, serializedXml, changedIds }) => {
+	const source = readBody(originalXml);
+	const current = readBody(serializedXml);
+	if (!source || !current) return null;
+	for (const root of [source.root, current.root]) for (const element of descendants(root)) if (WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "") && RANGE_ELEMENTS.has(getLocalName(element.name))) return null;
+	const allSourceIds = paragraphIds(source.root);
+	const allCurrentIds = paragraphIds(current.root);
+	if (!allSourceIds || !allCurrentIds) return null;
+	const changed = new Set([...changedIds].map((id) => id.toUpperCase()));
+	for (const { element } of [...source.blocks, ...current.blocks]) if (isWordElement(element, "p")) {
+		const id = paraIdAttribute(element)?.toUpperCase();
+		if (!id) return null;
+		const touched = changed.has(id) || !allSourceIds.has(id) || !allCurrentIds.has(id);
+		if (!paragraphIsSafe(element, touched)) return null;
+	} else if (!isWordElement(element, "tbl") && !isWordElement(element, "sectPr")) return null;
+	const sourceBody = parseDocumentBody(originalXml);
+	const currentBody = parseDocumentBody(serializedXml);
+	const barriers = (body) => ({
+		blocks: body.content.filter((block) => block.type !== "paragraph"),
+		finalSectionProperties: body.finalSectionProperties,
+		background: body.background
+	});
+	if (canonicalJson(barriers(sourceBody)) !== canonicalJson(barriers(currentBody))) return null;
+	const indexBlocks = (blocks) => {
+		let barrier = 0;
+		const indexed = /* @__PURE__ */ new Map();
+		for (const block of blocks) {
+			const key = isWordElement(block.element, "p") ? `p:${paraIdAttribute(block.element)?.toUpperCase()}` : `barrier:${barrier++}`;
+			indexed.set(key, block);
+		}
+		return indexed;
+	};
+	const before = indexBlocks(source.blocks);
+	const after = indexBlocks(current.blocks);
+	const survivingBefore = [...before.keys()].filter((key) => after.has(key));
+	const survivingAfter = [...after.keys()].filter((key) => before.has(key));
+	if (canonicalJson(survivingBefore) !== canonicalJson(survivingAfter)) return null;
+	const bindings = readRootNamespaceBindings(serializedXml);
+	const fragmentFor = (block) => paragraphFragment({
+		xml: serializedXml,
+		block,
+		bindings
+	});
+	const splices = [];
+	for (const [key, block] of before) if (!after.has(key)) splices.push({
+		start: block.start,
+		end: block.end,
+		newXml: ""
+	});
+	let pending = [];
+	for (const [key, block] of after) {
+		const original = before.get(key);
+		if (!original) {
+			const id = paraIdAttribute(block.element)?.toUpperCase();
+			if (!id || allSourceIds.has(id)) return null;
+			pending.push(fragmentFor(block));
+			continue;
+		}
+		const id = paraIdAttribute(block.element)?.toUpperCase();
+		const replacement = id !== void 0 && changed.has(id) ? fragmentFor(block) : originalXml.slice(original.start, original.end);
+		if (pending.length > 0 || replacement !== originalXml.slice(original.start, original.end)) splices.push({
+			start: original.start,
+			end: original.end,
+			newXml: pending.join("") + replacement
+		});
+		pending = [];
+	}
+	if (pending.length > 0) splices.push({
+		start: source.bodyEnd,
+		end: source.bodyEnd,
+		newXml: pending.join("")
+	});
+	return spliceXml(originalXml, splices);
+};
+//#endregion
+export { buildStructuralDocumentPatch };

package/dist/managers/editorShortcuts.d.ts

@@ -1,3 +1,4 @@
+import { HistoryShortcutOwner } from "../prosemirror/extensions/core/HistoryExtension.js";
 import { EditorState, Transaction } from "prosemirror-state";
 //#region src/managers/editorShortcuts.d.ts
 declare function isMacPlatform(): boolean;
@@ -17,19 +18,31 @@ type EditorKeydownIntent = {
 } | {
   type: "none";
 };
+/**
+ * An editor shortcut the host binds itself. The editor leaves its keys alone,
+ * so the host's binding (an IDE's undo stack, its own print command) is the
+ * only one that runs.
+ *  - `"history"`: undo and redo (Mod-z, Mod-y, Mod-Shift-z).
+ *  - `"print"`: Cmd/Ctrl+P.
+ */
+type HostShortcut = "history" | "print";
+/** Who answers the undo and redo keys when the host owns `hostShortcuts`. */
+declare const historyShortcutOwner: (hostShortcuts: readonly HostShortcut[]) => HistoryShortcutOwner;
 type ClassifyEditorKeydownOptions = {
   /** Whether the platform uses Cmd (Mac) rather than Ctrl as the primary modifier. */
   isMac: boolean;
   /** Whether focus is in a non-editor input/textarea/contenteditable. */
   isInputLike: boolean;
+  /** Shortcuts the host binds itself; their keys map to `none`. */
+  hostShortcuts: readonly HostShortcut[];
 };
 /**
  * Map a keydown to an editor intent:
  *  - Cmd/Ctrl+F or Cmd/Ctrl+H → open find
- *  - Cmd/Ctrl+P (no auto-repeat) → custom print
+ *  - Cmd/Ctrl+P (no auto-repeat) → custom print, unless the host owns print
  *  - Delete/Backspace (no modifiers, focus not in an input) → delete selected table
  */
-declare function classifyEditorKeydown(e: KeyboardEvent, { isMac, isInputLike }: ClassifyEditorKeydownOptions): EditorKeydownIntent;
+declare function classifyEditorKeydown(e: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey" | "repeat">, { isMac, isInputLike, hostShortcuts }: ClassifyEditorKeydownOptions): EditorKeydownIntent;
 /**
  * Which key presses the editor's page-level shortcuts answer.
  *  - `"document"`: every press on the page.
@@ -69,4 +82,4 @@ declare function isKeydownInShortcutScope(event: {
  */
 declare function deleteSelectedTable(state: EditorState, dispatch: (tr: Transaction) => void): boolean;
 //#endregion
-export { ClassifyEditorKeydownOptions, EditorKeydownIntent, IsKeydownInShortcutScopeOptions, KeyboardShortcutScope, ShortcutScopeRoot, classifyEditorKeydown, deleteSelectedTable, isFocusInInputLike, isKeydownInShortcutScope, isMacPlatform };
+export { ClassifyEditorKeydownOptions, EditorKeydownIntent, HostShortcut, IsKeydownInShortcutScopeOptions, KeyboardShortcutScope, ShortcutScopeRoot, classifyEditorKeydown, deleteSelectedTable, historyShortcutOwner, isFocusInInputLike, isKeydownInShortcutScope, isMacPlatform };

package/dist/managers/editorShortcuts.js

@@ -16,19 +16,21 @@ function isFocusInInputLike(target, editorDom) {
 	if (target.isContentEditable && target !== editorDom) return true;
 	return false;
 }
+/** Who answers the undo and redo keys when the host owns `hostShortcuts`. */
+const historyShortcutOwner = (hostShortcuts) => hostShortcuts.includes("history") ? "host" : "editor";
 /**
 * Map a keydown to an editor intent:
 *  - Cmd/Ctrl+F or Cmd/Ctrl+H → open find
-*  - Cmd/Ctrl+P (no auto-repeat) → custom print
+*  - Cmd/Ctrl+P (no auto-repeat) → custom print, unless the host owns print
 *  - Delete/Backspace (no modifiers, focus not in an input) → delete selected table
 */
-function classifyEditorKeydown(e, { isMac, isInputLike }) {
+function classifyEditorKeydown(e, { isMac, isInputLike, hostShortcuts }) {
 	const cmdOrCtrl = isMac ? e.metaKey : e.ctrlKey;
 	if (!cmdOrCtrl && !e.shiftKey && !e.altKey && (e.key === "Delete" || e.key === "Backspace") && !isInputLike) return { type: "deleteSelectedTable" };
 	if (cmdOrCtrl && !e.shiftKey && !e.altKey) {
 		const key = e.key.toLowerCase();
 		if (key === "f" || key === "h") return { type: "openFind" };
-		if (key === "p" && !e.repeat) return { type: "print" };
+		if (key === "p" && !e.repeat && !hostShortcuts.includes("print")) return { type: "print" };
 	}
 	return { type: "none" };
 }
@@ -76,4 +78,4 @@ function deleteSelectedTable(state, dispatch) {
 	return false;
 }
 //#endregion
-export { classifyEditorKeydown, deleteSelectedTable, isFocusInInputLike, isKeydownInShortcutScope, isMacPlatform };
+export { classifyEditorKeydown, deleteSelectedTable, historyShortcutOwner, isFocusInInputLike, isKeydownInShortcutScope, isMacPlatform };

package/dist/prosemirror/extensions/StarterKit.d.ts

@@ -1,4 +1,5 @@
 import { AnyExtension } from "./types.js";
+import { HistoryShortcutOwner } from "./core/HistoryExtension.js";
 import { SelectionChangeCallback } from "../plugins/selectionTracker.js";
 //#region src/prosemirror/extensions/StarterKit.d.ts
 type StarterKitOptions = {
@@ -8,6 +9,8 @@ type StarterKitOptions = {
   historyDepth?: number;
   /** History new group delay (default: 500) */
   historyNewGroupDelay?: number;
+  /** Who answers the undo and redo keys (default: `"editor"`). */
+  historyShortcuts?: HistoryShortcutOwner;
   /** Selection change callback */
   onSelectionChange?: SelectionChangeCallback;
 };

package/dist/prosemirror/extensions/StarterKit.js

@@ -61,7 +61,8 @@ function createStarterKit(options = {}) {
 	add("paragraph", ParagraphExtension());
 	add("history", HistoryExtension({
 		...options.historyDepth !== void 0 ? { depth: options.historyDepth } : {},
-		...options.historyNewGroupDelay !== void 0 ? { newGroupDelay: options.historyNewGroupDelay } : {}
+		...options.historyNewGroupDelay !== void 0 ? { newGroupDelay: options.historyNewGroupDelay } : {},
+		...options.historyShortcuts !== void 0 ? { shortcuts: options.historyShortcuts } : {}
 	}));
 	for (const name of MARK_NESTING_ORDER) add(name, MARK_EXTENSIONS[name]());
 	add("bookmarkBoundary", BookmarkBoundaryExtension({ getInternalClipboardToken }));

package/dist/prosemirror/extensions/core/HistoryExtension.d.ts

@@ -3,10 +3,18 @@ import { Extension } from "../types.js";
 /**
  * History Extension — undo/redo via prosemirror-history
  */
+/**
+ * Who answers the undo and redo keys (Mod-z, Mod-y, Mod-Shift-z).
+ *  - `"editor"`: the extension binds them. Default.
+ *  - `"host"`: nothing binds them. The host keeps its own undo stack and runs
+ *    the `undo` / `redo` commands itself, so one press never undoes twice.
+ */
+type HistoryShortcutOwner = "editor" | "host";
 type HistoryOptions = {
   depth: number;
   newGroupDelay: number;
+  shortcuts: HistoryShortcutOwner;
 };
 declare const HistoryExtension: (options?: Partial<HistoryOptions> | undefined) => Extension;
 //#endregion
-export { HistoryExtension };
+export { HistoryExtension, HistoryShortcutOwner };

package/dist/prosemirror/extensions/core/HistoryExtension.js

@@ -4,7 +4,8 @@ const HistoryExtension = createExtension({
 	name: "history",
 	defaultOptions: {
 		depth: 100,
-		newGroupDelay: 500
+		newGroupDelay: 500,
+		shortcuts: "editor"
 	},
 	onSchemaReady(_ctx, options) {
 		return {
@@ -16,11 +17,11 @@ const HistoryExtension = createExtension({
 				undo: () => undo,
 				redo: () => redo
 			},
-			keyboardShortcuts: {
+			...options.shortcuts === "editor" && { keyboardShortcuts: {
 				"Mod-z": undo,
 				"Mod-y": redo,
 				"Mod-Shift-z": redo
-			}
+			} }
 		};
 	}
 });

package/dist/prosemirror/extensions/features/ParagraphChangeTrackerExtension.d.ts

@@ -3,15 +3,15 @@ import { RemovedSectionReference, TrackedSectionEndpointRemoval } from "../../..
 import { EditorState, PluginKey, Transaction } from "prosemirror-state";
 import { Node } from "prosemirror-model";
 //#region src/prosemirror/extensions/features/ParagraphChangeTrackerExtension.d.ts
-declare const paragraphChangeTrackerKey: PluginKey<ParagraphChangeTrackerState>;
+declare const paragraphChangeTrackerKey: PluginKey<InternalParagraphChangeTrackerState>;
 type ParagraphChangeTrackerState = {
   /** Set of paraIds that were modified since last clear */
   changedParaIds: Set<string>;
-  /** Whether paragraphs were added or deleted (structural change) */
+  /** Whether paragraph order, membership, or block structure changed. */
   structuralChange: boolean;
-  /** Whether any edited paragraph lacked a paraId */
+  /** Whether edited paragraphs still lack IDs or source identity was unavailable. */
   hasUntrackedChanges: boolean;
-  /** Cached paragraph count to avoid full doc traversal on every transaction */
+  /** Paragraph count in the current tracked document. */
   paragraphCount: number;
   /** Cached section-endpoint count used to invalidate stale save authorization. */
   sectionEndpointCount: number;
@@ -20,6 +20,13 @@ type ParagraphChangeTrackerState = {
   /** Exact tracked-resolution transition that may reduce the saved section count. */
   sectionEndpointRemoval: TrackedSectionEndpointRemoval | null;
 };
+type InternalParagraphChangeTrackerState = ParagraphChangeTrackerState & {
+  /** Edited paragraph positions retained across allocator-only transactions. */
+  affectedParagraphPositions: Set<number>;
+  /** Editing an already unidentified source paragraph cannot become selective. */
+  hasUntrackedSourceChanges: boolean;
+  blockStructureFingerprint: string;
+};
 /**
  * Get the change tracker state from an EditorState
  */
@@ -29,7 +36,7 @@ declare function getChangeTrackerState(state: EditorState): ParagraphChangeTrack
  */
 declare function getChangedParagraphIds(state: EditorState): Set<string>;
 /**
- * Check if structural changes (paragraph add/delete) occurred
+ * Check if paragraph membership, order, or block structure changed
  */
 declare function hasStructuralChanges(state: EditorState): boolean;
 /**

package/dist/prosemirror/extensions/features/ParagraphChangeTrackerExtension.js

@@ -18,9 +18,20 @@ const isTrackedSectionEndpointRemovalMeta = (value) => typeof value === "object"
 function countDocumentStructure(doc) {
 	let paragraphs = 0;
 	let sectionEndpoints = 0;
+	const blockRecords = [];
 	const endpointRecords = [];
 	const visit = (parent, parentPath) => {
 		parent.forEach((node, _offset, index) => {
+			const path = parentPath.length === 0 ? `${index}` : `${parentPath}.${index}`;
+			blockRecords.push(node.type.name === "paragraph" ? [
+				path,
+				node.type.name,
+				node.attrs["paraId"] ?? null
+			] : [
+				path,
+				node.type.name,
+				canonicalJson(node.attrs)
+			]);
 			if (node.type.name === "paragraph") {
 				paragraphs++;
 				const sectionProperties = sectionPropertiesOf(node);
@@ -34,34 +45,36 @@ function countDocumentStructure(doc) {
 				}
 				return;
 			}
-			if (node.childCount > 0) {
-				const path = parentPath.length === 0 ? `${index}` : `${parentPath}.${index}`;
-				visit(node, path);
-			}
+			if (node.childCount > 0) visit(node, path);
 		});
 	};
 	visit(doc, "");
 	return {
+		blockStructureFingerprint: JSON.stringify(blockRecords),
 		paragraphs,
 		sectionEndpoints,
 		sectionEndpointFingerprint: canonicalJson(endpointRecords)
 	};
 }
+const isUsableParaId = (value) => typeof value === "string" && value.length > 0 && value !== "00000000";
 /**
 * Collect paraIds of all paragraphs that overlap with the given range
 */
 function collectAffectedParaIds(doc, from, to) {
 	const ids = /* @__PURE__ */ new Set();
+	const positions = /* @__PURE__ */ new Set();
 	let hasUntracked = false;
-	doc.nodesBetween(from, to, (node) => {
+	doc.nodesBetween(from, to, (node, pos) => {
 		if (node.type.name === "paragraph") {
+			positions.add(pos);
 			const paraId = node.attrs["paraId"];
-			if (paraId) ids.add(paraId);
+			if (isUsableParaId(paraId)) ids.add(paraId);
 			else hasUntracked = true;
 		}
 	});
 	return {
 		ids,
+		positions,
 		hasUntracked
 	};
 }
@@ -75,28 +88,40 @@ function collectAffectedParaIdsFromMarkLikeStep(doc, from, to) {
 	const hi = Math.max(from, to);
 	const primary = collectAffectedParaIds(doc, lo, hi > lo ? hi : lo + 1);
 	if (primary.ids.size > 0 || primary.hasUntracked) return primary;
-	try {
-		const $p = doc.resolve(lo);
-		for (let d = $p.depth; d >= 0; d--) {
-			const n = $p.node(d);
-			if (n.type.name === "paragraph") {
-				const paraId = n.attrs["paraId"];
-				if (paraId) return {
-					ids: /* @__PURE__ */ new Set([paraId]),
-					hasUntracked: false
-				};
-				return {
-					ids: /* @__PURE__ */ new Set(),
-					hasUntracked: true
-				};
-			}
+	const $p = doc.resolve(lo);
+	for (let depth = $p.depth; depth > 0; depth--) {
+		const node = $p.node(depth);
+		if (node.type.name === "paragraph") {
+			const paraId = node.attrs["paraId"];
+			return {
+				ids: new Set(isUsableParaId(paraId) ? [paraId] : []),
+				positions: /* @__PURE__ */ new Set([$p.before(depth)]),
+				hasUntracked: !isUsableParaId(paraId)
+			};
 		}
-	} catch {}
+	}
 	return {
 		ids: /* @__PURE__ */ new Set(),
+		positions: /* @__PURE__ */ new Set(),
 		hasUntracked: false
 	};
 }
+/** Map an edited paragraph's interior so markup replacement retains its ownership. */
+const mapParagraphPosition = (tr, position) => {
+	const mapped = tr.mapping.mapResult(position + 1, 1);
+	if (mapped.deletedAcross) return null;
+	const $position = tr.doc.resolve(mapped.pos);
+	for (let depth = $position.depth; depth > 0; depth--) if ($position.node(depth).type.name === "paragraph") return $position.before(depth);
+	return null;
+};
+const mapAffectedParagraphPositions = (tr, positions) => {
+	const mappedPositions = /* @__PURE__ */ new Set();
+	for (const position of positions) {
+		const mapped = mapParagraphPosition(tr, position);
+		if (mapped !== null) mappedPositions.add(mapped);
+	}
+	return mappedPositions;
+};
 function mapStepPosition(remap, pos, assoc) {
 	return remap.map(pos, assoc);
 }
@@ -107,6 +132,9 @@ function createParagraphChangeTrackerPlugin() {
 			init(_config, state) {
 				const counts = countDocumentStructure(state.doc);
 				return {
+					affectedParagraphPositions: /* @__PURE__ */ new Set(),
+					hasUntrackedSourceChanges: false,
+					blockStructureFingerprint: counts.blockStructureFingerprint,
 					changedParaIds: /* @__PURE__ */ new Set(),
 					structuralChange: false,
 					hasUntrackedChanges: false,
@@ -123,6 +151,9 @@ function createParagraphChangeTrackerPlugin() {
 				if (meta === CLEAR_META) {
 					const counts = countDocumentStructure(tr.doc);
 					return {
+						affectedParagraphPositions: /* @__PURE__ */ new Set(),
+						hasUntrackedSourceChanges: false,
+						blockStructureFingerprint: counts.blockStructureFingerprint,
 						changedParaIds: /* @__PURE__ */ new Set(),
 						structuralChange: false,
 						hasUntrackedChanges: false,
@@ -133,13 +164,22 @@ function createParagraphChangeTrackerPlugin() {
 					};
 				}
 				if (meta === IGNORE_META) {
-					const counts = tr.docChanged ? countDocumentStructure(tr.doc) : {
-						paragraphs: prevState.paragraphCount,
-						sectionEndpoints: prevState.sectionEndpointCount,
-						sectionEndpointFingerprint: prevState.sectionEndpointFingerprint
-					};
+					if (!tr.docChanged) return prevState;
+					const counts = countDocumentStructure(tr.doc);
+					const affectedParagraphPositions = mapAffectedParagraphPositions(tr, prevState.affectedParagraphPositions);
+					const changedParaIds = /* @__PURE__ */ new Set();
+					let unresolvedChanges = prevState.hasUntrackedSourceChanges;
+					for (const position of affectedParagraphPositions) {
+						const paraId = tr.doc.nodeAt(position)?.attrs["paraId"];
+						if (isUsableParaId(paraId)) changedParaIds.add(paraId);
+						else unresolvedChanges = true;
+					}
 					return {
 						...prevState,
+						affectedParagraphPositions,
+						changedParaIds,
+						hasUntrackedChanges: unresolvedChanges,
+						blockStructureFingerprint: counts.blockStructureFingerprint,
 						paragraphCount: counts.paragraphs,
 						sectionEndpointCount: counts.sectionEndpoints,
 						sectionEndpointRemoval: counts.sectionEndpointFingerprint === prevState.sectionEndpointFingerprint ? prevState.sectionEndpointRemoval : null,
@@ -162,6 +202,9 @@ function createParagraphChangeTrackerPlugin() {
 					};
 				} else sectionEndpointRemoval = null;
 				const newState = {
+					affectedParagraphPositions: mapAffectedParagraphPositions(tr, prevState.affectedParagraphPositions),
+					hasUntrackedSourceChanges: prevState.hasUntrackedSourceChanges,
+					blockStructureFingerprint: counts.blockStructureFingerprint,
 					changedParaIds: new Set(prevState.changedParaIds),
 					structuralChange: prevState.structuralChange || meta === STRUCTURAL_META,
 					hasUntrackedChanges: prevState.hasUntrackedChanges,
@@ -176,12 +219,13 @@ function createParagraphChangeTrackerPlugin() {
 						const from = mapStepPosition(remap, range.from, 1);
 						const to = mapStepPosition(remap, range.to, -1);
 						if (to <= from) continue;
-						const { ids, hasUntracked } = collectAffectedParaIdsFromMarkLikeStep(tr.doc, from, to);
+						const { ids, positions, hasUntracked } = collectAffectedParaIdsFromMarkLikeStep(tr.doc, from, to);
+						for (const position of positions) newState.affectedParagraphPositions.add(position);
 						for (const id of ids) newState.changedParaIds.add(id);
 						if (hasUntracked) newState.hasUntrackedChanges = true;
 					}
 				}
-				if (prevState.paragraphCount !== newCount) newState.structuralChange = true;
+				if (prevState.blockStructureFingerprint !== counts.blockStructureFingerprint) newState.structuralChange = true;
 				for (let stepIndex = 0; stepIndex < tr.steps.length; stepIndex++) {
 					const step = tr.steps[stepIndex];
 					const remap = tr.mapping.slice(stepIndex + 1);
@@ -189,7 +233,8 @@ function createParagraphChangeTrackerPlugin() {
 						const from = mapStepPosition(remap, step.from, 1);
 						const to = mapStepPosition(remap, step.to, -1);
 						if (to <= from) continue;
-						const { ids, hasUntracked } = collectAffectedParaIdsFromMarkLikeStep(tr.doc, from, to);
+						const { ids, positions, hasUntracked } = collectAffectedParaIdsFromMarkLikeStep(tr.doc, from, to);
+						for (const position of positions) newState.affectedParagraphPositions.add(position);
 						for (const id of ids) newState.changedParaIds.add(id);
 						if (hasUntracked) newState.hasUntrackedChanges = true;
 						continue;
@@ -199,7 +244,8 @@ function createParagraphChangeTrackerPlugin() {
 						const node = tr.doc.nodeAt(pos);
 						if (!node) continue;
 						const end = pos + node.nodeSize;
-						const { ids, hasUntracked } = collectAffectedParaIds(tr.doc, pos, end);
+						const { ids, positions, hasUntracked } = collectAffectedParaIds(tr.doc, pos, end);
+						for (const position of positions) newState.affectedParagraphPositions.add(position);
 						for (const id of ids) newState.changedParaIds.add(id);
 						if (hasUntracked) newState.hasUntrackedChanges = true;
 						continue;
@@ -208,11 +254,23 @@ function createParagraphChangeTrackerPlugin() {
 						const from = mapStepPosition(remap, newStart, 1);
 						const to = mapStepPosition(remap, newEnd, -1);
 						if (to < from) return;
-						const { ids, hasUntracked } = collectAffectedParaIds(tr.doc, from, to);
+						const { ids, positions, hasUntracked } = collectAffectedParaIds(tr.doc, from, to);
+						for (const position of positions) newState.affectedParagraphPositions.add(position);
 						for (const id of ids) newState.changedParaIds.add(id);
 						if (hasUntracked) newState.hasUntrackedChanges = true;
 					});
 				}
+				if (newState.hasUntrackedChanges || prevState.blockStructureFingerprint !== counts.blockStructureFingerprint) tr.before.descendants((node, position) => {
+					if (node.type.name !== "paragraph") return true;
+					if (!isUsableParaId(node.attrs["paraId"])) {
+						const mapped = mapParagraphPosition(tr, position);
+						if (mapped === null || newState.affectedParagraphPositions.has(mapped)) {
+							newState.hasUntrackedSourceChanges = true;
+							newState.hasUntrackedChanges = true;
+						}
+					}
+					return false;
+				});
 				return newState;
 			}
 		}
@@ -231,7 +289,7 @@ function getChangedParagraphIds(state) {
 	return getChangeTrackerState(state)?.changedParaIds ?? /* @__PURE__ */ new Set();
 }
 /**
-* Check if structural changes (paragraph add/delete) occurred
+* Check if paragraph membership, order, or block structure changed
 */
 function hasStructuralChanges(state) {
 	return getChangeTrackerState(state)?.structuralChange ?? false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",