@stll/folio-core 0.25.1 → 0.25.2

package/dist/ai-edits/headless.d.ts

@@ -148,7 +148,9 @@ declare class FolioDocxReviewer {
   private readonly originalBuffer;
   private state;
   private readonly secondaryStoryStates;
+  private readonly resolvedStoryExpectations;
   private readonly createdComments;
+  private readonly usedCommentIds;
   private readonly documentOperationUndoEntries;
   /**
    * Resolved-state overrides recorded by {@link resolveComment}, keyed by
@@ -289,6 +291,8 @@ declare class FolioDocxReviewer {
    * structural edits — the same two-tier path the editor's save uses.
    */
   toBuffer(): Promise<ArrayBuffer>;
+  private assertResolvedStoriesSerialized;
+  private getChangedNoteParaIds;
   /**
    * Attempt the selective patch, treating a throw the same as a decline. Odd
    * source XML can make the paragraph diff throw rather than return `null`; a
@@ -308,6 +312,8 @@ declare class FolioDocxReviewer {
   private withResolvedOverrides;
   /** Map each anchored comment id to its anchored text and containing block id. */
   private commentAnchors;
+  /** Allocate outside every parsed or newly-created comment and reply id. */
+  private nextCommentId;
   /**
    * Drive a ProseMirror command against the reviewer's headless state via the
    * same `{ state, dispatch }` seam {@link applyOperations} uses, retaining the

package/dist/ai-edits/headless.js

@@ -53,8 +53,8 @@ let undoHandleCursor = Date.now();
 * headless `commentOnBlock` / `comment` op serialises the same `comments.xml`
 * shape the editor produces.
 */
-const createReviewerComment = (text, author) => ({
-	id: commentIdCursor++,
+const createReviewerComment = (id, text, author) => ({
+	id,
 	author,
 	date: (/* @__PURE__ */ new Date()).toISOString(),
 	content: [{
@@ -133,10 +133,12 @@ const FOLIO_REVIEWED_VIEWS = Object.freeze([
 const FOLIO_RESOLVED_REVIEWED_VIEWS = Object.freeze(["original", "final"]);
 var UnsupportedFolioReviewedViewError = class extends TaggedError("UnsupportedFolioReviewedViewError") {};
 var FolioDocumentStoryNotFoundError = class extends TaggedError("FolioDocumentStoryNotFoundError") {};
+var FolioResolvedStorySerializationError = class extends TaggedError("FolioResolvedStorySerializationError") {};
 const MAIN_STORY = Object.freeze({ type: "main" });
 const headerFooterStoryKey = ({ type, relationshipId }) => `${type}:${relationshipId}`;
 const noteStoryKey = ({ type, noteId }) => `${type}:${noteId}`;
 const secondaryStoryKey = (story) => story.type === "header" || story.type === "footer" ? headerFooterStoryKey(story) : noteStoryKey(story);
+const editableStoryKey = (story) => story.type === "main" ? "main" : secondaryStoryKey(story);
 const isFolioReviewedView = (value) => FOLIO_REVIEWED_VIEWS.some((view) => view === value);
 const isFolioResolvedReviewedView = (value) => FOLIO_RESOLVED_REVIEWED_VIEWS.some((view) => view === value);
 const applyCommandToState = (state, command) => {
@@ -211,7 +213,9 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	originalBuffer;
 	state;
 	secondaryStoryStates = /* @__PURE__ */ new Map();
+	resolvedStoryExpectations = /* @__PURE__ */ new Map();
 	createdComments = [];
+	usedCommentIds;
 	documentOperationUndoEntries = [];
 	/**
 	* Resolved-state overrides recorded by {@link resolveComment}, keyed by
@@ -227,6 +231,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		this.originalBuffer = args.originalBuffer;
 		this.state = args.state;
 		this.author = args.author;
+		this.usedCommentIds = new Set((args.baseDocument.package.document.comments ?? []).map(({ id }) => id));
 	}
 	/** Parse a `.docx` buffer into a reviewer. */
 	static async fromBuffer(buffer, options = {}) {
@@ -297,7 +302,13 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 		const sourceState = this.getEditableStoryState(story);
 		if (!sourceState) return false;
-		this.setEditableStoryState(story, resolveReviewedState(sourceState, view));
+		const resolvedState = resolveReviewedState(sourceState, view);
+		this.setEditableStoryState(story, resolvedState);
+		this.resolvedStoryExpectations.set(editableStoryKey(story), {
+			story,
+			text: formatStoryStateForLLM(resolvedState, false),
+			blocks: createFolioAIEditSnapshot(resolvedState.doc).blocks
+		});
 		return true;
 	}
 	/**
@@ -360,7 +371,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			story: story.type === "main" ? "main" : story,
 			author: this.author,
 			createCommentId: (text) => {
-				const comment = createReviewerComment(text, this.author);
+				const comment = createReviewerComment(this.nextCommentId(), text, this.author);
 				this.createdComments.push(comment);
 				return comment.id;
 			},
@@ -602,6 +613,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 		if (!reply) return null;
 		this.createdComments.push(reply);
+		this.usedCommentIds.add(reply.id);
 		return {
 			id: reply.id,
 			author: reply.author,
@@ -676,11 +688,43 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	async toBuffer() {
 		const document = this.toDocument();
 		const selective = await this.trySelectiveSave(document);
-		if (selective) return selective;
-		return repackDocx({
+		if (selective) {
+			await this.assertResolvedStoriesSerialized(selective);
+			return selective;
+		}
+		const buffer = await repackDocx({
 			...document,
 			originalBuffer: this.originalBuffer
-		});
+		}, { changedNoteParaIds: this.getChangedNoteParaIds() });
+		await this.assertResolvedStoriesSerialized(buffer);
+		return buffer;
+	}
+	async assertResolvedStoriesSerialized(buffer) {
+		if (this.resolvedStoryExpectations.size === 0) return;
+		const reopened = await FolioDocxReviewer.fromBuffer(buffer);
+		for (const { story, text, blocks } of this.resolvedStoryExpectations.values()) {
+			const serialized = reopened.readReviewedStory({
+				story,
+				view: "current-markup"
+			});
+			const serializedState = reopened.getEditableStoryState(story);
+			if (serialized && serializedState && serialized.changes.length === 0 && formatStoryStateForLLM(serializedState, false) === text && JSON.stringify(createFolioAIEditSnapshot(serializedState.doc).blocks) === JSON.stringify(blocks)) continue;
+			throw new FolioResolvedStorySerializationError({
+				message: "Resolved document story did not persist to the serialized DOCX.",
+				story,
+				expectedText: text,
+				actualText: serializedState ? formatStoryStateForLLM(serializedState, false) : null,
+				remainingChangeCount: serialized?.changes.length ?? null
+			});
+		}
+	}
+	getChangedNoteParaIds() {
+		const changed = /* @__PURE__ */ new Set();
+		for (const entry of this.secondaryStoryStates.values()) {
+			if (entry.handle.type !== "footnote" && entry.handle.type !== "endnote") continue;
+			for (const paraId of getChangedParagraphIds(entry.state)) changed.add(paraId);
+		}
+		return changed;
 	}
 	/**
 	* Attempt the selective patch, treating a throw the same as a decline. Odd
@@ -741,6 +785,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 	}
 	setEditableStoryState(story, state) {
+		this.resolvedStoryExpectations.delete(editableStoryKey(story));
 		if (story.type === "main") {
 			this.state = state;
 			return;
@@ -840,12 +885,20 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 		return anchors;
 	}
+	/** Allocate outside every parsed or newly-created comment and reply id. */
+	nextCommentId() {
+		while (this.usedCommentIds.has(commentIdCursor)) commentIdCursor += 1;
+		const id = commentIdCursor++;
+		this.usedCommentIds.add(id);
+		return id;
+	}
 	/**
 	* Drive a ProseMirror command against the reviewer's headless state via the
 	* same `{ state, dispatch }` seam {@link applyOperations} uses, retaining the
 	* resulting state for {@link toBuffer}.
 	*/
 	runCommand(command) {
+		this.resolvedStoryExpectations.delete("main");
 		const view = {
 			state: this.state,
 			dispatch: (transaction) => {

package/dist/ai-edits/read.d.ts

@@ -2,6 +2,31 @@ import { FolioNodeRevisionKind } from "../prosemirror/revisionCarriers.js";
 import { Node } from "prosemirror-model";
 //#region src/ai-edits/read.d.ts
 type FolioReviewChangeKind = "insertion" | "deletion" | "formatting" | "rowInserted" | "rowDeleted" | "cellInserted" | "cellDeleted" | "cellMerged" | FolioNodeRevisionKind;
+/**
+ * Runtime census of every tracked-change discriminator the reviewer exposes.
+ *
+ * The total Record is intentional: adding a new FolioReviewChangeKind without
+ * adding it here is a compile-time error. Cross-product persistence tests use
+ * this census, so a newly modeled revision cannot silently miss the resolver
+ * and serialization matrix.
+ */
+declare const FOLIO_REVIEW_CHANGE_KINDS: Readonly<{
+  readonly insertion: "insertion";
+  readonly deletion: "deletion";
+  readonly formatting: "formatting";
+  readonly rowInserted: "rowInserted";
+  readonly rowDeleted: "rowDeleted";
+  readonly cellInserted: "cellInserted";
+  readonly cellDeleted: "cellDeleted";
+  readonly cellMerged: "cellMerged";
+  readonly paragraphMarkInserted: "paragraphMarkInserted";
+  readonly paragraphMarkDeleted: "paragraphMarkDeleted";
+  readonly paragraphPropertiesChanged: "paragraphPropertiesChanged";
+  readonly sectionPropertiesChanged: "sectionPropertiesChanged";
+  readonly tablePropertiesChanged: "tablePropertiesChanged";
+  readonly rowPropertiesChanged: "rowPropertiesChanged";
+  readonly cellPropertiesChanged: "cellPropertiesChanged";
+}>;
 /** A tracked change discovered in the document body. */
 type FolioReviewChange = {
   /**
@@ -44,4 +69,4 @@ declare const getTrackedChangesFromDoc: (doc: Node) => FolioReviewChange[];
  */
 declare const getCommentAnchorsFromDoc: (doc: Node) => FolioCommentAnchor[];
 //#endregion
-export { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };
+export { FOLIO_REVIEW_CHANGE_KINDS, FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };

package/dist/ai-edits/read.js

@@ -3,6 +3,31 @@ import { getFolioNodeRevisionCarriers } from "../prosemirror/revisionCarriers.js
 import { getTableCellMergeChange } from "../prosemirror/tableCellMergeRevision.js";
 import { createFolioAIEditSnapshot } from "./snapshot.js";
 //#region src/ai-edits/read.ts
+/**
+* Runtime census of every tracked-change discriminator the reviewer exposes.
+*
+* The total Record is intentional: adding a new FolioReviewChangeKind without
+* adding it here is a compile-time error. Cross-product persistence tests use
+* this census, so a newly modeled revision cannot silently miss the resolver
+* and serialization matrix.
+*/
+const FOLIO_REVIEW_CHANGE_KINDS = Object.freeze({
+	insertion: "insertion",
+	deletion: "deletion",
+	formatting: "formatting",
+	rowInserted: "rowInserted",
+	rowDeleted: "rowDeleted",
+	cellInserted: "cellInserted",
+	cellDeleted: "cellDeleted",
+	cellMerged: "cellMerged",
+	paragraphMarkInserted: "paragraphMarkInserted",
+	paragraphMarkDeleted: "paragraphMarkDeleted",
+	paragraphPropertiesChanged: "paragraphPropertiesChanged",
+	sectionPropertiesChanged: "sectionPropertiesChanged",
+	tablePropertiesChanged: "tablePropertiesChanged",
+	rowPropertiesChanged: "rowPropertiesChanged",
+	cellPropertiesChanged: "cellPropertiesChanged"
+});
 /** Map each snapshot block's start position to its stable id. */
 const blockStartIdsFromDoc = (doc) => {
 	const starts = /* @__PURE__ */ new Map();
@@ -214,4 +239,4 @@ const getCommentAnchorsFromDoc = (doc) => {
 	return [...anchors.values()];
 };
 //#endregion
-export { getCommentAnchorsFromDoc, getTrackedChangesFromDoc };
+export { FOLIO_REVIEW_CHANGE_KINDS, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };

package/dist/docx/rezip.d.ts

@@ -25,6 +25,8 @@ type RepackOptions = {
   updateModifiedDate?: boolean;
   /** Custom modifier name for lastModifiedBy */
   modifiedBy?: string;
+  /** Changed note paragraphs that must be serialized even without source paraIds. */
+  changedNoteParaIds?: ReadonlySet<string>;
 };
 /**
  * Repack a Document into a valid DOCX file

package/dist/docx/rezip.js

@@ -6,7 +6,7 @@ import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
 import { parseNumbering } from "./numberingParser.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
-import { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
+import { appendNumberingDefs, buildPatchedNotePartXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
 import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeFontTableXml } from "./serializer/fontTableSerializer.js";
@@ -434,7 +434,7 @@ const cloneDocxZip = (source) => {
 	clone.files = { ...source.files };
 	return clone;
 };
-const finishRepack = async ({ document, originalZip, outputZip, originalDocumentXml, originalCorePropertiesXml, compressionLevel, updateModifiedDate, modifiedBy }) => {
+const finishRepack = async ({ document, originalZip, outputZip, originalDocumentXml, originalCorePropertiesXml, compressionLevel, updateModifiedDate, modifiedBy, changedNoteParaIds }) => {
 	await materializeNewHeaderFooterParts(document, outputZip, compressionLevel);
 	const parts = collectDocxParts(document, outputZip);
 	await processNewImages(parts, outputZip, compressionLevel);
@@ -449,7 +449,13 @@ const finishRepack = async ({ document, originalZip, outputZip, originalDocument
 	});
 	await rebindWatermarkRelIds(document, outputZip, compressionLevel);
 	serializeHeadersFootersToZip(document, outputZip, compressionLevel);
-	await serializeNotesToZip(document, originalZip, outputZip, compressionLevel);
+	await serializeNotesToZip({
+		doc: document,
+		originalZip,
+		newZip: outputZip,
+		compressionLevel,
+		changedNoteParaIds
+	});
 	await serializeNumberingIntoZip(document, originalZip, outputZip, compressionLevel);
 	await serializeAddedStylesIntoZip(document, originalZip, outputZip, compressionLevel);
 	await serializeCommentsToZip(document, outputZip, compressionLevel);
@@ -475,7 +481,7 @@ const finishRepack = async ({ document, originalZip, outputZip, originalDocument
 */
 async function repackDocx(doc, options = {}) {
 	if (!doc.originalBuffer) panic("Cannot repack document: no original buffer for round-trip. Use createDocx() for new documents.");
-	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy } = options;
+	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy, changedNoteParaIds } = options;
 	const exportDocument = withoutOrphanCommentRanges(doc);
 	const originalZip = await JSZip.loadAsync(doc.originalBuffer);
 	const [originalDocumentXml, originalCorePropertiesXml] = await Promise.all([originalZip.file("word/document.xml")?.async("text"), originalZip.file("docProps/core.xml")?.async("text")]);
@@ -489,7 +495,8 @@ async function repackDocx(doc, options = {}) {
 		originalCorePropertiesXml,
 		compressionLevel,
 		updateModifiedDate,
-		...modifiedBy !== void 0 ? { modifiedBy } : {}
+		...modifiedBy !== void 0 ? { modifiedBy } : {},
+		...changedNoteParaIds !== void 0 ? { changedNoteParaIds } : {}
 	});
 }
 /**
@@ -501,7 +508,7 @@ async function repackDocx(doc, options = {}) {
 * @returns Promise resolving to DOCX as ArrayBuffer
 */
 async function repackDocxFromRaw(doc, rawContent, options = {}) {
-	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy } = options;
+	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy, changedNoteParaIds } = options;
 	const exportDocument = withoutOrphanCommentRanges(doc);
 	const newZip = new JSZip();
 	for (const [path, file] of Object.entries(rawContent.originalZip.files)) {
@@ -530,7 +537,13 @@ async function repackDocxFromRaw(doc, rawContent, options = {}) {
 	});
 	await rebindWatermarkRelIds(exportDocument, newZip, compressionLevel);
 	serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
-	await serializeNotesToZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
+	await serializeNotesToZip({
+		doc: exportDocument,
+		originalZip: rawContent.originalZip,
+		newZip,
+		compressionLevel,
+		changedNoteParaIds
+	});
 	await serializeNumberingIntoZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
 	await serializeAddedStylesIntoZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
 	await serializeCommentsToZip(exportDocument, newZip, compressionLevel);
@@ -1001,27 +1014,19 @@ function serializeHeadersFootersToZip(doc, zip, compressionLevel) {
 		compressionOptions
 	});
 }
-/**
-* Write edited footnote/endnote bodies into the repacked ZIP.
-*
-* The full repack rebuilds document.xml from the model, but note parts are
-* preserved from the original ZIP: the model only retains the normal notes, so
-* re-emitting the whole part would drop the separator / continuationSeparator
-* notes Word requires. Instead each edited note paragraph is spliced by `paraId`
-* into the ORIGINAL part, so an edited note gets the model content while
-* separators and every unedited note stay byte-exact.
-*
-* Full repack has no change-tracking signal, so "edited" is detected by
-* comparing the current model's note serialization against a BASELINE that
-* re-parses and re-serializes the original part. Both go through the same
-* (lossy) parse+serialize — e.g. the in-note `w:footnoteRef` auto-number mark
-* the model does not represent is dropped on both sides — so an unedited note
-* matches its baseline and is left verbatim (mark intact); only a genuine body
-* edit differs and is spliced.
-*/
-async function serializeNotesToZip(doc, originalZip, newZip, compressionLevel) {
+async function serializeNotesToZip({ doc, originalZip, newZip, compressionLevel, changedNoteParaIds }) {
 	const footnotes = doc.package.footnotes ?? [];
-	if (footnotes.length > 0) if (findNotePartEntry(originalZip, "word/footnotes.xml")) await patchNotePartIntoZip("word/footnotes.xml", serializeFootnotes(footnotes), (xml) => serializeFootnotes(parseFootnotes(xml).getNormalFootnotes()), originalZip, newZip, compressionLevel);
+	if (footnotes.length > 0) if (findNotePartEntry(originalZip, "word/footnotes.xml")) await patchNotePartIntoZip({
+		conventionalLowerPath: "word/footnotes.xml",
+		currentXml: serializeFootnotes(footnotes),
+		replacementXml: serializeNewFootnotesPart(footnotes),
+		baselineFrom: (xml) => serializeFootnotes(parseFootnotes(xml).getNormalFootnotes()),
+		elementName: "footnote",
+		changedNoteParaIds,
+		originalZip,
+		newZip,
+		compressionLevel
+	});
 	else await materializeNewNotePart({
 		contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml",
 		newZip,
@@ -1031,7 +1036,17 @@ async function serializeNotesToZip(doc, originalZip, newZip, compressionLevel) {
 		compressionLevel
 	});
 	const endnotes = doc.package.endnotes ?? [];
-	if (endnotes.length > 0) if (findNotePartEntry(originalZip, "word/endnotes.xml")) await patchNotePartIntoZip("word/endnotes.xml", serializeEndnotes(endnotes), (xml) => serializeEndnotes(parseEndnotes(xml).getNormalEndnotes()), originalZip, newZip, compressionLevel);
+	if (endnotes.length > 0) if (findNotePartEntry(originalZip, "word/endnotes.xml")) await patchNotePartIntoZip({
+		conventionalLowerPath: "word/endnotes.xml",
+		currentXml: serializeEndnotes(endnotes),
+		replacementXml: serializeNewEndnotesPart(endnotes),
+		baselineFrom: (xml) => serializeEndnotes(parseEndnotes(xml).getNormalEndnotes()),
+		elementName: "endnote",
+		changedNoteParaIds,
+		originalZip,
+		newZip,
+		compressionLevel
+	});
 	else await materializeNewNotePart({
 		contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml",
 		newZip,
@@ -1134,44 +1149,32 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		compressionOptions: { level: compressionLevel }
 	});
 }
-async function patchNotePartIntoZip(conventionalLowerPath, currentXml, baselineFrom, originalZip, newZip, compressionLevel) {
+async function patchNotePartIntoZip({ conventionalLowerPath, currentXml, replacementXml, baselineFrom, elementName, changedNoteParaIds, originalZip, newZip, compressionLevel }) {
 	const file = findNotePartEntry(originalZip, conventionalLowerPath);
 	if (!file) return;
 	const originalXml = await file.async("text");
-	const changedIds = collectChangedNoteParaIds(baselineFrom(originalXml), currentXml);
-	if (changedIds.size === 0) return;
-	const patched = buildPatchedNoteXml(originalXml, currentXml, changedIds);
-	if (patched === null) return;
+	const baselineXml = baselineFrom(originalXml);
+	const effectiveChangedNoteParaIds = changedNoteParaIds ?? collectChangedNoteParaIds(baselineXml, currentXml);
+	const patched = buildPatchedNotePartXml({
+		originalXml,
+		baselineXml,
+		serializedXml: currentXml,
+		replacementXml,
+		elementName,
+		changedParaIds: effectiveChangedNoteParaIds
+	});
+	const currentParaIds = collectParaIds(currentXml);
+	const hasDirtyParagraph = [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId));
+	if (patched === null || hasDirtyParagraph && patched === originalXml) {
+		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${file.name}`);
+		return;
+	}
+	if (patched === originalXml) return;
 	newZip.file(file.name, patched, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
 }
-/**
-* The note paragraphs whose current serialization differs from the baseline
-* (re-parsed original) serialization — i.e. the ones actually edited. A
-* paragraph is only considered when its `paraId` resolves uniquely in both,
-* so it can be spliced safely.
-*
-* Builds one {@link buildParagraphOffsetIndex} per side (a single linear scan
-* each) instead of calling `extractParagraphXml` per candidate id, which
-* re-scanned the whole XML per id — O(note count * XML size) for a document
-* with many footnotes/endnotes. The index turns each lookup below into O(1).
-*/
-function collectChangedNoteParaIds(baselineXml, currentXml) {
-	const changed = /* @__PURE__ */ new Set();
-	const baselineIds = collectParaIds(baselineXml);
-	const baselineOffsets = buildParagraphOffsetIndex(baselineXml);
-	const currentOffsets = buildParagraphOffsetIndex(currentXml);
-	for (const [id, count] of collectParaIds(currentXml)) {
-		if (count !== 1 || baselineIds.get(id) !== 1) continue;
-		const beforeRange = baselineOffsets.get(id);
-		const afterRange = currentOffsets.get(id);
-		if (!beforeRange || !afterRange) continue;
-		if (baselineXml.slice(beforeRange.start, beforeRange.end) !== currentXml.slice(afterRange.start, afterRange.end)) changed.add(id);
-	}
-	return changed;
-}
 /** `word/Footnotes.xml` -> `word/_rels/Footnotes.xml.rels` (casing preserved). */
 function notePartRelsPath(partPath) {
 	const lastSlash = partPath.lastIndexOf("/");

package/dist/docx/selectiveXmlPatch.d.ts

@@ -109,6 +109,29 @@ declare function buildPatchedDocumentXml(originalXml: string, serializedXml: str
  * the caller can fall back to preserving the original part verbatim.
  */
 declare function buildPatchedNoteXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+type NoteElementName = "footnote" | "endnote";
+declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
+type BuildPatchedNotePartXmlOptions = {
+  originalXml: string;
+  baselineXml: string;
+  serializedXml: string;
+  replacementXml: string;
+  elementName: NoteElementName;
+  changedParaIds?: ReadonlySet<string>;
+};
+/**
+ * Patch an existing note part from its model serialization.
+ *
+ * Dirty paragraph ids locate their owning note in the model serialization;
+ * `(note w:id, paragraph ordinal)` then locates the corresponding source XML
+ * even when the producer omitted paragraph ids. Equal-shape edits replace only
+ * dirty paragraphs. A tracked paragraph-break resolution can change that
+ * shape, so it replaces the one affected note. Separator notes, unrelated
+ * notes, and unaffected equal-shape paragraphs remain byte-exact.
+ * `replacementXml` also supplies synthesized automatic note-reference marks,
+ * which the parsed model intentionally omits.
+ */
+declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): string | null;
 type ChangedNumberingDefs = {
   abstractNums: Set<string>;
   nums: Set<string>;
@@ -148,4 +171,4 @@ declare function collectAddedNumberingDefs(baselineXml: string, currentXml: stri
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };
+export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };

package/dist/docx/selectiveXmlPatch.js

@@ -1,3 +1,4 @@
+import { WORDPROCESSINGML_NAMESPACE_URIS, findAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.ts
 /**
 * Selective XML Patch Module
@@ -317,6 +318,190 @@ function extractElementByIdAttr(xml, openLiteral, closeTag, idAttr, id) {
 	const offsets = findElementByIdAttr(xml, openLiteral, closeTag, idAttr, id);
 	return offsets ? xml.slice(offsets.start, offsets.end) : null;
 }
+const qualifiedName = (prefix, localName) => prefix.length === 0 ? localName : `${prefix}:${localName}`;
+const collectNoteElementSyntax = (xml, elementName) => {
+	const byId = /* @__PURE__ */ new Map();
+	const root = parseXmlDocument(xml);
+	for (const element of getChildElements(root)) {
+		if (getLocalName(element.name) !== elementName || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "")) continue;
+		const idAttribute = findAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "id");
+		if (!element.name || !idAttribute) continue;
+		const syntax = {
+			elementName: element.name,
+			idAttributeName: idAttribute.name,
+			elementPrefix: getNamespacePrefix(element.name) ?? "",
+			attributePrefix: getNamespacePrefix(idAttribute.name) ?? ""
+		};
+		const entries = byId.get(idAttribute.value);
+		if (entries) entries.push(syntax);
+		else byId.set(idAttribute.value, [syntax]);
+	}
+	return byId;
+};
+const syntaxLiteral = (syntax) => ({
+	openLiteral: `<${syntax.elementName}`,
+	closeTag: `</${syntax.elementName}>`,
+	idAttr: syntax.idAttributeName
+});
+const extractNoteElement = (xml, syntax, id) => {
+	const { openLiteral, closeTag, idAttr } = syntaxLiteral(syntax);
+	return extractElementByIdAttr(xml, openLiteral, closeTag, idAttr, id);
+};
+const findNoteElement = (xml, syntax, id) => {
+	const { openLiteral, closeTag, idAttr } = syntaxLiteral(syntax);
+	return findElementByIdAttr(xml, openLiteral, closeTag, idAttr, id);
+};
+const rewriteWordprocessingPrefixes = (xml, { source, target, sourceXmlnsDeclarations }) => {
+	let rewritten = "";
+	let quote = null;
+	let insideTag = false;
+	for (let index = 0; index < xml.length; index++) {
+		const character = xml[index];
+		if (!insideTag) {
+			rewritten += character;
+			insideTag = character === "<";
+			continue;
+		}
+		if (quote) {
+			rewritten += character;
+			if (character === quote) quote = null;
+			continue;
+		}
+		if (character === "\"" || character === "'") {
+			quote = character;
+			rewritten += character;
+			continue;
+		}
+		if (character === ">") {
+			insideTag = false;
+			rewritten += character;
+			continue;
+		}
+		const previous = xml[index - 1];
+		const isElementName = previous === "<" || previous === "/" && xml[index - 2] === "<";
+		const sourcePrefix = isElementName ? source.elementPrefix : source.attributePrefix;
+		if (sourcePrefix.length > 0 && xml.startsWith(`${sourcePrefix}:`, index)) {
+			const targetPrefix = isElementName ? target.elementPrefix : target.attributePrefix;
+			rewritten += targetPrefix.length === 0 ? "" : `${targetPrefix}:`;
+			index += sourcePrefix.length;
+			continue;
+		}
+		rewritten += character;
+	}
+	return withXmlnsDeclarations(rewritten, sourceXmlnsDeclarations);
+};
+const paragraphRanges = (xml, wordPrefix) => {
+	const ranges = [];
+	const paragraphName = qualifiedName(wordPrefix, "p");
+	const openLiteral = `<${paragraphName}`;
+	const closeTag = `</${paragraphName}>`;
+	let pos = 0;
+	while (pos < xml.length) {
+		const start = xml.indexOf(openLiteral, pos);
+		if (start === -1) break;
+		if (!isXmlNameBoundary(xml[start + openLiteral.length])) {
+			pos = start + 1;
+			continue;
+		}
+		const range = scanElementRange(xml, start, openLiteral, closeTag);
+		if (!range) break;
+		ranges.push(range);
+		pos = range.end;
+	}
+	return ranges;
+};
+const collectChangedNoteParaIds = (baselineXml, currentXml) => {
+	const changed = /* @__PURE__ */ new Set();
+	const baselineIds = collectParaIds(baselineXml);
+	const baselineOffsets = buildParagraphOffsetIndex(baselineXml);
+	const currentOffsets = buildParagraphOffsetIndex(currentXml);
+	for (const [id, count] of collectParaIds(currentXml)) {
+		if (count !== 1 || baselineIds.get(id) !== 1) continue;
+		const before = baselineOffsets.get(id);
+		const after = currentOffsets.get(id);
+		if (before && after && baselineXml.slice(before.start, before.end) !== currentXml.slice(after.start, after.end)) changed.add(id);
+	}
+	return changed;
+};
+const replaceRanges = (xml, replacements) => {
+	let result = xml;
+	for (const { start, end, newXml } of [...replacements].toSorted((a, b) => b.start - a.start)) result = result.slice(0, start) + newXml + result.slice(end);
+	return result;
+};
+/**
+* Patch an existing note part from its model serialization.
+*
+* Dirty paragraph ids locate their owning note in the model serialization;
+* `(note w:id, paragraph ordinal)` then locates the corresponding source XML
+* even when the producer omitted paragraph ids. Equal-shape edits replace only
+* dirty paragraphs. A tracked paragraph-break resolution can change that
+* shape, so it replaces the one affected note. Separator notes, unrelated
+* notes, and unaffected equal-shape paragraphs remain byte-exact.
+* `replacementXml` also supplies synthesized automatic note-reference marks,
+* which the parsed model intentionally omits.
+*/
+function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }) {
+	const currentElements = collectNoteElementSyntax(serializedXml, elementName);
+	const originalElements = collectNoteElementSyntax(originalXml, elementName);
+	const replacementElements = collectNoteElementSyntax(replacementXml, elementName);
+	const replacementXmlnsDeclarations = collectXmlnsFromOpeningTag(replacementXml);
+	const ordinalReplacements = [];
+	const serializedParaIds = collectParaIds(serializedXml);
+	const effectiveChangedParaIds = changedParaIds ?? collectChangedNoteParaIds(baselineXml, serializedXml);
+	const unroutedChangedParaIds = new Set([...effectiveChangedParaIds].filter((paraId) => serializedParaIds.has(paraId)));
+	for (const [id, currentSyntaxEntries] of currentElements) {
+		const originalSyntaxEntries = originalElements.get(id);
+		const replacementSyntaxEntries = replacementElements.get(id);
+		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return null;
+		const currentSyntax = currentSyntaxEntries[0];
+		const originalSyntax = originalSyntaxEntries[0];
+		const replacementSyntax = replacementSyntaxEntries[0];
+		if (!currentSyntax || !originalSyntax || !replacementSyntax) return null;
+		const currentNote = extractNoteElement(serializedXml, currentSyntax, id);
+		const originalOffsets = findNoteElement(originalXml, originalSyntax, id);
+		const replacementNote = extractNoteElement(replacementXml, replacementSyntax, id);
+		if (!currentNote || !originalOffsets || !replacementNote) return null;
+		const originalNote = originalXml.slice(originalOffsets.start, originalOffsets.end);
+		const currentParagraphs = paragraphRanges(currentNote, currentSyntax.elementPrefix);
+		const originalParagraphs = paragraphRanges(originalNote, originalSyntax.elementPrefix);
+		const replacementParagraphs = paragraphRanges(replacementNote, replacementSyntax.elementPrefix);
+		const noteChangedParaIds = [...collectParaIds(currentNote).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
+		if (noteChangedParaIds.length === 0) continue;
+		if (currentParagraphs.length !== originalParagraphs.length || currentParagraphs.length !== replacementParagraphs.length) {
+			for (const paraId of noteChangedParaIds) unroutedChangedParaIds.delete(paraId);
+			ordinalReplacements.push({
+				start: originalOffsets.start,
+				end: originalOffsets.end,
+				newXml: rewriteWordprocessingPrefixes(replacementNote, {
+					source: replacementSyntax,
+					target: originalSyntax,
+					sourceXmlnsDeclarations: replacementXmlnsDeclarations
+				})
+			});
+			continue;
+		}
+		for (let index = 0; index < currentParagraphs.length; index++) {
+			const currentRange = currentParagraphs[index];
+			const originalRange = originalParagraphs[index];
+			const replacementRange = replacementParagraphs[index];
+			if (!currentRange || !originalRange || !replacementRange) return null;
+			const routedIds = [...collectParaIds(currentNote.slice(currentRange.start, currentRange.end)).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
+			if (routedIds.length === 0) continue;
+			for (const paraId of routedIds) unroutedChangedParaIds.delete(paraId);
+			ordinalReplacements.push({
+				start: originalOffsets.start + originalRange.start,
+				end: originalOffsets.start + originalRange.end,
+				newXml: rewriteWordprocessingPrefixes(replacementNote.slice(replacementRange.start, replacementRange.end), {
+					source: replacementSyntax,
+					target: originalSyntax,
+					sourceXmlnsDeclarations: replacementXmlnsDeclarations
+				})
+			});
+		}
+	}
+	if (unroutedChangedParaIds.size > 0) return null;
+	return replaceRanges(originalXml, ordinalReplacements);
+}
 /**
 * The full range of the first `<openLiteral …>…</closeTag>` element, or null.
 * Used to locate an unkeyed sub-element (a level's `mc:AlternateContent`).
@@ -627,4 +812,4 @@ function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 //#endregion
-export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };

package/dist/docx/xmlParser.d.ts

@@ -104,6 +104,12 @@ declare const WORDPROCESSINGML_NAMESPACE_URIS: ReadonlySet<string>;
  * from a foreign namespace is not accepted.
  */
 declare function findChildByNamespaceUri(parent: XmlElement | null | undefined, namespaceUris: ReadonlySet<string>, localName: string): XmlElement | null;
+type XmlAttributeMatch = {
+  name: string;
+  value: string;
+};
+/** Find an attribute whose prefix resolves to one of the accepted namespace URIs. */
+declare function findAttributeByNamespaceUri(element: XmlElement | null | undefined, namespaceUris: ReadonlySet<string>, localName: string): XmlAttributeMatch | null;
 /** Get an attribute whose prefix resolves to one of the accepted namespace URIs. */
 declare function getAttributeByNamespaceUri(element: XmlElement | null | undefined, namespaceUris: ReadonlySet<string>, localName: string): string | null;
 /**
@@ -338,4 +344,4 @@ declare function mergeXmlnsDeclarations(inherited: Record<string, string>, eleme
  */
 declare function cloneWithXmlnsDeclarations(element: XmlElement, xmlnsDecls: Record<string, string>): XmlElement;
 //#endregion
-export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, XmlElement, XmlNamespaceScope, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };
+export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/docx/xmlParser.js

@@ -208,16 +208,23 @@ function findChildByNamespaceUri(parent, namespaceUris, localName) {
 	for (const child of parent.elements) if (child.type === "element" && hasLocalName(child.name, localName) && namespaceUris.has(child.namespaceUri ?? "")) return child;
 	return null;
 }
-/** Get an attribute whose prefix resolves to one of the accepted namespace URIs. */
-function getAttributeByNamespaceUri(element, namespaceUris, localName) {
+/** Find an attribute whose prefix resolves to one of the accepted namespace URIs. */
+function findAttributeByNamespaceUri(element, namespaceUris, localName) {
 	if (!element?.attributes) return null;
 	for (const [name, value] of Object.entries(element.attributes)) {
 		if (value === void 0 || getLocalName(name) !== localName) continue;
 		const prefix = getNamespacePrefix(name);
-		if (prefix !== null && namespaceUris.has(resolveNamespaceUri(element.namespaceScope, prefix) ?? "")) return String(value);
+		if (prefix !== null && namespaceUris.has(resolveNamespaceUri(element.namespaceScope, prefix) ?? "")) return {
+			name,
+			value: String(value)
+		};
 	}
 	return null;
 }
+/** Get an attribute whose prefix resolves to one of the accepted namespace URIs. */
+function getAttributeByNamespaceUri(element, namespaceUris, localName) {
+	return findAttributeByNamespaceUri(element, namespaceUris, localName)?.value ?? null;
+}
 function hasLocalName(name, localName) {
 	if (!name) return false;
 	if (name === localName) return true;
@@ -712,4 +719,4 @@ function cloneWithXmlnsDeclarations(element, xmlnsDecls) {
 	return element;
 }
 //#endregion
-export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };
+export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/prosemirror/conversion/toProseDoc.js

@@ -216,15 +216,17 @@ const resolveParagraphStyleFontFamily = (styleId, styleResolver) => {
 };
 /**
 * Apply comment marks to PM nodes within a comment range.
-* Only the first active comment ID is used (comments don't overlap visually).
 */
 function applyCommentMarks(nodes, commentIds) {
 	if (commentIds.size === 0) return nodes;
-	const commentId = [...commentIds][0];
-	const commentMark = schema.marks["comment"].create({ commentId });
+	const commentMarkType = schema.marks["comment"];
+	if (!commentMarkType) return nodes;
+	const commentMarks = [...commentIds].toSorted((left, right) => left - right).map((commentId) => commentMarkType.create({ commentId }));
 	return nodes.map((node) => {
-		if (node.isText || node.isInline && node.type.allowsMarkType(commentMark.type)) return node.mark(commentMark.addToSet(node.marks));
-		return node;
+		if (!node.isText && (!node.isInline || !node.type.allowsMarkType(commentMarkType))) return node;
+		let marks = node.marks;
+		for (const commentMark of commentMarks) marks = commentMark.addToSet(marks);
+		return node.mark(marks);
 	});
 }
 function anchorPointComment(nodes, commentId) {

package/dist/prosemirror/extensions/marks/CommentExtension.js

@@ -11,6 +11,7 @@ const CommentExtension = createMarkExtension({
 	name: "comment",
 	schemaMarkName: "comment",
 	markSpec: {
+		excludes: "",
 		attrs: { 
 		/** Comment ID (matches Comment.id) */
 commentId: { default: 0 } },

package/package.json

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