@stll/folio-core 0.59.0 → 0.61.0

package/README.md

@@ -20,9 +20,18 @@ Part of [stella](https://github.com/stella/stella), an open-source legal workspa
 ## Install
 
 ```sh
-bun add @stll/folio-core
+bun add @stll/folio-core \
+  prosemirror-commands@^1.7.1 prosemirror-dropcursor@^1.8.2 prosemirror-gapcursor@^1.4.1 prosemirror-history@^1.5.0 \
+  prosemirror-inputrules@^1.5.0 prosemirror-keymap@^1.2.3 prosemirror-model@^1.25.9 prosemirror-state@^1.4.4 \
+  prosemirror-tables@^1.8.5 prosemirror-transform@^1.12.0 prosemirror-view@^1.42.6 y-prosemirror@^1.3.7 \
+  y-protocols@^1.0.6 yjs@^13.6.31
 ```
 
+ProseMirror and Yjs packages are required peers, including the collaboration
+packages `y-prosemirror` and `y-protocols`. Install one compatible copy of each in the host
+application so schemas, plugins, editor states, and collaborative documents share
+the same runtime. The command above includes the complete editor peer closure.
+
 ## Exports
 
 | Import                      | What it is                                                                                                                                                         |
@@ -33,6 +42,19 @@ bun add @stll/folio-core
 | `@stll/folio-core/redline`  | Compare two `.docx` buffers and generate a native Word redline                                                                                                     |
 | `@stll/folio-core/*`        | the source-mirrored module tree (e.g. `@stll/folio-core/types/document`, `@stll/folio-core/prosemirror/schema`) for adapters that need lower-level building blocks |
 
+## Review display configuration
+
+`ReviewDisplayMode` is `all-markup | final | original`.
+`reviewDisplayModeToDisplayMode` in `managers/reviewDisplayMode` maps it to the
+layout pipeline's `markupView` input. The shared projection reuses the
+accept-all/reject-all resolver without changing editor state. Layout and
+search consume that projection; saved DOCX always uses the authored state.
+`getEditorReadOnlyReason` in `managers/EditorModeManager` makes projected review
+views read-only. Both adapters expose the resulting `EditorReadOnlyReason`
+through `getReadOnlyReason()` and `onReadonlyEditAttempt(reason)`.
+`showCommentHighlights` on the layout pipeline defaults to `true`; final
+(`no-markup`) and original suppress comment highlights regardless of it.
+
 ## New documents and reusable style sets
 
 Create a legal-shaped blank document with the built-in preset:

package/dist/ai-edits/apply.js

@@ -11,6 +11,7 @@ import { encloseWholeControls } from "../prosemirror/contentControlRevisions.js"
 import { JOINED_RUNS_RESTYLED_META } from "../prosemirror/extensions/features/JoinedRunStyleExtension.js";
 import { requestDeterministicParaIds } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
 import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
+import "../prosemirror/extensions/nodes/RangeAnchorExtension.js";
 import "../prosemirror/extensions/nodes/TextBoxAnchorExtension.js";
 import { CLEARED_LIST_RENDERING_ATTRS } from "../prosemirror/listMarker.js";
 import { effectiveParagraphNumbering, paragraphNumberingAttr, paragraphNumberingSourcesFromBoundary, readParagraphNumberingAttr, removedNumberingAttr } from "../prosemirror/numberingAttr.js";
@@ -23,11 +24,12 @@ import { directParagraphSpacing, paragraphSpacingAttrPatch, paragraphSpacingEqua
 import { getDocumentNumbering, getDocumentNumberingInstanceIds } from "../prosemirror/plugins/documentNumbering.js";
 import { getDocumentStyleDefinitions, getDocumentStyleResolver } from "../prosemirror/plugins/documentStyleState.js";
 import { claimRevisionIds, nextRevisionId, nextRevisionIdRange, reserveRevisionIds, seedRevisionIdsFromDoc } from "../prosemirror/plugins/revisionIds.js";
+import { readRangeAnchorAttrs } from "../prosemirror/rangeAnchorAttrs.js";
 import { rebaseParagraphRuns } from "../prosemirror/rebaseParagraphRuns.js";
-import { NON_INCLUSIVE_MARK_DISPOSITION, addCarriedMarks, annotatedReplacement, commentsAcrossBlockBoundary, commentsForTrackedInsertion, hasReplacedAnnotations, inheritedReplacementMarks, placeTrackedInsertion, surveyReplacedAnnotations } from "../prosemirror/replacedAnnotations.js";
+import { NON_INCLUSIVE_MARK_DISPOSITION, addCarriedMarks, annotatedReplacement, commentPoint, commentsAcrossBlockBoundary, commentsForTrackedInsertion, hasReplacedAnnotations, inheritedReplacementMarks, placeTrackedInsertion, surveyReplacedAnnotations } from "../prosemirror/replacedAnnotations.js";
 import { applyMarksToRunFormattingRepresentation, runFormattingInlineControlNodeName, selectRunFormattingCarrierRepresentations } from "../prosemirror/runFormattingInlineCarriers.js";
 import { RUN_FORMATTING_MARK_NAMES } from "../prosemirror/runFormattingMarkNames.js";
-import { readAuthoredRunFormatting, reconcileRunFormattingMarks } from "../prosemirror/runFormattingReconciliation.js";
+import { readAuthoredRunFormatting, readAuthoredRunPropertySnapshot, reconcileRunFormattingMarks } from "../prosemirror/runFormattingReconciliation.js";
 import { paragraphRunStyleContext, paragraphRunStyleContextAt, resolveParagraphBodyRunFormatting } from "../prosemirror/runStyleFormatting.js";
 import { sectionPropertiesOf } from "../prosemirror/sectionCarrier.js";
 import { listAttrsFromNumbering, listLevelAttrPatch, listLevelIndentRemovalPatch } from "../prosemirror/styles/resolvedStyleAttrs.js";
@@ -788,12 +790,12 @@ const applyTrackedInlineFormattingToRanges = ({ tr, schema, doc = tr.doc, ranges
 			pos: representation.from,
 			...styleResolver !== void 0 ? { styleResolver } : {}
 		});
-		const previousFormatting = readAuthoredRunFormatting({
+		const previousFormatting = readAuthoredRunPropertySnapshot({
 			context: styleContext,
 			marks: node.marks,
 			...styleResolver !== void 0 ? { styleResolver } : {}
 		});
-		const includedProperties = formattingChangesForAuthoredFormatting(previousFormatting, formatting);
+		const includedProperties = formattingChangesForAuthoredFormatting(previousFormatting ?? {}, formatting);
 		if (includedProperties.length === 0) continue;
 		const existingMark = node.marks.find((mark) => mark.type === propertyChangeType);
 		if (existingMark && expectRunPropertyChangeMarkAttrs(existingMark).changes.length > 0) {
@@ -802,7 +804,7 @@ const applyTrackedInlineFormattingToRanges = ({ tr, schema, doc = tr.doc, ranges
 		}
 		const formattingMarks = reconcileRunFormattingMarks({
 			authoredFormatting: patchAuthoredRunFormatting({
-				authoredFormatting: previousFormatting,
+				authoredFormatting: previousFormatting ?? {},
 				formatting,
 				includedProperties
 			}),
@@ -845,7 +847,7 @@ const applyTrackedInlineFormattingToRanges = ({ tr, schema, doc = tr.doc, ranges
 				date,
 				...initials ? { initials } : {}
 			},
-			...Object.keys(segment.previousFormatting).length > 0 ? { previousFormatting: segment.previousFormatting } : {}
+			...segment.previousFormatting !== void 0 ? { previousFormatting: segment.previousFormatting } : {}
 		};
 		const marks = propertyChangeType.create({
 			changes: [change],
@@ -1353,12 +1355,12 @@ const isPendingDeletion = (doc, blockFrom, paragraph, cleanText) => {
 	return false;
 };
 /** Whether every piece of the paragraph's content is pending inserted text. */
-const holdsOnlyInsertedContent = (paragraph) => {
+const holdsOnlyInsertedContent = (paragraph, revisions) => {
 	let whollyInserted = true;
 	paragraph.descendants((node) => {
 		if (!whollyInserted) return false;
 		if (!node.isInline || isZeroWidthAnchor(node)) return true;
-		whollyInserted = node.marks.some((mark) => mark.type.name === "insertion" && mark.attrs["moveKind"] !== "moveTo");
+		whollyInserted = node.marks.some((mark) => mark.type.name === "insertion" && (revisions === "including-moves" || mark.attrs["moveKind"] !== "moveTo"));
 		return false;
 	});
 	return whollyInserted;
@@ -1376,11 +1378,16 @@ const holdsOnlyInsertedContent = (paragraph) => {
 */
 const pendingParagraphRetraction = (doc, position) => {
 	const paragraph = doc.nodeAt(position);
-	if (paragraph?.type.name !== "paragraph" || !holdsOnlyInsertedContent(paragraph)) return null;
+	if (paragraph?.type.name !== "paragraph") return null;
 	const at = doc.resolve(position);
 	const before = at.nodeBefore;
 	const endsItsContainer = paragraphEndsItsContainer(at, paragraph.type.name);
 	if (at.parent.childCount < 2 || endsItsContainer && before?.type.name !== paragraph.type.name) return null;
+	let followingIndex = at.index() + 1;
+	while (at.parent.maybeChild(followingIndex)?.type.name === "blockBookmarkBoundary") followingIndex++;
+	const following = at.parent.maybeChild(followingIndex);
+	if (expectParagraphAttrs(paragraph).pPrMark?.kind === "moveTo" && following?.type.spec["tableRole"] === "table" && holdsOnlyInsertedContent(paragraph, "including-moves")) return { clearBreakAt: null };
+	if (!holdsOnlyInsertedContent(paragraph, "ordinary")) return null;
 	if (isInsertedPPrMark(paragraph.attrs["pPrMark"]) || isSuggestedParagraphInsert(paragraph)) return { clearBreakAt: null };
 	if (endsItsContainer && before && paragraph.attrs["pPrMark"] == null) return isInsertedPPrMark(before.attrs["pPrMark"]) ? { clearBreakAt: position - before.nodeSize } : null;
 	return null;
@@ -1596,7 +1603,7 @@ const hasDeferredParagraphPropertyWrite = ({ tr, deletions, targets, mergedPrope
 		})) continue;
 		const writeTarget = mark == null ? target : tr.doc.nodeAt(predecessor.position + predecessor.node.nodeSize);
 		if (!writeTarget || !targets.includes(writeTarget)) continue;
-		if (mark != null && !(isInsertedPPrMark(mark) && canRetractFinalBreak({
+		if (mark != null && !(addedBreakRevisionId(mark) !== null && canRetractFinalBreak({
 			predecessor: predecessor.node,
 			target: writeTarget
 		}))) continue;
@@ -1629,7 +1636,7 @@ const paragraphPropertyRevisionTargets = ({ item, tr, deletedFinalParagraphs })
 	for (const deletion of deletedFinalParagraphs) {
 		const at = tr.mapping.slice(deletion.mappedFrom).map(deletion.position);
 		const predecessor = finalParagraphPredecessor(tr.doc, at);
-		if (!predecessor || !isInsertedPPrMark(predecessor.node.attrs["pPrMark"])) continue;
+		if (!predecessor || addedBreakRevisionId(predecessor.node.attrs["pPrMark"]) === null) continue;
 		const target = tr.doc.nodeAt(predecessor.position + predecessor.node.nodeSize);
 		if (!target) continue;
 		if (canRetractFinalBreak({
@@ -1727,7 +1734,7 @@ const withRetiredFinalParagraphs = ({ tr, deletions, mergedPropertyTargets, appl
 			});
 			continue;
 		}
-		if (isInsertedPPrMark(mark)) {
+		if (addedBreakRevisionId(mark) !== null) {
 			const following = tr.doc.nodeAt(position + previous.nodeSize);
 			if (!following || !canRetractFinalBreak({
 				predecessor: previous,
@@ -1777,10 +1784,10 @@ const withRetiredFinalParagraphs = ({ tr, deletions, mergedPropertyTargets, appl
 /**
 * Move an ADDED paragraph break off every paragraph its container ends with.
 *
-* A container's final mark carries no revision in either direction: nothing
-* follows it, so "join this paragraph with the one after it" and its mirror
-* both state an edit that cannot be carried out, and a reader is left with a
-* revision neither accepting nor rejecting everything can clear.
+* Prefer a preceding carrier so rejection can join the inserted content back
+* over its added boundary. When no carrier is free, the insertion keeps its
+* own mark: the resolver can remove that whole paragraph when its text is
+* rejected, while a markless empty paragraph would have no insertion owner.
 *
 * Appending at a container's end therefore rotates exactly as removing from it
 * does. The first inserted break moves onto the paragraph the run was appended
@@ -1806,7 +1813,9 @@ const withRetiredFinalParagraphs = ({ tr, deletions, mergedPropertyTargets, appl
 * paragraph's words run into the one after it, which ends with the free mark,
 * and neither break is left to resolve.
 */
-const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, author, date, initials, styleResolver }) => {
+const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, author, date, initials, styleResolver, numbering }) => {
+	let nextRevisionId = revisionSeed;
+	const synthesizedRevisions = [];
 	const supersededDeletedBreaks = [];
 	const collectSupersededDeletedBreaks = (parent, contentStart) => {
 		let previous = null;
@@ -1824,7 +1833,7 @@ const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, autho
 				const trackedInsertion = insertedRevisionId !== null && batchRevisionIds.has(insertedRevisionId);
 				const suggestedInsertion = isSuggestedParagraphInsert(node);
 				const deletedBreakRevisionId = addedOrDeletedBreakRevisionId(deletedMark);
-				if (isPlainDeletedPPrMark(deletedMark) && deletedBreakRevisionId !== null && !batchRevisionIds.has(deletedBreakRevisionId) && !holdsOnlyDeletedContent(previous.node) && (trackedInsertion || suggestedInsertion) && holdsOnlyInsertedContent(node)) supersededDeletedBreaks.push({
+				if (isPlainDeletedPPrMark(deletedMark) && deletedBreakRevisionId !== null && !batchRevisionIds.has(deletedBreakRevisionId) && !holdsOnlyDeletedContent(previous.node) && (trackedInsertion || suggestedInsertion) && holdsOnlyInsertedContent(node, "ordinary")) supersededDeletedBreaks.push({
 					preceding: previous.position,
 					inserted: position,
 					deletedMark,
@@ -1859,6 +1868,33 @@ const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, autho
 		}
 		tr.setNodeAttribute(preceding, "pPrMark", precedingMark);
 		tr.setNodeAttribute(inserted, "pPrMark", deletedMark);
+		if (insertionRevisionId === null) continue;
+		const source = tr.doc.nodeAt(inserted);
+		const survivor = paragraphLeftAfter({
+			doc: tr.doc,
+			paragraphPos: inserted
+		});
+		if (!source || survivor === null) continue;
+		const revisionId = nextRevisionId;
+		if (carryParagraphProperties({
+			tr,
+			position: survivor,
+			source,
+			styleResolver,
+			numbering,
+			revision: {
+				id: revisionId,
+				author,
+				date,
+				...initials ? { initials } : {}
+			}
+		}).tracked) {
+			nextRevisionId++;
+			synthesizedRevisions.push({
+				ownerRevisionId: insertionRevisionId,
+				revisionId
+			});
+		}
 	}
 	const paragraphTypeName = tr.doc.type.schema.nodes["paragraph"]?.name ?? "paragraph";
 	const rotations = finalParagraphsOf(tr.doc, paragraphTypeName).flatMap(({ node, position }) => {
@@ -1872,16 +1908,11 @@ const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, autho
 		}] : [];
 	}).toSorted((left, right) => right.position - left.position);
 	let next = tr;
-	let nextRevisionId = revisionSeed;
-	const synthesizedRevisions = [];
 	const retractedRevisionIds = [];
 	for (const { position: finalPosition, node: final, mark: finalMark } of rotations) {
 		const resolved = next.doc.resolve(finalPosition);
 		const carrier = finalBreakCarrierBefore(resolved, final.type.name, batchRevisionIds);
-		if (!carrier) {
-			next = next.setNodeAttribute(finalPosition, "pPrMark", null);
-			continue;
-		}
+		if (!carrier) continue;
 		const path = [{
 			node: final,
 			position: finalPosition
@@ -1897,10 +1928,10 @@ const withRotatedAddedFinalBreaks = ({ tr, batchRevisionIds, revisionSeed, autho
 			});
 			if (position === carrier.position) break;
 		}
-		if (path.at(-1)?.position !== carrier.position) {
-			next = next.setNodeAttribute(finalPosition, "pPrMark", null);
-			continue;
-		}
+		if (path.at(-1)?.position !== carrier.position) panic("A final-mark rotation lost its carrier", {
+			finalPosition,
+			carrier: carrier.position
+		});
 		if (path.slice(0, -1).some(({ node }) => {
 			const revisionId = addedBreakRevisionId(node.attrs["pPrMark"]);
 			return revisionId === null || !batchRevisionIds.has(revisionId);
@@ -2581,6 +2612,17 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations: reques
 			date,
 			...trackedRevisionExtras
 		} : null;
+		const commentSource = tr.doc;
+		const commentStepsBefore = tr.steps.length;
+		const commentReplacement = replacementText(item.operation);
+		const commentPlan = mode === "direct" && commentReplacement !== null && surveyReplacedAnnotations(commentSource, item.from, item.to).carried.some((mark) => mark.type.name === "comment") ? planDocumentReplacement({
+			doc: commentSource,
+			item,
+			replacement: stripInlineEmphasisMarkers(commentReplacement),
+			noteReferences,
+			planChanges: (before, after) => changesFromSegments(diffText(before, after)),
+			keepFieldsOf: planTextChanges
+		}) : null;
 		switch (item.operation.type) {
 			case "replaceInBlock":
 			case "replaceRange": {
@@ -3259,8 +3301,8 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations: reques
 					const markPosition = tr.mapping.map(item.blockFrom);
 					const endsItsContainer = paragraphEndsItsContainer(tr.doc.resolve(markPosition), item.blockNode.type.name);
 					const deleted = tr.doc.nodeAt(markPosition);
-					const following = deleted && tr.doc.nodeAt(markPosition + deleted.nodeSize);
-					if (deleted && following?.type === deleted.type && !isPairedMove(item.operation.moveId) && isInsertedPPrMark(deleted.attrs["pPrMark"])) {
+					const following = deleted && paragraphJoinAfter(tr.doc, markPosition + deleted.nodeSize)?.next;
+					if (deleted && following?.type === deleted.type && !isPairedMove(item.operation.moveId) && addedBreakRevisionId(deleted.attrs["pPrMark"]) !== null) {
 						const restored = paragraphPropertiesOnReject(deleted);
 						const followingChanges = expectParagraphAttrs(following)._propertyChanges;
 						const recordsRestored = isInsertedPPrMark(following.attrs["pPrMark"]) && !hasSerializableParagraphPropertyChange(followingChanges) && JSON.stringify(restored) !== JSON.stringify(paragraphPropertiesSnapshot(following));
@@ -3784,6 +3826,14 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations: reques
 				break;
 			default: break;
 		}
+		if (commentPlan !== null) tr = applyAlignedReplacementComments({
+			tr,
+			source: commentSource,
+			item,
+			plan: commentPlan,
+			stepsBefore: commentStepsBefore,
+			noteReferences
+		});
 		if (tr.steps.length === stepsBefore) {
 			if (!deletedFinalParagraphs.some(({ operationId }) => operationId === item.operation.id)) {
 				skipped.push({
@@ -3838,7 +3888,8 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations: reques
 			author,
 			date,
 			initials,
-			styleResolver: styleResolver ?? null
+			styleResolver: styleResolver ?? null,
+			numbering
 		});
 		tr = rotated.transaction;
 		revisionSeed = rotated.nextRevisionId;
@@ -4353,6 +4404,57 @@ const directReplacementMarks = ({ doc, plan, replacementBackground }) => {
 	keepUntil(plan.spanEnd - plan.spanStart);
 	return allocated;
 };
+const replacementText = (operation) => {
+	switch (operation.type) {
+		case "replaceBlock": return operation.text;
+		case "replaceInBlock":
+		case "replaceRange": return operation.replace;
+		default: return null;
+	}
+};
+/** Both modes project comment coverage through the same text alignment. */
+const applyAlignedReplacementComments = ({ tr, source, item, plan, stepsBefore, noteReferences }) => {
+	const comments = surveyReplacedAnnotations(source, item.from, item.to).carried.filter((mark) => mark.type.name === "comment");
+	if (comments.length === 0) return tr;
+	const marks = directReplacementMarks({
+		doc: source,
+		plan,
+		replacementBackground: "keep"
+	});
+	const blockFrom = tr.mapping.slice(stepsBefore).map(item.blockFrom, -1);
+	const block = tr.doc.nodeAt(blockFrom);
+	if (!block) panic("Replacement lost its paragraph");
+	const clean = buildCleanBlockText(block, blockFrom, {
+		fieldResults: "text",
+		noteReferences
+	});
+	for (const [index, expected] of marks.entries()) {
+		const from = clean.offsets[plan.spanStart + index];
+		if (from === void 0) panic("Replacement lost an aligned character");
+		const node = tr.doc.nodeAt(from);
+		if (!node?.isText || noteReferenceOf(node) !== null) continue;
+		for (const comment of comments) if (comment.isInSet(expected)) tr.addMark(from, from + 1, comment);
+		else tr.removeMark(from, from + 1, comment);
+	}
+	const visible = /* @__PURE__ */ new Set();
+	const points = /* @__PURE__ */ new Set();
+	tr.doc.descendants((node) => {
+		if (node.type.name === "rangeAnchor") {
+			const attrs = readRangeAnchorAttrs(node);
+			if (attrs.ok && attrs.value.start.type === "commentRangeStart") points.add(attrs.value.start.id);
+		}
+		if (!node.isInline || isZeroWidthAnchor(node) || node.marks.some((mark) => mark.type.name === "deletion")) return;
+		for (const mark of node.marks) if (mark.type.name === "comment") visible.add(mark.attrs["commentId"]);
+	});
+	const at = clean.offsets[plan.spanStart];
+	if (at === void 0) panic("Replacement lost its start gap");
+	for (const comment of comments) {
+		const id = comment.attrs["commentId"];
+		if (visible.has(id) || points.has(id)) continue;
+		tr.insert(at, commentPoint(tr.doc.type.schema, id));
+	}
+	return tr;
+};
 /**
 * Apply a direct-mode text replacement as the difference between the matched
 * text and its replacement; `minimal-replacement.ts` states the contract.
@@ -4474,11 +4576,16 @@ const applyMinimalTrackedReplacement = ({ tr, item, noteReferences, replacement,
 		noteReferences,
 		planChanges: planTextChanges
 	});
+	const annotationMarks = directReplacementMarks({
+		doc: tr.doc,
+		plan,
+		replacementBackground: "keep"
+	});
 	const allocatedMarks = directPlan === null ? null : directReplacementMarks({
 		doc: tr.doc,
 		plan: directPlan,
 		replacementBackground
-	});
+	}).map((marks, index) => addCarriedMarks(marks.filter((mark) => mark.type.name !== "comment"), (annotationMarks[index] ?? []).filter((mark) => mark.type.name === "comment")));
 	const unifiesFormatting = directPlan === null ? false : replacementUnifiesFormatting(tr.doc, directPlan);
 	let nextTr = tr;
 	let backgroundRevisionIds = [];

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

@@ -591,6 +591,8 @@ declare class FolioDocxReviewer {
   private noteKeysReferencedOutsideBody;
   private resolveEveryStoryOnce;
   private acceptOrdinaryChangesWithSuggestions;
+  /** Resolve ordinary revisions on a detached in-memory document. */
+  toResolvedDocument(decision: "accept" | "reject"): document_d_exports.Document;
   /** The current document model with edits merged back in. */
   toDocument(): document_d_exports.Document;
   private captureReviewerState;
@@ -625,6 +627,7 @@ declare class FolioDocxReviewer {
    * state for a story nothing edits.
    */
   private readSecondaryStoryDoc;
+  private secondaryStorySource;
   private secondaryStoryDoc;
   private requireEditableStoryState;
   private setEditableStoryState;

package/dist/ai-edits/headless.js

@@ -4,8 +4,11 @@ import { stageSectionBoundaryProperties } from "../compare/section-boundary-prop
 import { importReferencedStyleDefinitions, styleClosureNumberingReferences } from "../compare/style-resources.js";
 import { applyFolioDocumentOperations } from "../document-operations.js";
 import { applyReplyThreadMarkers } from "../docx/commentReplyMarkers.js";
+import { commentTextParagraph } from "../docx/commentTextParagraph.js";
+import { buildSections } from "../docx/documentParser.js";
 import { rebindDrawingImageRelationship } from "../docx/drawingRelationships.js";
 import { isSeparatorEndnote, isSeparatorFootnote } from "../docx/footnoteParser.js";
+import { normalizeListModelRendering } from "../docx/listModelNormalization.js";
 import { createNumberingIdAllocator } from "../docx/numberingIds.js";
 import { getCachedNumberingMap } from "../docx/numberingParser.js";
 import { recreateProseNodeWithParagraphPropertySource, transferProseParagraphPropertySource } from "../docx/paragraphPropertySource.js";
@@ -40,6 +43,7 @@ import { deterministicHexId } from "../utils/hexId.js";
 import { buildAnnotatedBlockTextWithNoteReferences } from "./clean-text.js";
 import { anchoredCommentIdsInBlocks, anchoredCommentIdsInProseDoc, withoutLostCommentThreads } from "./comment-lifecycle.js";
 import { noteReferenceEditsAllowed } from "./note-references.js";
+import { noteStoryInventory } from "./note-story-inventory.js";
 import { FolioPendingSuggestionRegistry, createPendingSuggestionSourceSnapshot, withoutPendingSuggestionCommentMarks } from "./pending-suggestions.js";
 import { getCommentAnchorsFromDoc, getTrackedChangeGroupIdsFromDoc, getTrackedChangeStatsFromDoc, getTrackedChangesFromDoc, getTrackedChangesFromSnapshot } from "./read.js";
 import { classifyResourceReference } from "./referenceClassification.js";
@@ -49,6 +53,7 @@ import { tableTemplateCanCrossPackageLosslessly } from "./table-template.js";
 import { TaggedError, panic } from "better-result";
 import { REVIEW_CARRIERS } from "@stll/docx-core/model";
 import { Fragment } from "prosemirror-model";
+import { reconcileDocumentPartRelationships } from "@stll/docx-core/ops";
 import { EditorState } from "prosemirror-state";
 import JSZip from "jszip";
 //#region src/ai-edits/headless.ts
@@ -76,18 +81,7 @@ const createReviewerComment = ({ id, text, author, date }) => ({
 	id,
 	author,
 	date: date ?? (/* @__PURE__ */ new Date()).toISOString(),
-	content: [{
-		type: "paragraph",
-		formatting: {},
-		content: [{
-			type: "run",
-			formatting: {},
-			content: [{
-				type: "text",
-				text
-			}]
-		}]
-	}]
+	content: [commentTextParagraph(text)]
 });
 /**
 * Assign a stable `w14:paraId` to every body paragraph that lacks one (or
@@ -1080,42 +1074,28 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* with the sections that show it: `[header first (sections 1, 3)] …`.
 	*/
 	getNotesAsText() {
-		const pkg = this.baseDocument.package;
 		const lines = [];
 		const placements = this.headerFooterPlacements();
-		const pushHeaderFooter = (map, label) => {
-			if (!map) return;
-			for (const [relationshipId, hf] of map) {
-				const handle = {
-					type: label,
-					relationshipId
-				};
-				const text = this.getHeaderFooterStoryText(handle, hf);
-				if (text.length > 0) {
-					const roles = placements.byPart.get(`${label}:${relationshipId}`);
-					lines.push(`[${label} ${roles ? describePlacements(roles, placements.sectionCount) : hf.hdrFtrType}] ${text}`);
+		for (const handle of this.listStoryHandlesInternal()) {
+			if (handle.type === "main") continue;
+			const text = this.getStoryText(handle);
+			if (text.length === 0) continue;
+			switch (handle.type) {
+				case "header":
+				case "footer": {
+					const source = this.getHeaderFooterStory(handle);
+					if (!source) panic("A listed document story no longer exists", { story: handle });
+					const roles = placements.byPart.get(`${handle.type}:${handle.relationshipId}`);
+					const label = roles ? describePlacements(roles, placements.sectionCount) : source.hdrFtrType;
+					lines.push(`[${handle.type} ${label}] ${text}`);
+					break;
 				}
+				case "footnote":
+				case "endnote":
+					lines.push(`[${handle.type} #${handle.noteId}] ${text}`);
+					break;
+				default: return handle;
 			}
-		};
-		pushHeaderFooter(pkg.headers, "header");
-		pushHeaderFooter(pkg.footers, "footer");
-		for (const footnote of pkg.footnotes ?? []) {
-			if (isSeparatorFootnote(footnote)) continue;
-			const handle = {
-				type: "footnote",
-				noteId: footnote.id
-			};
-			const text = this.getNoteStoryText(handle, footnote);
-			if (text.length > 0) lines.push(`[footnote #${footnote.id}] ${text}`);
-		}
-		for (const endnote of pkg.endnotes ?? []) {
-			if (isSeparatorEndnote(endnote)) continue;
-			const handle = {
-				type: "endnote",
-				noteId: endnote.id
-			};
-			const text = this.getNoteStoryText(handle, endnote);
-			if (text.length > 0) lines.push(`[endnote #${endnote.id}] ${text}`);
 		}
 		return lines.join("\n");
 	}
@@ -1138,17 +1118,18 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			type: "footer",
 			relationshipId
 		});
-		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) handles.push({
+		const notes = noteStoryInventory(pkg, this.removedNoteStories);
+		for (const footnote of notes.footnotes ?? []) if (!isSeparatorFootnote(footnote)) handles.push({
 			type: "footnote",
 			noteId: footnote.id
 		});
-		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) handles.push({
+		for (const endnote of notes.endnotes ?? []) if (!isSeparatorEndnote(endnote)) handles.push({
 			type: "endnote",
 			noteId: endnote.id
 		});
 		return handles.filter((handle) => {
 			if (handle.type === "header" || handle.type === "footer") return !this.removedHeaderFooterStories.has(headerFooterStoryKey(handle));
-			return handle.type !== "footnote" && handle.type !== "endnote" || !this.removedNoteStories.has(noteStoryKey(handle));
+			return true;
 		});
 	}
 	/** Discover every readable document story through a typed, serializable handle. */
@@ -1676,6 +1657,18 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			})
 		};
 	}
+	/** Resolve ordinary revisions on a detached in-memory document. */
+	toResolvedDocument(decision) {
+		const copy = new FolioDocxReviewer({
+			baseDocument: this.toDocument(),
+			originalBuffer: this.originalBuffer,
+			state: this.state,
+			author: this.author
+		});
+		if (decision === "accept") copy.acceptAll();
+		else copy.rejectAll();
+		return copy.toDocument();
+	}
 	/** The current document model with edits merged back in. */
 	toDocument() {
 		const document = this.documentFromStateSnapshot(this.captureReviewerState());
@@ -1702,7 +1695,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			importedFooters: new Map(this.importedFooters),
 			createdComments: [...this.createdComments],
 			resolvedOverrides: new Map(this.resolvedOverrides),
-			resolvedStoryExpectations: [...this.resolvedStoryExpectations.values()]
+			resolvedStoryExpectations: [...this.resolvedStoryExpectations.values()].filter(({ story }) => story.type === "main" || this.secondaryStorySource(story) !== void 0)
 		};
 	}
 	documentFromStateSnapshot(snapshot) {
@@ -1717,7 +1710,10 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			type: "supplied",
 			styles: snapshot.importedStyles
 		} });
-		if (snapshot.finalSectionPropertiesOverride !== void 0) document.package.document.finalSectionProperties = snapshot.finalSectionPropertiesOverride;
+		if (snapshot.finalSectionPropertiesOverride !== void 0) {
+			document.package.document.finalSectionProperties = snapshot.finalSectionPropertiesOverride;
+			if (document.package.document.sections !== void 0) document.package.document.sections = buildSections(document.package.document.content, snapshot.finalSectionPropertiesOverride);
+		}
 		if (snapshot.importedStyles !== void 0) document.package.styles = snapshot.importedStyles;
 		if (snapshot.importedMedia.size > 0) document.package.media = new Map([...document.package.media ?? [], ...snapshot.importedMedia]);
 		if (snapshot.importedHeaders.size > 0) document.package.headers = new Map([...document.package.headers ?? [], ...snapshot.importedHeaders]);
@@ -1734,20 +1730,12 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			const candidates = new Set(snapshot.removedNoteStories.map(noteStoryKey));
 			const referenced = referencedNotes(document, candidates);
 			const removed = new Set([...candidates].filter((key) => !referenced.has(key)));
-			const { footnotes, endnotes } = document.package;
-			if (footnotes) document.package.footnotes = footnotes.filter((note) => !removed.has(noteStoryKey({
-				type: "footnote",
-				noteId: note.id
-			})));
-			if (endnotes) document.package.endnotes = endnotes.filter((note) => !removed.has(noteStoryKey({
-				type: "endnote",
-				noteId: note.id
-			})));
+			Object.assign(document.package, noteStoryInventory(document.package, removed));
 		}
 		const definitions = [...document.package.document.comments ?? [], ...snapshot.createdComments];
 		const kept = this.keptCommentThreads(definitions, snapshot.mainState, snapshot.secondaryStoryStates);
 		if (kept.length !== definitions.length || snapshot.createdComments.length > 0 || snapshot.resolvedOverrides.size > 0) document.package.document.comments = this.withResolvedOverrides(kept, snapshot.resolvedOverrides);
-		return document;
+		return normalizeListModelRendering(reconcileDocumentPartRelationships(document)).document;
 	}
 	captureSaveSnapshot() {
 		const snapshot = this.captureReviewerState();
@@ -1895,6 +1883,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	}
 	getEditableStoryState(story) {
 		if (story.type === "main") return this.state;
+		if (!this.secondaryStorySource(story)) return null;
 		const key = secondaryStoryKey(story);
 		const existing = this.secondaryStoryStates.get(key);
 		if (existing) return existing.state;
@@ -1919,10 +1908,14 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* state for a story nothing edits.
 	*/
 	readSecondaryStoryDoc(story) {
+		if (!this.secondaryStorySource(story)) return null;
 		return this.secondaryStoryStates.get(secondaryStoryKey(story))?.state.doc ?? this.secondaryStoryDoc(story);
 	}
+	secondaryStorySource(story) {
+		return story.type === "header" || story.type === "footer" ? this.getHeaderFooterStory(story) : this.getNoteStory(story);
+	}
 	secondaryStoryDoc(story) {
-		const source = story.type === "header" || story.type === "footer" ? this.getHeaderFooterStory(story) : this.getNoteStory(story);
+		const source = this.secondaryStorySource(story);
 		if (!source) return null;
 		const conversionOptions = {
 			...this.baseDocument.package.numbering !== void 0 && { numbering: this.baseDocument.package.numbering },
@@ -2041,8 +2034,9 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		return snapshot !== null && detachFolioAIEditSnapshotExternalHyperlinks(snapshot) !== null;
 	}
 	getNoteStory(story) {
-		if (story.type === "footnote") return this.baseDocument.package.footnotes?.find((note) => note.id === story.noteId && !isSeparatorFootnote(note));
-		return this.baseDocument.package.endnotes?.find((note) => note.id === story.noteId && !isSeparatorEndnote(note));
+		const notes = noteStoryInventory(this.baseDocument.package, this.removedNoteStories);
+		if (story.type === "footnote") return notes.footnotes?.find((note) => note.id === story.noteId && !isSeparatorFootnote(note));
+		return notes.endnotes?.find((note) => note.id === story.noteId && !isSeparatorEndnote(note));
 	}
 	/**
 	* A loaded story's blocks, so its text comes from the same walk an unloaded
@@ -2178,7 +2172,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		}
 		for (const handle of this.removedNoteStories.values()) {
 			const entry = loaded.get(secondaryStoryKey(handle));
-			addAll(anchoredBefore, entry ? anchoredCommentIdsInProseDoc(entry.initialState.doc) : anchoredCommentIdsInBlocks(this.getNoteStory(handle)?.content ?? []));
+			addAll(anchoredBefore, entry ? anchoredCommentIdsInProseDoc(entry.initialState.doc) : anchoredCommentIdsInBlocks((handle.type === "footnote" ? this.baseDocument.package.footnotes : this.baseDocument.package.endnotes)?.find((note) => note.id === handle.noteId)?.content ?? []));
 		}
 		return withoutLostCommentThreads(comments, {
 			anchoredBefore,

package/dist/ai-edits/note-story-inventory.d.ts

@@ -0,0 +1,7 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/ai-edits/note-story-inventory.d.ts
+type NoteStories = Pick<document_d_exports.Document["package"], "footnotes" | "endnotes">;
+/** The note collections visible to a reviewer or its captured save state. */
+declare const noteStoryInventory: (source: NoteStories, removed: Pick<ReadonlySet<string>, "has" | "size">) => NoteStories;
+//#endregion
+export { noteStoryInventory };

package/dist/ai-edits/note-story-inventory.js

@@ -0,0 +1,11 @@
+//#region src/ai-edits/note-story-inventory.ts
+/** The note collections visible to a reviewer or its captured save state. */
+const noteStoryInventory = (source, removed) => {
+	if (removed.size === 0) return source;
+	return {
+		...source.footnotes && { footnotes: source.footnotes.filter((note) => !removed.has(`footnote:${note.id}`)) },
+		...source.endnotes && { endnotes: source.endnotes.filter((note) => !removed.has(`endnote:${note.id}`)) }
+	};
+};
+//#endregion
+export { noteStoryInventory };