@stll/folio-core 0.3.1 → 0.5.0

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

@@ -23,13 +23,7 @@ type ApplyFolioAIEditOperationsOptions = {
   author?: string;
   createCommentId?: (text: string) => number;
 };
-declare const applyFolioAIEditOperations: ({
-  view,
-  snapshot,
-  operations,
-  mode,
-  author,
-  createCommentId
-}: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyResult;
+declare const applyFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyResult;
+declare const previewFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyResult;
 //#endregion
-export { FolioAIEditView, applyFolioAIEditOperations };
+export { FolioAIEditView, applyFolioAIEditOperations, previewFolioAIEditOperations };

package/dist/ai-edits/apply.js

@@ -193,7 +193,7 @@ const buildEmphasisInlineContent = (schema, text, baseMarks) => {
 	}
 	return nodes.length > 0 ? nodes : [schema.text(text, [...baseMarks])];
 };
-const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracked-changes", author = "AI", createCommentId }) => {
+const applyFolioAIEditOperationsInternal = ({ view, snapshot, operations, mode = "tracked-changes", author = "AI", createCommentId, revisionIdSeed }) => {
 	const applied = [];
 	const skipped = [];
 	const resolved = [];
@@ -210,6 +210,13 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 	const liveBlocks = collectLiveBlocksByHash(view.state.doc);
 	const liveBlocksByParaId = collectLiveBlocksByParaId(view.state.doc);
 	for (const [index, operation] of operations.entries()) {
+		if (mode === "tracked-changes" && operation.type === "formatRange") {
+			skipped.push({
+				id: operation.id,
+				reason: "unsupportedMode"
+			});
+			continue;
+		}
 		const commentText = getOperationCommentText(operation);
 		if (commentText !== void 0 && (!commentType || createCommentId === void 0)) {
 			skipped.push({
@@ -244,7 +251,7 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 		skipped
 	};
 	let tr = view.state.tr;
-	let revisionSeed = nextRevisionSeed(resolved.length);
+	let revisionSeed = revisionIdSeed ?? nextRevisionSeed(resolved.length);
 	const date = (/* @__PURE__ */ new Date()).toISOString();
 	for (const item of resolved.toSorted((left, right) => {
 		if (left.from !== right.from) return right.from - left.from;
@@ -254,7 +261,8 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 		const stepsBefore = tr.steps.length;
 		let appliedRevisionIds;
 		switch (item.operation.type) {
-			case "replaceInBlock": {
+			case "replaceInBlock":
+			case "replaceRange": {
 				const revisionIdDelete = revisionSeed++;
 				const revisionIdInsert = revisionSeed++;
 				tr = applyTextReplacement({
@@ -270,6 +278,17 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 				if (mode === "tracked-changes") appliedRevisionIds = [revisionIdDelete, revisionIdInsert];
 				break;
 			}
+			case "commentOnRange":
+				if (commentMark) tr = tr.addMark(item.from, item.to, commentMark);
+				break;
+			case "formatRange":
+				for (const [name, enabled] of Object.entries(item.operation.formatting)) {
+					const markType = view.state.schema.marks[name];
+					if (!markType) continue;
+					if (enabled) tr = tr.addMark(item.from, item.to, name === "underline" ? markType.create({ style: "single" }) : markType.create());
+					else tr = tr.removeMark(item.from, item.to, markType);
+				}
+				break;
 			case "replaceBlock": {
 				const revisionIdDelete = revisionSeed++;
 				const revisionIdInsert = revisionSeed++;
@@ -314,7 +333,7 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 				if (mode === "tracked-changes" && item.operation.pageBreakBefore === true && (!item.insertText || item.insertText.length === 0)) {
 					skipped.push({
 						id: item.operation.id,
-						reason: "unsupportedBlock"
+						reason: "unsupportedMode"
 					});
 					continue;
 				}
@@ -338,6 +357,7 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 						attrs["listMarker"] = null;
 						attrs["listMarkerHidden"] = null;
 						attrs["listLevelNumFmts"] = null;
+						attrs["listLevelStarts"] = null;
 						attrs["listAbstractNumId"] = null;
 						attrs["listStartOverride"] = null;
 					}
@@ -350,7 +370,7 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 				if (mode === "tracked-changes") {
 					skipped.push({
 						id: item.operation.id,
-						reason: "unsupportedBlock"
+						reason: "unsupportedMode"
 					});
 					continue;
 				}
@@ -411,15 +431,36 @@ const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracke
 		skipped
 	};
 };
+const applyFolioAIEditOperations = (options) => applyFolioAIEditOperationsInternal(options);
+const previewFolioAIEditOperations = (options) => {
+	const { view, createCommentId, ...applyOptions } = options;
+	let previewCommentId = -1;
+	const previewView = {
+		state: view.state,
+		dispatch: (transaction) => {
+			previewView.state = previewView.state.apply(transaction);
+		}
+	};
+	const result = applyFolioAIEditOperationsInternal({
+		...applyOptions,
+		view: previewView,
+		...createCommentId !== void 0 && { createCommentId: () => previewCommentId-- },
+		revisionIdSeed: -1e9
+	});
+	return {
+		applied: result.applied.map(({ id }) => ({ id })),
+		skipped: result.skipped
+	};
+};
 const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete, revisionIdInsert, commentMark }) => {
 	let nextTr = tr;
 	const replacement = stripInlineEmphasisMarkers((() => {
-		if (item.operation.type === "replaceInBlock") return item.operation.replace;
+		if (item.operation.type === "replaceInBlock" || item.operation.type === "replaceRange") return item.operation.replace;
 		if (item.operation.type === "replaceBlock") return item.operation.text;
 		return "";
 	})());
 	if (mode === "direct") {
-		if (item.operation.type === "replaceInBlock" && hasInlineEmphasis(item.operation.replace)) {
+		if ((item.operation.type === "replaceInBlock" || item.operation.type === "replaceRange") && hasInlineEmphasis(item.operation.replace)) {
 			const content = buildEmphasisInlineContent(nextTr.doc.type.schema, item.operation.replace, commentMark ? [commentMark] : []);
 			return nextTr.replaceWith(item.from, item.to, content);
 		}
@@ -447,6 +488,9 @@ const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete,
 			sourceText = item.operation.find;
 			sourceCleanStart = cleanBlock.text.indexOf(item.operation.find);
 			if (sourceCleanStart === -1) sourceText = null;
+		} else if (item.operation.type === "replaceRange") {
+			sourceCleanStart = item.operation.range.startOffset;
+			sourceText = cleanBlock.text.slice(sourceCleanStart, item.operation.range.endOffset);
 		} else if (item.operation.type === "replaceBlock") {
 			sourceText = cleanBlock.text;
 			sourceCleanStart = 0;
@@ -518,12 +562,13 @@ const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete,
 	return nextTr;
 };
 const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId, doc }) => {
-	const anchor = snapshot.anchors[operation.blockId];
+	const blockId = operation.type === "replaceRange" || operation.type === "commentOnRange" || operation.type === "formatRange" ? operation.range.blockId : operation.blockId;
+	const anchor = snapshot.anchors[blockId];
 	if (!anchor) return {
 		type: "skip",
 		reason: "missingBlock"
 	};
-	const encodedParaId = getFolioParaIdFromBlockId(operation.blockId);
+	const encodedParaId = getFolioParaIdFromBlockId(blockId);
 	let live;
 	if (encodedParaId !== null) {
 		live = liveBlocksByParaId.get(encodedParaId);
@@ -532,7 +577,7 @@ const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId,
 			reason: "missingBlock"
 		};
 	} else {
-		const ordinal = ordinalAmongSameHash(snapshot, operation.blockId);
+		const ordinal = ordinalAmongSameHash(snapshot, blockId);
 		if (ordinal < 0) return {
 			type: "skip",
 			reason: "missingBlock"
@@ -548,10 +593,44 @@ const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId,
 	const blockTo = live.to;
 	const cleanBlock = buildCleanBlockText(blockNode, blockFrom);
 	const currentText = cleanBlock.text;
-	if (hashFolioAIBlockText(normalizeFolioAIBlockText(currentText)) !== anchor.textHash) return {
+	const currentTextHash = hashFolioAIBlockText(normalizeFolioAIBlockText(currentText));
+	if (operation.precondition !== void 0 && currentTextHash !== operation.precondition.blockTextHash) return {
+		type: "skip",
+		reason: "preconditionFailed"
+	};
+	if (currentTextHash !== anchor.textHash) return {
 		type: "skip",
 		reason: "changedBlock"
 	};
+	if (operation.type === "replaceRange" || operation.type === "commentOnRange" || operation.type === "formatRange") {
+		const { startOffset, endOffset, selectedTextHash } = operation.range;
+		const from = cleanBlock.offsets[startOffset];
+		const to = cleanBlock.offsets[endOffset];
+		if (from === void 0 || to === void 0) return {
+			type: "skip",
+			reason: "staleRange"
+		};
+		const selectedText = currentText.slice(startOffset, endOffset);
+		if (hashFolioAIBlockText(selectedText) !== selectedTextHash) return {
+			type: "skip",
+			reason: "staleRange"
+		};
+		if (operation.type === "replaceRange" && selectedText === operation.replace) return {
+			type: "skip",
+			reason: "noopOperation"
+		};
+		return {
+			type: "resolved",
+			operation: {
+				operation,
+				from,
+				to,
+				blockFrom,
+				blockTo,
+				blockNode
+			}
+		};
+	}
 	if (operation.type === "insertAfterBlock" || operation.type === "insertBeforeBlock") {
 		if (operation.text.length === 0 && operation.pageBreakBefore !== true) return {
 			type: "skip",
@@ -623,7 +702,8 @@ const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId,
 		type: "skip",
 		reason: "noopOperation"
 	};
-	const range = resolveTextInCleanBlock(cleanBlock, getOperationQuote(operation) || currentText);
+	const quote = getOperationQuote(operation);
+	const range = resolveTextInCleanBlock(cleanBlock, quote || currentText);
 	if (range.type !== "resolved") return range;
 	return {
 		type: "resolved",
@@ -674,10 +754,10 @@ const getTextRangeFromCleanBlock = (cleanBlock) => {
 		to
 	};
 };
-const getOperationCommentText = (operation) => operation.comment?.text;
+const getOperationCommentText = (operation) => "comment" in operation ? operation.comment?.text : void 0;
 const getOperationQuote = (operation) => {
 	if (operation.type === "replaceInBlock") return operation.find;
 	if (operation.type === "commentOnBlock") return operation.quote;
 };
 //#endregion
-export { applyFolioAIEditOperations };
+export { applyFolioAIEditOperations, previewFolioAIEditOperations };

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

@@ -0,0 +1,33 @@
+import { FolioAIEditSnapshot } from "./types.js";
+import { Node } from "prosemirror-model";
+
+//#region src/ai-edits/blockRange.d.ts
+type DocPositionRange = {
+  from: number;
+  to: number;
+};
+type ResolveFolioAIBlockRangeOptions = {
+  blockId: string;
+  doc: Node;
+  snapshot?: FolioAIEditSnapshot | null | undefined;
+};
+declare const resolveFolioAIBlockRange: ({
+  blockId,
+  doc,
+  snapshot
+}: ResolveFolioAIBlockRangeOptions) => DocPositionRange | null;
+/**
+ * Clamp a `{from, to}` pair so both endpoints fit inside a document of
+ * `docSize` (in PM content positions). Block-boundary snapshots and stale
+ * range data sometimes produce a `to` one past the last inline position;
+ * `view.state.doc.resolve(...)` rejects that with
+ * "Position … out of range", and `TextSelection.between` doesn't help — it
+ * needs *valid* resolved positions. Clamping before resolution is the cheap
+ * defensive step.
+ *
+ * Order is preserved: if both endpoints exceed `docSize`, the returned
+ * `from` may equal `to`, yielding a cursor selection at the doc end.
+ */
+declare function clampRangeToDocSize(docSize: number, range: DocPositionRange): DocPositionRange;
+//#endregion
+export { DocPositionRange, clampRangeToDocSize, resolveFolioAIBlockRange };

package/dist/ai-edits/blockRange.js

@@ -0,0 +1,58 @@
+import { getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex } from "../types/block-id.js";
+import { createFolioAIEditSnapshot } from "./snapshot.js";
+import { findParagraphByParaId } from "../prosemirror/utils/findParagraphByParaId.js";
+//#region src/ai-edits/blockRange.ts
+const resolveFolioAIBlockRange = ({ blockId, doc, snapshot }) => {
+	const paraId = getFolioParaIdFromBlockId(blockId);
+	if (paraId !== null) {
+		const liveRange = findParagraphByParaId(doc, paraId);
+		if (liveRange !== null) return {
+			from: liveRange.from,
+			to: liveRange.to
+		};
+	}
+	const resolvedSnapshot = snapshot ?? createFolioAIEditSnapshot(doc);
+	const anchor = resolvedSnapshot.anchors[blockId] ?? resolveSequentialBlockAnchor(blockId, resolvedSnapshot);
+	if (!anchor) return null;
+	return clampRangeToDocSize(doc.content.size, anchor);
+};
+/**
+* Resolve a `seq-NNNN` fallback id by document position.
+*
+* A sequential id is only minted for a paragraph the source DOCX left
+* without a `w14:paraId`. The live editor's `ParaIdAllocator` fills
+* that gap with a fresh random hex paraId, so a snapshot of the live
+* document keys the block by that hex and never reproduces the
+* server's `seq-NNNN`: the direct anchor lookup misses, and a
+* paraId-based live lookup can't match either (no node carries a
+* `seq-` paraId). The seq number is the block's 1-based position in
+* the same non-empty-block walk the server extractor and
+* `createFolioAIEditSnapshot` share, so it indexes the snapshot's
+* ordered `blocks` directly.
+*/
+const resolveSequentialBlockAnchor = (blockId, snapshot) => {
+	const index = getSequentialFolioBlockIdIndex(blockId);
+	if (index === null) return;
+	const block = snapshot.blocks.at(index - 1);
+	return block ? snapshot.anchors[block.id] : void 0;
+};
+/**
+* Clamp a `{from, to}` pair so both endpoints fit inside a document of
+* `docSize` (in PM content positions). Block-boundary snapshots and stale
+* range data sometimes produce a `to` one past the last inline position;
+* `view.state.doc.resolve(...)` rejects that with
+* "Position … out of range", and `TextSelection.between` doesn't help — it
+* needs *valid* resolved positions. Clamping before resolution is the cheap
+* defensive step.
+*
+* Order is preserved: if both endpoints exceed `docSize`, the returned
+* `from` may equal `to`, yielding a cursor selection at the doc end.
+*/
+function clampRangeToDocSize(docSize, range) {
+	return {
+		from: Math.min(Math.max(range.from, 0), docSize),
+		to: Math.min(Math.max(range.to, 0), docSize)
+	};
+}
+//#endregion
+export { clampRangeToDocSize, resolveFolioAIBlockRange };

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

@@ -1,11 +1,13 @@
 import { FolioAIBlock, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
 import { document_d_exports } from "../types/document.js";
+import { FolioDocumentOperationBatch, FolioDocumentOperationResult } from "../document-operations.js";
 import { FolioReviewChange, FolioReviewChangeKind } from "./read.js";
 
 //#region src/ai-edits/headless.d.ts
 /** Options for {@link FolioDocxReviewer.fromBuffer}. */
 type FolioDocxReviewerOptions = {
-  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string;
+  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined;
 };
 /** Options for {@link FolioDocxReviewer.applyOperations}. */
 type FolioApplyOperationsOptions = {
@@ -17,6 +19,8 @@ type FolioApplyOperationsOptions = {
    */
   snapshot?: FolioAIEditSnapshot;
 };
+/** Options for {@link FolioDocxReviewer.applyDocumentOperations}. */
+type FolioApplyDocumentOperationsOptions = Omit<FolioApplyOperationsOptions, "mode">;
 /** Options for {@link FolioDocxReviewer.getContentAsText}. */
 type FolioGetContentAsTextOptions = {
   /**
@@ -26,6 +30,19 @@ type FolioGetContentAsTextOptions = {
    */
   annotated?: boolean;
 };
+type FolioDocumentStoryHandle = {
+  type: "main";
+} | {
+  type: "header" | "footer";
+  relationshipId: string;
+} | {
+  type: "footnote" | "endnote";
+  noteId: number;
+};
+type FolioDocumentStory = {
+  handle: FolioDocumentStoryHandle;
+  text: string;
+};
 /** Filter for {@link FolioDocxReviewer.getChanges}. */
 type FolioReviewChangeFilter = {
   author?: string;
@@ -104,6 +121,13 @@ declare class FolioDocxReviewer {
    * (including any comments) is retained for {@link toBuffer}.
    */
   applyOperations(operations: FolioAIEditOperation[], options?: FolioApplyOperationsOptions): FolioAIEditApplyResult;
+  /**
+   * Apply a versioned document-operation batch against the current state.
+   * This is the contract entry point for serialized callers; the legacy
+   * {@link applyOperations} method delegates here so both APIs keep identical
+   * edit semantics.
+   */
+  applyDocumentOperations(batch: FolioDocumentOperationBatch, options?: FolioApplyDocumentOperationsOptions): FolioDocumentOperationResult;
   /**
    * The body blocks with their stable ids, in document order — the same
    * `FolioAIBlock` shape {@link snapshot} builds, reused verbatim so the ids
@@ -130,6 +154,10 @@ declare class FolioDocxReviewer {
    * Empty parts and separator notes are omitted.
    */
   getNotesAsText(): string;
+  /** 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. */
+  readStory(handle: FolioDocumentStoryHandle): FolioDocumentStory | null;
   /**
    * The tracked changes (insertions and deletions) present in the body, read
    * from the same `insertion` / `deletion` marks the editor renders. Each
@@ -209,9 +237,11 @@ declare class FolioDocxReviewer {
   private trySelectiveSave;
   /**
    * Count every tracked change an accept-all / reject-all sweep resolves: the
-   * inline insertion / deletion groups {@link getChanges} enumerates, plus
-   * paragraph-level changes (`pPrMark`, `_propertyChanges`) that live on
-   * paragraph attrs rather than inline marks.
+   * inline insertion / deletion groups {@link getChanges} enumerates, plus the
+   * property-change records living on node attrs rather than inline marks —
+   * paragraph-level (`pPrMark`, `_propertyChanges`, the inline sectPr's
+   * `propertyChanges`) and table-level (`tblPrChange` / `trPrChange` /
+   * `tcPrChange`).
    */
   private countTrackedChanges;
   /** Apply any {@link resolveComment} overrides recorded for these comments. */
@@ -249,4 +279,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyOperationsOptions, FolioDocxReviewer, FolioDocxReviewerOptions, FolioGetContentAsTextOptions, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyDocumentOperationsOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocxReviewer, FolioDocxReviewerOptions, FolioGetContentAsTextOptions, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer };

package/dist/ai-edits/headless.js

@@ -1,9 +1,9 @@
+import { buildAnnotatedBlockText } from "./clean-text.js";
+import { createFolioAIEditSnapshot, normalizeFolioAIBlockText } from "./snapshot.js";
+import { applyFolioDocumentOperations } from "../document-operations.js";
 import { getEndnoteText, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote } from "../docx/footnoteParser.js";
 import { deterministicHexId } from "../utils/hexId.js";
 import { repackDocx } from "../docx/rezip.js";
-import { buildAnnotatedBlockText } from "./clean-text.js";
-import { createFolioAIEditSnapshot, normalizeFolioAIBlockText } from "./snapshot.js";
-import { applyFolioAIEditOperations } from "./apply.js";
 import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
 import { createReply } from "../docx/replyToComment.js";
 import { attemptSelectiveSave } from "../docx/selectiveSave.js";
@@ -181,17 +181,19 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	static async fromBuffer(buffer, options = {}) {
 		const baseDocument = await parseDocx(buffer, {
 			detectVariables: false,
-			preloadFonts: false
+			preloadFonts: false,
+			password: options.password
 		});
 		const plugins = singletonManager.getPlugins();
+		const state = ensureDeterministicParaIdsInState(EditorState.create({
+			schema,
+			doc: toProseDoc(baseDocument),
+			plugins
+		}));
 		return new FolioDocxReviewer({
 			baseDocument,
-			originalBuffer: buffer,
-			state: ensureDeterministicParaIdsInState(EditorState.create({
-				schema,
-				doc: toProseDoc(baseDocument),
-				plugins
-			})),
+			originalBuffer: baseDocument.originalBuffer ?? buffer,
+			state,
 			author: options.author ?? "AI"
 		});
 	}
@@ -208,18 +210,33 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* (including any comments) is retained for {@link toBuffer}.
 	*/
 	applyOperations(operations, options = {}) {
-		const snapshot = options.snapshot ?? this.snapshot();
+		const { applied, skipped } = this.applyDocumentOperations({
+			version: 1,
+			operations,
+			mode: options.mode ?? "tracked-changes"
+		}, { ...options.snapshot !== void 0 && { snapshot: options.snapshot } });
+		return {
+			applied,
+			skipped
+		};
+	}
+	/**
+	* Apply a versioned document-operation batch against the current state.
+	* This is the contract entry point for serialized callers; the legacy
+	* {@link applyOperations} method delegates here so both APIs keep identical
+	* edit semantics.
+	*/
+	applyDocumentOperations(batch, options = {}) {
 		const view = {
 			state: this.state,
 			dispatch: (transaction) => {
 				view.state = view.state.apply(transaction);
 			}
 		};
-		const result = applyFolioAIEditOperations({
+		const result = applyFolioDocumentOperations({
 			view,
-			snapshot,
-			operations,
-			mode: options.mode ?? "tracked-changes",
+			snapshot: options.snapshot ?? this.snapshot(),
+			batch,
 			author: this.author,
 			createCommentId: (text) => {
 				const comment = createReviewerComment(text, this.author);
@@ -257,7 +274,8 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		return snapshot.blocks.map((block) => {
 			const from = startById.get(block.id);
 			const node = from === void 0 ? null : this.state.doc.nodeAt(from);
-			return formatBlockLine(block, node ? buildAnnotatedBlockText(node) : block.text);
+			const text = node ? buildAnnotatedBlockText(node) : block.text;
+			return formatBlockLine(block, text);
 		}).join("\n");
 	}
 	/**
@@ -291,6 +309,50 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		}
 		return lines.join("\n");
 	}
+	/** 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 ?? []) stories.push({
+			handle: {
+				type: "header",
+				relationshipId
+			},
+			text: normalizeFolioAIBlockText(getHeaderFooterText(header))
+		});
+		for (const [relationshipId, footer] of pkg.footers ?? []) stories.push({
+			handle: {
+				type: "footer",
+				relationshipId
+			},
+			text: normalizeFolioAIBlockText(getHeaderFooterText(footer))
+		});
+		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) stories.push({
+			handle: {
+				type: "footnote",
+				noteId: footnote.id
+			},
+			text: normalizeFolioAIBlockText(getFootnoteText(footnote))
+		});
+		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) stories.push({
+			handle: {
+				type: "endnote",
+				noteId: endnote.id
+			},
+			text: normalizeFolioAIBlockText(getEndnoteText(endnote))
+		});
+		return stories;
+	}
+	/** Read one discovered story; returns null when its handle is no longer present. */
+	readStory(handle) {
+		const stories = this.listStories();
+		if (handle.type === "main") return stories.at(0) ?? null;
+		if (handle.type === "header" || handle.type === "footer") return stories.find(({ handle: candidate }) => candidate.type === handle.type && candidate.relationshipId === handle.relationshipId) ?? null;
+		return stories.find(({ handle: candidate }) => (candidate.type === "footnote" || candidate.type === "endnote") && candidate.type === handle.type && candidate.noteId === handle.noteId) ?? null;
+	}
 	/**
 	* The tracked changes (insertions and deletions) present in the body, read
 	* from the same `insertion` / `deletion` marks the editor renders. Each
@@ -462,18 +524,26 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	}
 	/**
 	* Count every tracked change an accept-all / reject-all sweep resolves: the
-	* inline insertion / deletion groups {@link getChanges} enumerates, plus
-	* paragraph-level changes (`pPrMark`, `_propertyChanges`) that live on
-	* paragraph attrs rather than inline marks.
+	* inline insertion / deletion groups {@link getChanges} enumerates, plus the
+	* property-change records living on node attrs rather than inline marks —
+	* paragraph-level (`pPrMark`, `_propertyChanges`, the inline sectPr's
+	* `propertyChanges`) and table-level (`tblPrChange` / `trPrChange` /
+	* `tcPrChange`).
 	*/
 	countTrackedChanges() {
+		const hasEntries = (value) => Array.isArray(value) && value.length > 0;
 		let count = this.getChanges().length;
 		this.state.doc.descendants((node) => {
-			if (node.type.name !== "paragraph") return;
+			const typeName = node.type.name;
+			if (typeName === "table" && hasEntries(node.attrs["tblPrChange"])) count += 1;
+			if (typeName === "tableRow" && hasEntries(node.attrs["trPrChange"])) count += 1;
+			if ((typeName === "tableCell" || typeName === "tableHeader") && hasEntries(node.attrs["tcPrChange"])) count += 1;
+			if (typeName !== "paragraph") return;
 			const pPrMark = node.attrs["pPrMark"];
 			if (pPrMark !== null && pPrMark !== void 0) count += 1;
-			const propertyChanges = node.attrs["_propertyChanges"];
-			if (Array.isArray(propertyChanges) && propertyChanges.length > 0) count += 1;
+			if (hasEntries(node.attrs["_propertyChanges"])) count += 1;
+			const sectionProperties = node.attrs["_sectionProperties"];
+			if (hasEntries(sectionProperties?.propertyChanges)) count += 1;
 			return false;
 		});
 		return count;

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

@@ -1,8 +1,10 @@
-import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAISignatureParty } from "./types.js";
+import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAISignatureParty, FolioAITextRangeHandle } from "./types.js";
 import { FolioAIEditView, applyFolioAIEditOperations } from "./apply.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
+import { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationStatus, FolioDocumentOperationType, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
-import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
+import { FolioDocumentStory, FolioDocumentStoryHandle } from "./headless.js";
+import { createFolioAIEditSnapshot, createFolioAITextRangeHandle, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
 import { getFolioParaIdFromBlockId } from "../types/block-id.js";
 import { WordDiffSegment, diffWordSegments } from "./word-diff.js";
-export { type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIEditView, type FolioAISignatureParty, type FolioCommentAnchor, type FolioReviewChange, type FolioReviewChangeKind, type WordDiffSegment, applyFolioAIEditOperations, buildAnnotatedBlockText, createFolioAIEditSnapshot, diffWordSegments, getCommentAnchorsFromDoc, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, normalizeFolioAIBlockText };
+export { type ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIEditView, type FolioAIInlineFormatting, type FolioAISignatureParty, type FolioAITextRangeHandle, type FolioCommentAnchor, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationType, type FolioDocumentStory, type FolioDocumentStoryHandle, type FolioReviewChange, type FolioReviewChangeKind, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, type WordDiffSegment, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch };

package/dist/ai-edits/index.js

@@ -1,7 +1,8 @@
 import { getFolioParaIdFromBlockId } from "../types/block-id.js";
 import { buildAnnotatedBlockText } from "./clean-text.js";
-import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
+import { createFolioAIEditSnapshot, createFolioAITextRangeHandle, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
 import { diffWordSegments } from "./word-diff.js";
 import { applyFolioAIEditOperations } from "./apply.js";
+import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
-export { applyFolioAIEditOperations, buildAnnotatedBlockText, createFolioAIEditSnapshot, diffWordSegments, getCommentAnchorsFromDoc, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, normalizeFolioAIBlockText };
+export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch };

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

@@ -1,9 +1,21 @@
-import { FolioAIEditSnapshot } from "./types.js";
+import { FolioAIEditSnapshot, FolioAITextRangeHandle } from "./types.js";
 import { Node } from "prosemirror-model";
 
 //#region src/ai-edits/snapshot.d.ts
 declare const normalizeFolioAIBlockText: (text: string) => string;
 declare const hashFolioAIBlockText: (text: string) => string;
+type CreateFolioAITextRangeHandleOptions = {
+  blockId: string;
+  text: string;
+  startOffset: number;
+  endOffset: number;
+};
+declare const createFolioAITextRangeHandle: ({
+  blockId,
+  text,
+  startOffset,
+  endOffset
+}: CreateFolioAITextRangeHandleOptions) => FolioAITextRangeHandle | null;
 declare const createFolioAIEditSnapshot: (doc: Node) => FolioAIEditSnapshot;
 //#endregion
-export { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText };
+export { createFolioAIEditSnapshot, createFolioAITextRangeHandle, hashFolioAIBlockText, normalizeFolioAIBlockText };