@stll/folio-core 0.37.0 → 0.37.2

package/dist/ai-edits/apply.js

@@ -135,7 +135,12 @@ const hasRepresentableCommentAnchor = (item, mode) => {
 		default: return item.from < item.to;
 	}
 };
-const writesParagraphPropertyChange = (item) => item.operation.type === "setBlockParagraphProperties" || isResolvedReplaceBlockOperation(item) && REPLACE_BLOCK_IMPACT[item.replaceBlockImpact].changesStyle;
+const writesParagraphPropertyChange = (item) => {
+	if (item.operation.type === "setBlockParagraphProperties") return true;
+	if (item.operation.type === "splitBlock") return item.operation.firstParagraphProperties !== void 0 || item.operation.secondParagraphProperties !== void 0;
+	if (item.operation.type === "mergeBlockWithNext") return item.operation.mergedParagraphProperties !== void 0;
+	return isResolvedReplaceBlockOperation(item) && REPLACE_BLOCK_IMPACT[item.replaceBlockImpact].changesStyle;
+};
 const resolveReplaceBlockImpact = ({ changesText, changesStyle }) => {
 	if (changesText) return changesStyle ? "textAndStyle" : "text";
 	if (changesStyle) return "style";
@@ -266,6 +271,50 @@ const resolveFormattingFromStyle = ({ attrs, styleId, styleResolver }) => {
 	if (attrs.alignmentFromStyle !== void 0) fallback.alignment = attrs.alignmentFromStyle;
 	return Object.keys(fallback).length > 0 ? fallback : void 0;
 };
+/**
+* Apply one paragraph-property patch to a live node. A tracked patch stores
+* the complete previous pPr: a partial snapshot cannot distinguish a property
+* the change left alone from one it explicitly cleared when rejecting it.
+*/
+const applyBlockParagraphProperties = ({ tr, position, node, properties, styleResolver, numbering = null, revisionInfo }) => {
+	const attrs = expectParagraphAttrs(node);
+	const resolvedFormattingFromStyle = properties.styleId === void 0 ? resolveFormattingFromStyle({
+		attrs,
+		styleId: attrs.styleId,
+		styleResolver
+	}) : resolveFormattingFromStyle({
+		attrs,
+		styleId: properties.styleId,
+		styleResolver
+	});
+	const patch = paragraphPropertiesPatch({
+		node,
+		properties,
+		resolvedFormattingFromStyle,
+		numbering
+	});
+	if (patch === null) return {
+		tr,
+		changed: false,
+		revisionId: null
+	};
+	const changeInfo = revisionInfo?.();
+	const change = changeInfo ? {
+		type: "paragraphPropertyChange",
+		info: changeInfo,
+		previousFormatting: paragraphPropertiesSnapshot(node)
+	} : null;
+	const existing = attrs._propertyChanges;
+	return {
+		tr: tr.setNodeMarkup(position, void 0, {
+			...node.attrs,
+			...patch,
+			...change ? { _propertyChanges: [...Array.isArray(existing) ? existing : [], change] } : {}
+		}),
+		changed: true,
+		revisionId: change?.info.id ?? null
+	};
+};
 const applyReplaceBlockStyleId = ({ item, tr, styleResolver, revisionInfo }) => {
 	if (item.operation.type !== "replaceBlock" || item.operation.styleId === void 0) return {
 		tr,
@@ -1291,7 +1340,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 		const provisionalCommentId = item.commentText !== void 0 ? reserveProvisionalCommentId() : void 0;
 		const commentMark = provisionalCommentId !== void 0 && commentType ? commentType.create({ commentId: provisionalCommentId }) : null;
 		const stepsBefore = tr.steps.length;
-		let appliedRevisionIds;
+		let appliedRevisionIds = [];
 		if (isSuggested && !SUGGESTED_SUPPORTED_OPERATION_TYPES.has(item.operation.type)) {
 			skipped.push({
 				id: item.operation.id,
@@ -1900,85 +1949,89 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 			case "setBlockParagraphProperties": {
 				const blockPosition = tr.mapping.map(item.blockFrom);
 				const liveBlock = tr.doc.nodeAt(blockPosition) ?? item.blockNode;
-				const liveAttrs = expectParagraphAttrs(liveBlock);
-				const resolvedFormattingFromStyle = item.operation.properties.styleId === void 0 ? resolveFormattingFromStyle({
-					attrs: liveAttrs,
-					styleId: liveAttrs.styleId,
-					styleResolver
-				}) : resolveFormattingFromStyle({
-					attrs: liveAttrs,
-					styleId: item.operation.properties.styleId,
-					styleResolver
-				});
-				const patch = paragraphPropertiesPatch({
+				const appliedProperties = applyBlockParagraphProperties({
+					tr,
+					position: blockPosition,
 					node: liveBlock,
 					properties: item.operation.properties,
-					resolvedFormattingFromStyle,
-					numbering
+					styleResolver,
+					numbering,
+					...mode === "direct" ? {} : { revisionInfo: () => ({
+						id: operationRevisionSeed++,
+						author,
+						date,
+						...trackedRevisionExtras
+					}) }
 				});
-				if (patch === null) {
+				if (!appliedProperties.changed) {
 					skipped.push({
 						id: item.operation.id,
 						reason: "noopOperation"
 					});
 					continue;
 				}
-				if (mode === "direct") {
-					tr = tr.setNodeMarkup(blockPosition, void 0, {
-						...liveBlock.attrs,
-						...patch
-					});
-					break;
-				}
-				const revisionId = operationRevisionSeed++;
-				const change = {
-					type: "paragraphPropertyChange",
-					info: {
-						id: revisionId,
-						author,
-						date,
-						...trackedRevisionExtras
-					},
-					previousFormatting: paragraphPropertiesSnapshot(liveBlock)
-				};
-				const existing = expectParagraphAttrs(liveBlock)._propertyChanges;
-				tr = tr.setNodeMarkup(blockPosition, void 0, {
-					...liveBlock.attrs,
-					...patch,
-					_propertyChanges: [...Array.isArray(existing) ? existing : [], change]
-				});
-				appliedRevisionIds = [revisionId];
+				tr = appliedProperties.tr;
+				if (appliedProperties.revisionId !== null) appliedRevisionIds = [appliedProperties.revisionId];
 				break;
 			}
 			case "splitBlock": {
 				if (mode === "direct") {
 					if (item.to > item.from) tr = tr.delete(item.from, item.to);
 					tr = tr.split(item.from);
-					break;
-				}
-				const revisionIdMark = operationRevisionSeed++;
-				const info = {
-					id: revisionIdMark,
-					author,
-					date,
-					...trackedRevisionExtras
-				};
-				appliedRevisionIds = [revisionIdMark];
-				if (item.to > item.from && deletionType) {
-					const revisionIdSeparator = operationRevisionSeed++;
-					tr = tr.addMark(item.from, item.to, deletionType.create({
-						revisionId: revisionIdSeparator,
+				} else {
+					const revisionIdMark = operationRevisionSeed++;
+					const info = {
+						id: revisionIdMark,
 						author,
 						date,
 						...trackedRevisionExtras
-					}));
-					appliedRevisionIds = [revisionIdMark, revisionIdSeparator];
+					};
+					appliedRevisionIds = [revisionIdMark];
+					if (item.to > item.from && deletionType) {
+						const revisionIdSeparator = operationRevisionSeed++;
+						tr = tr.addMark(item.from, item.to, deletionType.create({
+							revisionId: revisionIdSeparator,
+							author,
+							date,
+							...trackedRevisionExtras
+						}));
+						appliedRevisionIds.push(revisionIdSeparator);
+					}
+					tr = tr.split(item.from);
+					tr = tr.setNodeAttribute(item.blockFrom, "pPrMark", {
+						kind: "ins",
+						info
+					});
 				}
-				tr = tr.split(item.from);
-				tr = tr.setNodeAttribute(item.blockFrom, "pPrMark", {
-					kind: "ins",
-					info
+				const allocateSplitParagraphPropertyRevisionInfo = () => ({
+					id: operationRevisionSeed++,
+					author,
+					date,
+					...trackedRevisionExtras
 				});
+				const paragraphPropertyTargets = [{
+					position: item.blockFrom,
+					properties: item.operation.firstParagraphProperties
+				}, {
+					position: item.from + 1,
+					properties: item.operation.secondParagraphProperties
+				}];
+				for (const { position, properties } of paragraphPropertyTargets) {
+					if (!properties) continue;
+					const paragraph = tr.doc.nodeAt(position);
+					if (!paragraph) panic("A resolved split did not produce two paragraphs");
+					const appliedProperties = applyBlockParagraphProperties({
+						tr,
+						position,
+						node: paragraph,
+						properties,
+						styleResolver,
+						numbering,
+						...mode === "direct" ? {} : { revisionInfo: allocateSplitParagraphPropertyRevisionInfo }
+					});
+					tr = appliedProperties.tr;
+					if (appliedProperties.revisionId !== null) appliedRevisionIds.push(appliedProperties.revisionId);
+				}
 				break;
 			}
 			case "mergeBlockWithNext": {
@@ -1987,30 +2040,50 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 				if (mode === "direct") {
 					if (separator.length > 0) tr = tr.insertText(separator, insertAt);
 					tr = tr.join(item.blockTo + separator.length);
-					break;
+				} else {
+					const revisionIdMark = operationRevisionSeed++;
+					appliedRevisionIds = [revisionIdMark];
+					if (separator.length > 0 && insertionType) {
+						const revisionIdSeparator = operationRevisionSeed++;
+						tr = tr.insertText(separator, insertAt);
+						tr = tr.addMark(insertAt, insertAt + separator.length, insertionType.create({
+							revisionId: revisionIdSeparator,
+							author,
+							date,
+							...trackedRevisionExtras
+						}));
+						appliedRevisionIds.push(revisionIdSeparator);
+					}
+					tr = tr.setNodeAttribute(item.blockFrom, "pPrMark", {
+						kind: "del",
+						info: {
+							id: revisionIdMark,
+							author,
+							date,
+							...trackedRevisionExtras
+						}
+					});
 				}
-				const revisionIdMark = operationRevisionSeed++;
-				appliedRevisionIds = [revisionIdMark];
-				if (separator.length > 0 && insertionType) {
-					const revisionIdSeparator = operationRevisionSeed++;
-					tr = tr.insertText(separator, insertAt);
-					tr = tr.addMark(insertAt, insertAt + separator.length, insertionType.create({
-						revisionId: revisionIdSeparator,
-						author,
-						date,
-						...trackedRevisionExtras
-					}));
-					appliedRevisionIds = [revisionIdMark, revisionIdSeparator];
+				if (item.operation.mergedParagraphProperties) {
+					const mergedParagraph = tr.doc.nodeAt(item.blockFrom);
+					if (!mergedParagraph) panic("A resolved merge did not produce a paragraph");
+					const appliedProperties = applyBlockParagraphProperties({
+						tr,
+						position: item.blockFrom,
+						node: mergedParagraph,
+						properties: item.operation.mergedParagraphProperties,
+						styleResolver,
+						numbering,
+						...mode === "direct" ? {} : { revisionInfo: () => ({
+							id: operationRevisionSeed++,
+							author,
+							date,
+							...trackedRevisionExtras
+						}) }
+					});
+					tr = appliedProperties.tr;
+					if (appliedProperties.revisionId !== null) appliedRevisionIds.push(appliedProperties.revisionId);
 				}
-				tr = tr.setNodeAttribute(item.blockFrom, "pPrMark", {
-					kind: "del",
-					info: {
-						id: revisionIdMark,
-						author,
-						date,
-						...trackedRevisionExtras
-					}
-				});
 				break;
 			}
 			case "commentOnBlock":
@@ -2043,7 +2116,7 @@ const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode =
 		applied.push({
 			id: item.operation.id,
 			...committedCommentId !== void 0 && { commentId: committedCommentId },
-			...appliedRevisionIds !== void 0 && appliedRevisionIds[0] !== void 0 && {
+			...appliedRevisionIds[0] !== void 0 && {
 				revisionId: appliedRevisionIds[0],
 				revisionIds: appliedRevisionIds
 			},

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

@@ -122,6 +122,22 @@ type FolioApplyDocumentOperationsToStoryOptions = FolioApplyDocumentOperationsOp
    */
   tableTemplates?: FolioTableTemplates;
 };
+type FolioDocxComparisonProjectionMode = "with-revision-census" | "without-revision-census";
+type FolioDocxComparisonStoryProjection = {
+  handle: FolioDocumentStoryHandle;
+  snapshot: FolioAIEditSnapshot | null;
+};
+type FolioDocxComparisonProjection = {
+  stories: readonly FolioDocxComparisonStoryProjection[];
+  revisions: {
+    highestId: number;
+    present: boolean;
+  };
+};
+type FolioDocxComparisonAccess = {
+  projectStories: (mode: FolioDocxComparisonProjectionMode) => FolioDocxComparisonProjection;
+  snapshotReviewedStory: (options?: FolioReadReviewedStoryOptions) => FolioAIEditSnapshot | null;
+};
 declare const isFolioReviewedView: (value: unknown) => value is FolioReviewedView;
 declare const isFolioResolvedReviewedView: (value: unknown) => value is FolioResolvedReviewedView;
 /** Filter for {@link FolioDocxReviewer.getChanges}. */
@@ -222,6 +238,8 @@ declare class FolioDocxReviewer {
   getDocumentProperties(): Readonly<NonNullable<document_d_exports.Document["package"]["properties"]>> | null;
   /** Snapshot one editable story into stable, operation-ready blocks. */
   snapshotStory(story: FolioEditableDocumentStoryHandle): FolioAIEditSnapshot | null;
+  private snapshotReviewedStoryInternal;
+  private projectComparisonStoriesInternal;
   /**
    * One story's tables, in the document order {@link snapshotStory} numbers
    * them with, read through a reviewed view.
@@ -249,6 +267,7 @@ declare class FolioDocxReviewer {
   readReviewedStory(options?: FolioReadReviewedStoryOptions): FolioReviewedStory | null;
   /** Resolve one editable story to its original or final state. */
   resolveReviewedStory({ story, view }: FolioResolveReviewedStoryOptions): boolean;
+  private resolveReviewedStorySnapshotInternal;
   /**
    * Apply operations against the current state. Reuses the live-editor applier
    * verbatim via a headless `{ state, dispatch }` seam; the resulting state
@@ -292,6 +311,7 @@ declare class FolioDocxReviewer {
    * parts and separator notes are omitted.
    */
   getNotesAsText(): string;
+  private listStoryHandlesInternal;
   /** Discover every readable document story through a typed, serializable handle. */
   listStories(): FolioDocumentStory[];
   /** Read one discovered story; returns null when its handle is no longer present. */
@@ -386,6 +406,7 @@ declare class FolioDocxReviewer {
   private getNoteStory;
   private getHeaderFooterStoryText;
   private getNoteStoryText;
+  private getStoryText;
   private mergeEditedSecondaryStories;
   /** Apply any {@link resolveComment} overrides recorded for these comments. */
   private withResolvedOverrides;
@@ -401,6 +422,8 @@ declare class FolioDocxReviewer {
   private runCommand;
   private runStoryCommand;
 }
+/** @internal Comparison-only access to atomic and fresh reviewer projections. */
+declare const getFolioDocxComparisonAccess: (reviewer: FolioDocxReviewer) => FolioDocxComparisonAccess;
 /** Options for {@link applyFolioAIEditsToBuffer}. */
 type ApplyFolioAIEditsToBufferOptions = {
   /** Default author for tracked changes and comments. (default: `"AI"`) */
@@ -428,4 +451,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };

package/dist/ai-edits/headless.js

@@ -18,10 +18,10 @@ import { createDocumentStylesPlugin, getDocumentStyleResolver } from "../prosemi
 import { schema, singletonManager } from "../prosemirror/schema/index.js";
 import { deterministicHexId } from "../utils/hexId.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
-import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
-import { createFolioAIEditSnapshotWithStyleResolver, folioStoryTables, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./snapshot.js";
+import { getCommentAnchorsFromDoc, getTrackedChangeStatsFromDoc, getTrackedChangesFromDoc, getTrackedChangesFromSnapshot } from "./read.js";
+import { createFolioAIEditSnapshotWithStyleResolver, folioStoryTables, isFolioAIContentBlock, normalizeFolioAIBlockText, sourceDocumentOf } from "./snapshot.js";
 import { matchTableGeometry } from "./table-geometry.js";
-import { TaggedError } from "better-result";
+import { TaggedError, panic } from "better-result";
 import { Fragment } from "prosemirror-model";
 import { EditorState } from "prosemirror-state";
 //#region src/ai-edits/headless.ts
@@ -160,6 +160,7 @@ const resolvedStoryBlockProjection = (block) => {
 	delete persisted.idStability;
 	return persisted;
 };
+const comparisonAccessByReviewer = /* @__PURE__ */ new WeakMap();
 const MAIN_STORY = Object.freeze({ type: "main" });
 const headerFooterStoryKey = ({ type, relationshipId }) => `${type}:${relationshipId}`;
 const noteStoryKey = ({ type, noteId }) => `${type}:${noteId}`;
@@ -177,12 +178,11 @@ const createHeadlessPlugins = (styles, numbering) => [
 	createDocumentNumberingPlugin(numbering)
 ];
 const createStateSnapshot = (state) => createFolioAIEditSnapshotWithStyleResolver(state.doc, getDocumentStyleResolver(state));
-const formatStoryStateForLLM = (state, annotated) => {
-	const snapshot = createStateSnapshot(state);
+const formatStorySnapshotForLLM = (snapshot, annotated) => {
 	const blocks = snapshot.blocks.filter(isFolioAIContentBlock);
 	if (!annotated) return blocks.map(formatBlockForLLM).join("\n");
 	const nodeByStart = /* @__PURE__ */ new Map();
-	state.doc.descendants((node, pos) => {
+	sourceDocumentOf(snapshot).descendants((node, pos) => {
 		if (!node.isTextblock) return true;
 		nodeByStart.set(pos, node);
 		return false;
@@ -264,6 +264,10 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		this.state = args.state;
 		this.author = args.author;
 		this.usedCommentIds = new Set((args.baseDocument.package.document.comments ?? []).map(({ id }) => id));
+		comparisonAccessByReviewer.set(this, Object.freeze({
+			projectStories: (mode) => this.projectComparisonStoriesInternal(mode),
+			snapshotReviewedStory: (options) => this.snapshotReviewedStoryInternal(options)
+		}));
 	}
 	/** Parse a `.docx` buffer into a reviewer. */
 	static async fromBuffer(buffer, options = {}) {
@@ -339,6 +343,43 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		const state = this.getEditableStoryState(story);
 		return state ? createStateSnapshot(state) : null;
 	}
+	snapshotReviewedStoryInternal(options = {}) {
+		const story = options.story ?? MAIN_STORY;
+		const view = options.view ?? "final";
+		if (!isFolioReviewedView(view)) throw new UnsupportedFolioReviewedViewError({
+			message: "Unsupported reviewed document view.",
+			receivedView: view
+		});
+		const sourceState = this.getEditableStoryState(story);
+		return sourceState ? createStateSnapshot(resolveReviewedState(sourceState, view)) : null;
+	}
+	projectComparisonStoriesInternal(mode) {
+		const handles = this.listStoryHandlesInternal();
+		let highestId = 0;
+		let present = false;
+		if (mode === "with-revision-census") for (const handle of handles) {
+			const state = this.getEditableStoryState(handle);
+			if (!state) continue;
+			const stats = getTrackedChangeStatsFromDoc(state.doc);
+			highestId = Math.max(highestId, stats.highestId);
+			present ||= stats.present;
+		}
+		const stories = [];
+		for (const handle of handles) stories.push({
+			handle,
+			snapshot: this.resolveReviewedStorySnapshotInternal({
+				story: handle,
+				view: "final"
+			})
+		});
+		return {
+			stories,
+			revisions: {
+				highestId,
+				present
+			}
+		};
+	}
 	/**
 	* One story's tables, in the document order {@link snapshotStory} numbers
 	* them with, read through a reviewed view.
@@ -390,37 +431,42 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	readReviewedStory(options = {}) {
 		const story = options.story ?? MAIN_STORY;
 		const view = options.view ?? "final";
-		if (!isFolioReviewedView(view)) throw new UnsupportedFolioReviewedViewError({
-			message: "Unsupported reviewed document view.",
-			receivedView: view
+		const snapshot = this.snapshotReviewedStoryInternal({
+			story,
+			view
 		});
-		const sourceState = this.getEditableStoryState(story);
-		if (!sourceState) return null;
-		const state = resolveReviewedState(sourceState, view);
+		if (!snapshot) return null;
 		return {
 			story,
 			view,
-			snapshot: createStateSnapshot(state),
-			text: formatStoryStateForLLM(state, view === "current-markup"),
-			changes: getTrackedChangesFromDoc(state.doc)
+			snapshot,
+			text: formatStorySnapshotForLLM(snapshot, view === "current-markup"),
+			changes: getTrackedChangesFromSnapshot(snapshot)
 		};
 	}
 	/** Resolve one editable story to its original or final state. */
 	resolveReviewedStory({ story = MAIN_STORY, view }) {
+		return this.resolveReviewedStorySnapshotInternal({
+			story,
+			view
+		}) !== null;
+	}
+	resolveReviewedStorySnapshotInternal({ story = MAIN_STORY, view }) {
 		if (!isFolioResolvedReviewedView(view)) throw new UnsupportedFolioReviewedViewError({
 			message: "Only original and final views can replace editable story state.",
 			receivedView: view
 		});
 		const sourceState = this.getEditableStoryState(story);
-		if (!sourceState) return false;
+		if (!sourceState) return null;
 		const resolvedState = resolveReviewedState(sourceState, view);
 		this.setEditableStoryState(story, resolvedState);
+		const snapshot = createStateSnapshot(resolvedState);
 		this.resolvedStoryExpectations.set(editableStoryKey(story), {
 			story,
-			text: formatStoryStateForLLM(resolvedState, false),
-			blocks: createStateSnapshot(resolvedState).blocks.map(resolvedStoryBlockProjection)
+			text: formatStorySnapshotForLLM(snapshot, false),
+			blocks: snapshot.blocks.map(resolvedStoryBlockProjection)
 		});
-		return true;
+		return snapshot;
 	}
 	/**
 	* Apply operations against the current state. Reuses the live-editor applier
@@ -564,7 +610,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* (clean) output flattens tracked changes and is unchanged.
 	*/
 	getContentAsText(options = {}) {
-		return formatStoryStateForLLM(this.state, options.annotated === true);
+		return formatStorySnapshotForLLM(this.snapshot(), options.annotated === true);
 	}
 	/**
 	* Header / footer and footnote / endnote text as labeled, LLM-ready lines,
@@ -608,54 +654,33 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		}
 		return lines.join("\n");
 	}
+	listStoryHandlesInternal() {
+		const pkg = this.baseDocument.package;
+		const handles = [{ type: "main" }];
+		for (const relationshipId of pkg.headers?.keys() ?? []) handles.push({
+			type: "header",
+			relationshipId
+		});
+		for (const relationshipId of pkg.footers?.keys() ?? []) handles.push({
+			type: "footer",
+			relationshipId
+		});
+		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) handles.push({
+			type: "footnote",
+			noteId: footnote.id
+		});
+		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) handles.push({
+			type: "endnote",
+			noteId: endnote.id
+		});
+		return handles;
+	}
 	/** Discover every readable document story through a typed, serializable handle. */
 	listStories() {
-		const pkg = this.baseDocument.package;
-		const stories = [{
-			handle: { type: "main" },
-			text: this.getContentAsText()
-		}];
-		for (const [relationshipId, header] of pkg.headers ?? []) {
-			const handle = {
-				type: "header",
-				relationshipId
-			};
-			stories.push({
-				handle,
-				text: this.getHeaderFooterStoryText(handle, header)
-			});
-		}
-		for (const [relationshipId, footer] of pkg.footers ?? []) {
-			const handle = {
-				type: "footer",
-				relationshipId
-			};
-			stories.push({
-				handle,
-				text: this.getHeaderFooterStoryText(handle, footer)
-			});
-		}
-		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) {
-			const handle = {
-				type: "footnote",
-				noteId: footnote.id
-			};
-			stories.push({
-				handle,
-				text: this.getNoteStoryText(handle, footnote)
-			});
-		}
-		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) {
-			const handle = {
-				type: "endnote",
-				noteId: endnote.id
-			};
-			stories.push({
-				handle,
-				text: this.getNoteStoryText(handle, endnote)
-			});
-		}
-		return stories;
+		return this.listStoryHandlesInternal().map((handle) => ({
+			handle,
+			text: this.getStoryText(handle)
+		}));
 	}
 	/** Read one discovered story; returns null when its handle is no longer present. */
 	readStory(handle) {
@@ -887,11 +912,10 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 				story,
 				view: "current-markup"
 			});
-			const serializedState = reopened.getEditableStoryState(story);
-			const serializedText = serializedState ? formatStoryStateForLLM(serializedState, false) : null;
-			const serializedBlocks = serializedState ? createStateSnapshot(serializedState).blocks.map(resolvedStoryBlockProjection) : null;
+			const serializedText = serialized ? formatStorySnapshotForLLM(serialized.snapshot, false) : null;
+			const serializedBlocks = serialized ? serialized.snapshot.blocks.map(resolvedStoryBlockProjection) : null;
 			const mismatches = [];
-			if (!serialized || !serializedState) mismatches.push(FOLIO_RESOLVED_STORY_SERIALIZATION_MISMATCHES.storyMissing);
+			if (!serialized) mismatches.push(FOLIO_RESOLVED_STORY_SERIALIZATION_MISMATCHES.storyMissing);
 			else {
 				if (serialized.changes.length > 0) mismatches.push(FOLIO_RESOLVED_STORY_SERIALIZATION_MISMATCHES.revisionMarkupRemains);
 				if (serializedText !== text) mismatches.push(FOLIO_RESOLVED_STORY_SERIALIZATION_MISMATCHES.textProjection);
@@ -986,6 +1010,17 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		const sourceText = source.type === "footnote" ? getFootnoteText(source) : getEndnoteText(source);
 		return normalizeFolioAIBlockText(state?.doc.textContent ?? sourceText);
 	}
+	getStoryText(story) {
+		if (story.type === "main") return this.getContentAsText();
+		if (story.type === "header" || story.type === "footer") {
+			const source = this.getHeaderFooterStory(story);
+			if (!source) return panic("A listed document story no longer exists", { story });
+			return this.getHeaderFooterStoryText(story, source);
+		}
+		const source = this.getNoteStory(story);
+		if (!source) return panic("A listed document story no longer exists", { story });
+		return this.getNoteStoryText(story, source);
+	}
 	mergeEditedSecondaryStories(document, secondaryStoryStates = this.secondaryStoryStates.values()) {
 		let headers;
 		let footers;
@@ -1087,6 +1122,8 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		return handled;
 	}
 };
+/** @internal Comparison-only access to atomic and fresh reviewer projections. */
+const getFolioDocxComparisonAccess = (reviewer) => comparisonAccessByReviewer.get(reviewer) ?? panic("Comparison access was requested for an uninitialized DOCX reviewer");
 /**
 * One-shot headless review: parse `buffer`, apply `operations`, and return the
 * reviewed `.docx` buffer alongside the applied / skipped breakdown. Convenience
@@ -1106,4 +1143,4 @@ const applyFolioAIEditsToBuffer = async (buffer, operations, options = {}) => {
 	};
 };
 //#endregion
-export { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, FolioDocxReviewer, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };
+export { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, FolioDocxReviewer, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };