@stll/folio-core 0.2.0 → 0.3.1

package/README.md

@@ -12,8 +12,8 @@ changes, and footnotes.
 
 There is **no React** in the import graph, so the core runs on a server or under
 any framework. The React editor lives in
-[`@stll/folio-react`](https://www.npmjs.com/package/@stll/folio-react); a Vue or
-Tauri adapter could build on this same core.
+[`@stll/folio-react`](https://www.npmjs.com/package/@stll/folio-react), and the
+Vue editor lives in [`@stll/folio-vue`](https://www.npmjs.com/package/@stll/folio-vue).
 
 Part of [stella](https://github.com/stella/stella), an open-source legal workspace.
 

package/dist/ai-edits/clean-text.d.ts

@@ -24,5 +24,25 @@ type CleanBlockText = {
   offsets: number[];
 };
 declare const buildCleanBlockText: (blockNode: Node, blockFrom: number) => CleanBlockText;
+/**
+ * A "redline-aware" view of a textblock: the same left-to-right traversal as
+ * {@link buildCleanBlockText}, but every tracked change and comment anchor is
+ * rendered inline with a simple tag rather than being flattened away:
+ *
+ * - `<ins author="…">text</ins>` for insertion-marked runs,
+ * - `<del author="…">text</del>` for deletion-marked runs (tracked moves
+ *   surface as plain ins/del, since a move carries the same marks),
+ * - `<comment id="N">quoted text</comment>` for comment-anchored runs.
+ *
+ * Nested annotations (e.g. an inserted run that is also commented) nest their
+ * tags in a stable `comment > ins > del` order. Text content and attribute
+ * values are XML-escaped so the tags stay unambiguous when embedded in a
+ * prompt. Adjacent runs sharing the same annotation coalesce into one tag.
+ *
+ * This is the view a consumer embeds when it wants the model to reason about
+ * the redline itself, in contrast to {@link buildCleanBlockText}'s
+ * post-tracked-changes view.
+ */
+declare const buildAnnotatedBlockText: (blockNode: Node) => string;
 //#endregion
-export { CleanBlockText, buildCleanBlockText };
+export { CleanBlockText, buildAnnotatedBlockText, buildCleanBlockText };

package/dist/ai-edits/clean-text.js

@@ -1,5 +1,7 @@
 //#region src/ai-edits/clean-text.ts
 const DELETION_MARK = "deletion";
+const INSERTION_MARK = "insertion";
+const COMMENT_MARK = "comment";
 const buildCleanBlockText = (blockNode, blockFrom) => {
 	let text = "";
 	const offsets = [];
@@ -19,5 +21,71 @@ const buildCleanBlockText = (blockNode, blockFrom) => {
 		offsets
 	};
 };
+/**
+* A "redline-aware" view of a textblock: the same left-to-right traversal as
+* {@link buildCleanBlockText}, but every tracked change and comment anchor is
+* rendered inline with a simple tag rather than being flattened away:
+*
+* - `<ins author="…">text</ins>` for insertion-marked runs,
+* - `<del author="…">text</del>` for deletion-marked runs (tracked moves
+*   surface as plain ins/del, since a move carries the same marks),
+* - `<comment id="N">quoted text</comment>` for comment-anchored runs.
+*
+* Nested annotations (e.g. an inserted run that is also commented) nest their
+* tags in a stable `comment > ins > del` order. Text content and attribute
+* values are XML-escaped so the tags stay unambiguous when embedded in a
+* prompt. Adjacent runs sharing the same annotation coalesce into one tag.
+*
+* This is the view a consumer embeds when it wants the model to reason about
+* the redline itself, in contrast to {@link buildCleanBlockText}'s
+* post-tracked-changes view.
+*/
+const buildAnnotatedBlockText = (blockNode) => {
+	const segments = [];
+	blockNode.descendants((node) => {
+		if (!node.isText || node.text === void 0) return true;
+		const annotation = annotationOf(node.marks);
+		const previous = segments.at(-1);
+		if (previous && sameAnnotation(previous.annotation, annotation)) {
+			previous.text += node.text;
+			return false;
+		}
+		segments.push({
+			annotation,
+			text: node.text
+		});
+		return false;
+	});
+	return segments.map(renderAnnotatedSegment).join("");
+};
+const authorOf = (attrs) => {
+	const author = attrs["author"];
+	return typeof author === "string" ? author : "";
+};
+const annotationOf = (marks) => {
+	let commentId = null;
+	let insertionAuthor = null;
+	let deletionAuthor = null;
+	for (const mark of marks) if (mark.type.name === COMMENT_MARK) {
+		const id = mark.attrs["commentId"];
+		if (typeof id === "number") commentId = id;
+	} else if (mark.type.name === INSERTION_MARK) insertionAuthor = authorOf(mark.attrs);
+	else if (mark.type.name === DELETION_MARK) deletionAuthor = authorOf(mark.attrs);
+	return {
+		commentId,
+		insertionAuthor,
+		deletionAuthor
+	};
+};
+const sameAnnotation = (a, b) => a.commentId === b.commentId && a.insertionAuthor === b.insertionAuthor && a.deletionAuthor === b.deletionAuthor;
+const escapeText = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const escapeAttr = (value) => escapeText(value).replaceAll("\"", "&quot;");
+const renderAnnotatedSegment = ({ annotation, text }) => {
+	let inner = escapeText(text);
+	if (annotation.deletionAuthor !== null) inner = `<del author="${escapeAttr(annotation.deletionAuthor)}">${inner}</del>`;
+	if (annotation.insertionAuthor !== null) inner = `<ins author="${escapeAttr(annotation.insertionAuthor)}">${inner}</ins>`;
+	if (annotation.commentId !== null) inner = `<comment id="${annotation.commentId}">${inner}</comment>`;
+	return inner;
+};
 //#endregion
-export { buildCleanBlockText };
+export { buildAnnotatedBlockText, buildCleanBlockText };

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

@@ -1,5 +1,6 @@
 import { FolioAIBlock, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
 import { document_d_exports } from "../types/document.js";
+import { FolioReviewChange, FolioReviewChangeKind } from "./read.js";
 
 //#region src/ai-edits/headless.d.ts
 /** Options for {@link FolioDocxReviewer.fromBuffer}. */
@@ -16,26 +17,14 @@ type FolioApplyOperationsOptions = {
    */
   snapshot?: FolioAIEditSnapshot;
 };
-type FolioReviewChangeKind = "insertion" | "deletion";
-/** A tracked change (insertion or deletion) discovered in the document body. */
-type FolioReviewChange = {
+/** Options for {@link FolioDocxReviewer.getContentAsText}. */
+type FolioGetContentAsTextOptions = {
   /**
-   * The tracked-change revision id — the OOXML `w:id` carried on the
-   * insertion / deletion mark. Pass it (or the whole change) to
-   * {@link FolioDocxReviewer.acceptChange} / `rejectChange`. A replace produces
-   * two changes (a deletion side and an insertion side) with distinct ids.
+   * Render tracked changes and comment anchors inline as `<ins>` / `<del>` /
+   * `<comment>` tags instead of the default flattened, post-tracked-changes
+   * text. (default: `false`)
    */
-  id: number;
-  type: FolioReviewChangeKind;
-  author: string; /** ISO date the change was authored, or `null` when the source omitted it. */
-  date: string | null; /** Inserted text for insertions, removed text for deletions. */
-  text: string;
-  /**
-   * Stable id of the containing body block (Word `w14:paraId` or `seq-NNNN`),
-   * matching {@link FolioDocxReviewer.getContent}. `null` when the change sits
-   * in a block with no surviving visible text, which has no snapshot block.
-   */
-  blockId: string | null;
+  annotated?: boolean;
 };
 /** Filter for {@link FolioDocxReviewer.getChanges}. */
 type FolioReviewChangeFilter = {
@@ -92,6 +81,15 @@ declare class FolioDocxReviewer {
   private readonly originalBuffer;
   private state;
   private readonly createdComments;
+  /**
+   * Resolved-state overrides recorded by {@link resolveComment}, keyed by
+   * comment id. Applied on read ({@link getComments}) and on write
+   * ({@link toDocument}) rather than mutating the parsed `Comment` objects in
+   * place, matching how the parser/serializer treat `Comment` as immutable
+   * (`commentParser.ts` replaces array slots via spread; the serializer
+   * types its inputs `readonly Comment[]`).
+   */
+  private readonly resolvedOverrides;
   private constructor();
   /** Parse a `.docx` buffer into a reviewer. */
   static fromBuffer(buffer: ArrayBuffer, options?: FolioDocxReviewerOptions): Promise<FolioDocxReviewer>;
@@ -116,8 +114,22 @@ declare class FolioDocxReviewer {
    * The body as LLM-ready plain text: one line per block, each prefixed with
    * its stable block id (`[<blockId>] text`). Copyable verbatim into a prompt
    * without JSON quote-escaping.
+   *
+   * With `{ annotated: true }` each block's text is rendered redline-aware:
+   * tracked insertions/deletions and comment anchors appear inline as
+   * `<ins>` / `<del>` / `<comment>` tags (see {@link buildAnnotatedBlockText})
+   * for prompt-embedding parity with a live editor's redline view. The default
+   * (clean) output flattens tracked changes and is unchanged.
    */
-  getContentAsText(): string;
+  getContentAsText(options?: FolioGetContentAsTextOptions): string;
+  /**
+   * Header / footer and footnote / endnote text as labeled, LLM-ready lines,
+   * one per non-empty part: `[header default] …`, `[footer default] …`,
+   * `[footnote #N] …`, `[endnote #N] …`. Read-only — note bodies are outside
+   * the reviewer's body-only apply scope, so this reflects the parsed source.
+   * Empty parts and separator notes are omitted.
+   */
+  getNotesAsText(): string;
   /**
    * The tracked changes (insertions and deletions) present in the body, read
    * from the same `insertion` / `deletion` marks the editor renders. Each
@@ -141,6 +153,21 @@ declare class FolioDocxReviewer {
    * the created reply, or `null` when the target comment is absent.
    */
   replyTo(target: FolioReviewComment | number, input: FolioReviewReplyInput): FolioReviewCommentReply | null;
+  /**
+   * Mark a comment thread resolved, or reopen a previously resolved one. Pass
+   * the id from {@link getComments} / {@link FolioReviewComment.id}. Applies
+   * only to the target comment id, not cascaded to its replies: Word keys the
+   * resolved marker off the comment's own `w15:commentEx` entry
+   * (`commentSerializer.ts`'s `buildCommentExtendedEntries` reads only
+   * `comment.done` for the id it is building an entry for), so resolving the
+   * thread root is sufficient and reply entries need no `done` flag of their
+   * own. On {@link toBuffer} the state is written to `commentsExtended.xml`
+   * (`w15:done`) through the same channel `replyTo`-created comments use.
+   * Returns `false` when no comment with that id exists.
+   */
+  resolveComment(commentId: string, options?: {
+    resolved?: boolean;
+  }): boolean;
   /**
    * Accept an existing tracked change, keeping its text and dropping the
    * redline. Pass a {@link FolioReviewChange} from {@link getChanges} or its
@@ -187,8 +214,8 @@ declare class FolioDocxReviewer {
    * paragraph attrs rather than inline marks.
    */
   private countTrackedChanges;
-  /** Map each snapshot block's start position to its stable id. */
-  private blockStartIds;
+  /** Apply any {@link resolveComment} overrides recorded for these comments. */
+  private withResolvedOverrides;
   /** Map each anchored comment id to its anchored text and containing block id. */
   private commentAnchors;
   /**
@@ -222,4 +249,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyOperationsOptions, FolioDocxReviewer, FolioDocxReviewerOptions, FolioReviewChange, FolioReviewChangeFilter, FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyOperationsOptions, FolioDocxReviewer, FolioDocxReviewerOptions, FolioGetContentAsTextOptions, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer };

package/dist/ai-edits/headless.js

@@ -1,9 +1,13 @@
+import { getEndnoteText, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote } from "../docx/footnoteParser.js";
 import { deterministicHexId } from "../utils/hexId.js";
 import { repackDocx } from "../docx/rezip.js";
-import { createFolioAIEditSnapshot } from "./snapshot.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";
+import { getHeaderFooterText } from "../docx/headerFooterParser.js";
 import { parseDocx } from "../docx/parser.js";
 import { acceptAIEditRevision, acceptAllChanges, rejectAIEditRevision, rejectAllChanges } from "../prosemirror/commands/comments.js";
 import { updateDocumentContent } from "../prosemirror/conversion/fromProseDoc.js";
@@ -114,12 +118,13 @@ const ensureDeterministicParaIdsInState = (state) => {
 * for headings and the list marker for list items, so a model can copy the
 * block id straight back into an operation.
 */
-const formatBlockForLLM = (block) => {
+const formatBlockLine = (block, text) => {
 	const label = `[${block.id}]`;
-	if (block.kind === "heading") return `${label} (h${headingLevel(block)}) ${block.text}`;
-	if (block.kind === "listItem") return `${label} ${block.displayLabel ?? "•"} ${block.text}`;
-	return `${label} ${block.text}`;
+	if (block.kind === "heading") return `${label} (h${headingLevel(block)}) ${text}`;
+	if (block.kind === "listItem") return `${label} ${block.displayLabel ?? "•"} ${text}`;
+	return `${label} ${text}`;
 };
+const formatBlockForLLM = (block) => formatBlockLine(block, block.text);
 const headingLevel = (block) => {
 	const digits = /(\d+)/u.exec(block.styleId ?? block.displayLabel ?? "")?.[1];
 	const level = digits ? Number.parseInt(digits, 10) : 1;
@@ -157,6 +162,15 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	originalBuffer;
 	state;
 	createdComments = [];
+	/**
+	* Resolved-state overrides recorded by {@link resolveComment}, keyed by
+	* comment id. Applied on read ({@link getComments}) and on write
+	* ({@link toDocument}) rather than mutating the parsed `Comment` objects in
+	* place, matching how the parser/serializer treat `Comment` as immutable
+	* (`commentParser.ts` replaces array slots via spread; the serializer
+	* types its inputs `readonly Comment[]`).
+	*/
+	resolvedOverrides = /* @__PURE__ */ new Map();
 	constructor(args) {
 		this.baseDocument = args.baseDocument;
 		this.originalBuffer = args.originalBuffer;
@@ -228,9 +242,54 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* The body as LLM-ready plain text: one line per block, each prefixed with
 	* its stable block id (`[<blockId>] text`). Copyable verbatim into a prompt
 	* without JSON quote-escaping.
+	*
+	* With `{ annotated: true }` each block's text is rendered redline-aware:
+	* tracked insertions/deletions and comment anchors appear inline as
+	* `<ins>` / `<del>` / `<comment>` tags (see {@link buildAnnotatedBlockText})
+	* for prompt-embedding parity with a live editor's redline view. The default
+	* (clean) output flattens tracked changes and is unchanged.
+	*/
+	getContentAsText(options = {}) {
+		if (!options.annotated) return this.getContent().map(formatBlockForLLM).join("\n");
+		const snapshot = this.snapshot();
+		const startById = /* @__PURE__ */ new Map();
+		for (const anchor of Object.values(snapshot.anchors)) startById.set(anchor.id, anchor.from);
+		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);
+		}).join("\n");
+	}
+	/**
+	* Header / footer and footnote / endnote text as labeled, LLM-ready lines,
+	* one per non-empty part: `[header default] …`, `[footer default] …`,
+	* `[footnote #N] …`, `[endnote #N] …`. Read-only — note bodies are outside
+	* the reviewer's body-only apply scope, so this reflects the parsed source.
+	* Empty parts and separator notes are omitted.
 	*/
-	getContentAsText() {
-		return this.getContent().map(formatBlockForLLM).join("\n");
+	getNotesAsText() {
+		const pkg = this.baseDocument.package;
+		const lines = [];
+		const pushHeaderFooter = (map, label) => {
+			if (!map) return;
+			for (const hf of map.values()) {
+				const text = normalizeFolioAIBlockText(getHeaderFooterText(hf));
+				if (text.length > 0) lines.push(`[${label} ${hf.hdrFtrType}] ${text}`);
+			}
+		};
+		pushHeaderFooter(pkg.headers, "header");
+		pushHeaderFooter(pkg.footers, "footer");
+		for (const footnote of pkg.footnotes ?? []) {
+			if (isSeparatorFootnote(footnote)) continue;
+			const text = normalizeFolioAIBlockText(getFootnoteText(footnote));
+			if (text.length > 0) lines.push(`[footnote #${footnote.id}] ${text}`);
+		}
+		for (const endnote of pkg.endnotes ?? []) {
+			if (isSeparatorEndnote(endnote)) continue;
+			const text = normalizeFolioAIBlockText(getEndnoteText(endnote));
+			if (text.length > 0) lines.push(`[endnote #${endnote.id}] ${text}`);
+		}
+		return lines.join("\n");
 	}
 	/**
 	* The tracked changes (insertions and deletions) present in the body, read
@@ -239,44 +298,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* against. Runs of one revision within a block fold into a single entry.
 	*/
 	getChanges(filter) {
-		const insertionType = this.state.schema.marks["insertion"];
-		const deletionType = this.state.schema.marks["deletion"];
-		const blockStarts = this.blockStartIds();
-		const grouped = /* @__PURE__ */ new Map();
-		let currentBlockId = null;
-		this.state.doc.descendants((node, pos) => {
-			if (node.isTextblock) {
-				currentBlockId = blockStarts.get(pos) ?? null;
-				return true;
-			}
-			if (!node.isInline || node.text === void 0) return;
-			const text = node.text;
-			for (const mark of node.marks) {
-				if (typeof mark.attrs["revisionId"] !== "number") continue;
-				let kind;
-				if (mark.type === insertionType) kind = "insertion";
-				else if (mark.type === deletionType) kind = "deletion";
-				else continue;
-				const revisionId = mark.attrs["revisionId"];
-				const key = `${currentBlockId ?? ""}:${kind}:${revisionId}`;
-				const existing = grouped.get(key);
-				if (existing) {
-					existing.text += text;
-					continue;
-				}
-				const author = mark.attrs["author"];
-				const date = mark.attrs["date"];
-				grouped.set(key, {
-					id: revisionId,
-					type: kind,
-					author: typeof author === "string" ? author : "",
-					date: typeof date === "string" ? date : null,
-					text,
-					blockId: currentBlockId
-				});
-			}
-		});
-		const changes = [...grouped.values()];
+		const changes = getTrackedChangesFromDoc(this.state.doc);
 		if (!filter) return changes;
 		return changes.filter((change) => (filter.author === void 0 || change.author === filter.author) && (filter.type === void 0 || change.type === filter.type));
 	}
@@ -287,7 +309,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* (nested tracked changes, hyperlinks) is out of scope.
 	*/
 	getComments(filter) {
-		const definitions = [...this.baseDocument.package.document.comments ?? [], ...this.createdComments];
+		const definitions = this.withResolvedOverrides([...this.baseDocument.package.document.comments ?? [], ...this.createdComments]);
 		if (definitions.length === 0) return [];
 		const anchors = this.commentAnchors();
 		const repliesByParent = /* @__PURE__ */ new Map();
@@ -347,6 +369,25 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		};
 	}
 	/**
+	* Mark a comment thread resolved, or reopen a previously resolved one. Pass
+	* the id from {@link getComments} / {@link FolioReviewComment.id}. Applies
+	* only to the target comment id, not cascaded to its replies: Word keys the
+	* resolved marker off the comment's own `w15:commentEx` entry
+	* (`commentSerializer.ts`'s `buildCommentExtendedEntries` reads only
+	* `comment.done` for the id it is building an entry for), so resolving the
+	* thread root is sufficient and reply entries need no `done` flag of their
+	* own. On {@link toBuffer} the state is written to `commentsExtended.xml`
+	* (`w15:done`) through the same channel `replyTo`-created comments use.
+	* Returns `false` when no comment with that id exists.
+	*/
+	resolveComment(commentId, options = {}) {
+		const resolved = options.resolved ?? true;
+		const target = [...this.baseDocument.package.document.comments ?? [], ...this.createdComments].find((comment) => String(comment.id) === commentId);
+		if (!target) return false;
+		this.resolvedOverrides.set(target.id, resolved);
+		return true;
+	}
+	/**
 	* Accept an existing tracked change, keeping its text and dropping the
 	* redline. Pass a {@link FolioReviewChange} from {@link getChanges} or its
 	* revision id. Reuses the editor's own accept command headlessly, so the
@@ -384,7 +425,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	/** The current document model with edits merged back in. */
 	toDocument() {
 		const document = updateDocumentContent(this.baseDocument, this.state.doc);
-		if (this.createdComments.length > 0) document.package.document.comments = [...document.package.document.comments ?? [], ...this.createdComments];
+		if (this.createdComments.length > 0 || this.resolvedOverrides.size > 0) document.package.document.comments = this.withResolvedOverrides([...document.package.document.comments ?? [], ...this.createdComments]);
 		return document;
 	}
 	/**
@@ -437,40 +478,23 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		});
 		return count;
 	}
-	/** Map each snapshot block's start position to its stable id. */
-	blockStartIds() {
-		const starts = /* @__PURE__ */ new Map();
-		for (const anchor of Object.values(this.snapshot().anchors)) starts.set(anchor.from, anchor.id);
-		return starts;
+	/** Apply any {@link resolveComment} overrides recorded for these comments. */
+	withResolvedOverrides(comments) {
+		if (this.resolvedOverrides.size === 0) return [...comments];
+		return comments.map((comment) => {
+			const override = this.resolvedOverrides.get(comment.id);
+			return override === void 0 ? comment : {
+				...comment,
+				done: override
+			};
+		});
 	}
 	/** Map each anchored comment id to its anchored text and containing block id. */
 	commentAnchors() {
-		const commentType = this.state.schema.marks["comment"];
 		const anchors = /* @__PURE__ */ new Map();
-		if (!commentType) return anchors;
-		const blockStarts = this.blockStartIds();
-		let currentBlockId = null;
-		this.state.doc.descendants((node, pos) => {
-			if (node.isTextblock) {
-				currentBlockId = blockStarts.get(pos) ?? null;
-				return true;
-			}
-			if (!node.isInline || node.text === void 0) return;
-			const text = node.text;
-			for (const mark of node.marks) {
-				if (mark.type !== commentType || typeof mark.attrs["commentId"] !== "number") continue;
-				const commentId = mark.attrs["commentId"];
-				const existing = anchors.get(commentId);
-				if (!existing) {
-					anchors.set(commentId, {
-						text,
-						blockId: currentBlockId
-					});
-					continue;
-				}
-				existing.text += text;
-				existing.blockId ??= currentBlockId;
-			}
+		for (const anchor of getCommentAnchorsFromDoc(this.state.doc)) anchors.set(anchor.commentId, {
+			text: anchor.quote,
+			blockId: anchor.blockId
 		});
 		return anchors;
 	}

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

@@ -1,6 +1,8 @@
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAISignatureParty } from "./types.js";
 import { FolioAIEditView, applyFolioAIEditOperations } from "./apply.js";
+import { buildAnnotatedBlockText } from "./clean-text.js";
+import { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
 import { createFolioAIEditSnapshot, 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 WordDiffSegment, applyFolioAIEditOperations, createFolioAIEditSnapshot, diffWordSegments, getFolioParaIdFromBlockId, hashFolioAIBlockText, normalizeFolioAIBlockText };
+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 };

package/dist/ai-edits/index.js

@@ -1,5 +1,7 @@
 import { getFolioParaIdFromBlockId } from "../types/block-id.js";
+import { buildAnnotatedBlockText } from "./clean-text.js";
 import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
 import { diffWordSegments } from "./word-diff.js";
 import { applyFolioAIEditOperations } from "./apply.js";
-export { applyFolioAIEditOperations, createFolioAIEditSnapshot, diffWordSegments, getFolioParaIdFromBlockId, hashFolioAIBlockText, normalizeFolioAIBlockText };
+import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
+export { applyFolioAIEditOperations, buildAnnotatedBlockText, createFolioAIEditSnapshot, diffWordSegments, getCommentAnchorsFromDoc, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, normalizeFolioAIBlockText };

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

@@ -0,0 +1,43 @@
+import { Node } from "prosemirror-model";
+
+//#region src/ai-edits/read.d.ts
+type FolioReviewChangeKind = "insertion" | "deletion";
+/** A tracked change (insertion or deletion) discovered in the document body. */
+type FolioReviewChange = {
+  /**
+   * The tracked-change revision id — the OOXML `w:id` carried on the
+   * insertion / deletion mark. A replace produces two changes (a deletion side
+   * and an insertion side) with distinct ids.
+   */
+  id: number;
+  type: FolioReviewChangeKind;
+  author: string; /** ISO date the change was authored, or `null` when the source omitted it. */
+  date: string | null; /** Inserted text for insertions, removed text for deletions. */
+  text: string;
+  /**
+   * Stable id of the containing body block (Word `w14:paraId` or `seq-NNNN`).
+   * `null` when the change sits in a block with no surviving visible text,
+   * which has no snapshot block.
+   */
+  blockId: string | null;
+};
+/** A comment anchor (the ranged text a comment marks) discovered in the body. */
+type FolioCommentAnchor = {
+  commentId: number; /** Stable id of the anchored body block, or `null` when the anchor is absent. */
+  blockId: string | null; /** The document text the comment is anchored to. */
+  quote: string;
+};
+/**
+ * The tracked changes (insertions and deletions) present in the body, read from
+ * the `insertion` / `deletion` marks the editor renders. Runs of one revision
+ * within a block fold into a single entry.
+ */
+declare const getTrackedChangesFromDoc: (doc: Node) => FolioReviewChange[];
+/**
+ * The comment anchors present in the body, read from the `comment` mark the
+ * editor renders. Each entry carries the anchored text and containing block id;
+ * runs of one comment id within the body fold into a single anchor.
+ */
+declare const getCommentAnchorsFromDoc: (doc: Node) => FolioCommentAnchor[];
+//#endregion
+export { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };

package/dist/ai-edits/read.js

@@ -0,0 +1,91 @@
+import { createFolioAIEditSnapshot } from "./snapshot.js";
+//#region src/ai-edits/read.ts
+/** Map each snapshot block's start position to its stable id. */
+const blockStartIdsFromDoc = (doc) => {
+	const starts = /* @__PURE__ */ new Map();
+	for (const anchor of Object.values(createFolioAIEditSnapshot(doc).anchors)) starts.set(anchor.from, anchor.id);
+	return starts;
+};
+/**
+* The tracked changes (insertions and deletions) present in the body, read from
+* the `insertion` / `deletion` marks the editor renders. Runs of one revision
+* within a block fold into a single entry.
+*/
+const getTrackedChangesFromDoc = (doc) => {
+	const insertionType = doc.type.schema.marks["insertion"];
+	const deletionType = doc.type.schema.marks["deletion"];
+	const blockStarts = blockStartIdsFromDoc(doc);
+	const grouped = /* @__PURE__ */ new Map();
+	let currentBlockId = null;
+	doc.descendants((node, pos) => {
+		if (node.isTextblock) {
+			currentBlockId = blockStarts.get(pos) ?? null;
+			return true;
+		}
+		if (!node.isInline || node.text === void 0) return;
+		const text = node.text;
+		for (const mark of node.marks) {
+			if (typeof mark.attrs["revisionId"] !== "number") continue;
+			let kind;
+			if (mark.type === insertionType) kind = "insertion";
+			else if (mark.type === deletionType) kind = "deletion";
+			else continue;
+			const revisionId = mark.attrs["revisionId"];
+			const key = `${currentBlockId ?? ""}:${kind}:${revisionId}`;
+			const existing = grouped.get(key);
+			if (existing) {
+				existing.text += text;
+				continue;
+			}
+			const author = mark.attrs["author"];
+			const date = mark.attrs["date"];
+			grouped.set(key, {
+				id: revisionId,
+				type: kind,
+				author: typeof author === "string" ? author : "",
+				date: typeof date === "string" ? date : null,
+				text,
+				blockId: currentBlockId
+			});
+		}
+	});
+	return [...grouped.values()];
+};
+/**
+* The comment anchors present in the body, read from the `comment` mark the
+* editor renders. Each entry carries the anchored text and containing block id;
+* runs of one comment id within the body fold into a single anchor.
+*/
+const getCommentAnchorsFromDoc = (doc) => {
+	const commentType = doc.type.schema.marks["comment"];
+	if (!commentType) return [];
+	const blockStarts = blockStartIdsFromDoc(doc);
+	const anchors = /* @__PURE__ */ new Map();
+	let currentBlockId = null;
+	doc.descendants((node, pos) => {
+		if (node.isTextblock) {
+			currentBlockId = blockStarts.get(pos) ?? null;
+			return true;
+		}
+		if (!node.isInline || node.text === void 0) return;
+		const text = node.text;
+		for (const mark of node.marks) {
+			if (mark.type !== commentType || typeof mark.attrs["commentId"] !== "number") continue;
+			const commentId = mark.attrs["commentId"];
+			const existing = anchors.get(commentId);
+			if (!existing) {
+				anchors.set(commentId, {
+					commentId,
+					blockId: currentBlockId,
+					quote: text
+				});
+				continue;
+			}
+			existing.quote += text;
+			existing.blockId ??= currentBlockId;
+		}
+	});
+	return [...anchors.values()];
+};
+//#endregion
+export { getCommentAnchorsFromDoc, getTrackedChangesFromDoc };