@stll/folio-core 0.37.1 → 0.37.3

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 };

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

@@ -1,3 +1,4 @@
+import { FolioAIEditSnapshot } from "./types.js";
 import { FolioNodeRevisionKind } from "../prosemirror/revisionCarriers.js";
 import { Node } from "prosemirror-model";
 //#region src/ai-edits/read.d.ts
@@ -56,6 +57,8 @@ type FolioCommentAnchor = {
   /** The document text the comment is anchored to. */
   quote: string;
 };
+/** Read revisions from the exact immutable document that produced a snapshot. */
+declare const getTrackedChangesFromSnapshot: (snapshot: FolioAIEditSnapshot) => FolioReviewChange[];
 /**
  * The tracked changes present in the body, read from inline marks and
  * structural node attributes. Runs of one inline revision within a block fold
@@ -66,6 +69,11 @@ type FolioCommentAnchor = {
  * fold into the row's entry rather than reporting a second time.
  */
 declare const getTrackedChangesFromDoc: (doc: Node) => FolioReviewChange[];
+/** @internal Read revision statistics without paying for an unrelated block projection. */
+declare const getTrackedChangeStatsFromDoc: (doc: Node) => {
+  highestId: number;
+  present: boolean;
+};
 /**
  * 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;
@@ -73,4 +81,4 @@ declare const getTrackedChangesFromDoc: (doc: Node) => FolioReviewChange[];
  */
 declare const getCommentAnchorsFromDoc: (doc: Node) => FolioCommentAnchor[];
 //#endregion
-export { FOLIO_REVIEW_CHANGE_KINDS, FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };
+export { FOLIO_REVIEW_CHANGE_KINDS, FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangeStatsFromDoc, getTrackedChangesFromDoc, getTrackedChangesFromSnapshot };

package/dist/ai-edits/read.js

@@ -2,7 +2,7 @@ import { expectRunPropertyChangeMarkAttrs } from "../prosemirror/attrs/index.js"
 import { getFolioNodeRevisionCarriers } from "../prosemirror/revisionCarriers.js";
 import { expandRunFormattingCarrier, runFormattingCarrierReviewText, runFormattingInlineAtomDisposition } from "../prosemirror/runFormattingInlineCarriers.js";
 import { getTableCellMergeChange } from "../prosemirror/tableCellMergeRevision.js";
-import { createFolioAIEditSnapshot } from "./snapshot.js";
+import { createFolioAIEditSnapshot, sourceDocumentOf } from "./snapshot.js";
 //#region src/ai-edits/read.ts
 /**
 * Runtime census of every tracked-change discriminator the reviewer exposes.
@@ -31,11 +31,16 @@ const FOLIO_REVIEW_CHANGE_KINDS = Object.freeze({
 });
 /** Map each snapshot block's start position to its stable id. */
 const blockStartIdsFromDoc = (doc) => {
+	return blockStartIdsFromSnapshot(createFolioAIEditSnapshot(doc));
+};
+/** Map an existing snapshot's block starts without projecting its document again. */
+const blockStartIdsFromSnapshot = (snapshot) => {
 	const starts = /* @__PURE__ */ new Map();
-	for (const anchor of Object.values(createFolioAIEditSnapshot(doc).anchors)) starts.set(anchor.from, anchor.id);
+	for (const anchor of Object.values(snapshot.anchors)) starts.set(anchor.from, anchor.id);
 	return starts;
 };
 const firstBlockIdWithin = ({ node, nodePos, blockStarts }) => {
+	if (!blockStarts) return null;
 	let blockId = null;
 	node.descendants((child, relativePos) => {
 		if (blockId !== null || !child.isTextblock) return blockId === null;
@@ -51,19 +56,10 @@ const firstBlockIdWithin = ({ node, nodePos, blockStarts }) => {
 * matches neither and keeps its own entry.
 */
 const belongsToRowRevision = (scope, revision) => revision.id === scope.change.id || revision.author === scope.change.author && revision.date === scope.change.date;
-/**
-* The tracked changes present in the body, read from inline marks and
-* structural node attributes. Runs of one inline revision within a block fold
-* into a single entry.
-*
-* A tracked row insertion or deletion marks the row AND every run in its
-* cells, the way Word writes it. Both halves are one change, so the run marks
-* fold into the row's entry rather than reporting a second time.
-*/
-const getTrackedChangesFromDoc = (doc) => {
+/** Shared revision interpreter; a null block map omits unrelated block-id projection. */
+const getTrackedChangesFromProjectedDoc = (doc, blockStarts) => {
 	const insertionType = doc.type.schema.marks["insertion"];
 	const deletionType = doc.type.schema.marks["deletion"];
-	const blockStarts = blockStartIdsFromDoc(doc);
 	const grouped = /* @__PURE__ */ new Map();
 	const structuralChangeCellPositions = /* @__PURE__ */ new Map();
 	const rowRevisionScopes = [];
@@ -73,7 +69,7 @@ const getTrackedChangesFromDoc = (doc) => {
 		while (pos >= (rowRevisionScopes.at(-1)?.end ?? Number.POSITIVE_INFINITY)) rowRevisionScopes.pop();
 		const nodeRevisionCarriers = getFolioNodeRevisionCarriers(node, pos);
 		if (nodeRevisionCarriers.length > 0) {
-			const blockId = node.isTextblock ? blockStarts.get(pos) ?? null : firstBlockIdWithin({
+			const blockId = node.isTextblock ? blockStarts?.get(pos) ?? null : firstBlockIdWithin({
 				node,
 				nodePos: pos,
 				blockStarts
@@ -171,7 +167,7 @@ const getTrackedChangesFromDoc = (doc) => {
 			}
 		}
 		if (node.isTextblock) {
-			currentBlockId = blockStarts.get(pos) ?? null;
+			currentBlockId = blockStarts?.get(pos) ?? null;
 			return true;
 		}
 		if (!node.isInline) return;
@@ -244,6 +240,28 @@ const getTrackedChangesFromDoc = (doc) => {
 	});
 	return [...grouped.values()];
 };
+/** Read revisions from the exact immutable document that produced a snapshot. */
+const getTrackedChangesFromSnapshot = (snapshot) => getTrackedChangesFromProjectedDoc(sourceDocumentOf(snapshot), blockStartIdsFromSnapshot(snapshot));
+/**
+* The tracked changes present in the body, read from inline marks and
+* structural node attributes. Runs of one inline revision within a block fold
+* into a single entry.
+*
+* A tracked row insertion or deletion marks the row AND every run in its
+* cells, the way Word writes it. Both halves are one change, so the run marks
+* fold into the row's entry rather than reporting a second time.
+*/
+const getTrackedChangesFromDoc = (doc) => getTrackedChangesFromProjectedDoc(doc, blockStartIdsFromDoc(doc));
+/** @internal Read revision statistics without paying for an unrelated block projection. */
+const getTrackedChangeStatsFromDoc = (doc) => {
+	let highestId = 0;
+	const changes = getTrackedChangesFromProjectedDoc(doc, null);
+	for (const change of changes) highestId = Math.max(highestId, change.id);
+	return {
+		highestId,
+		present: changes.length > 0
+	};
+};
 /**
 * 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;
@@ -281,4 +299,4 @@ const getCommentAnchorsFromDoc = (doc) => {
 	return [...anchors.values()];
 };
 //#endregion
-export { FOLIO_REVIEW_CHANGE_KINDS, getCommentAnchorsFromDoc, getTrackedChangesFromDoc };
+export { FOLIO_REVIEW_CHANGE_KINDS, getCommentAnchorsFromDoc, getTrackedChangeStatsFromDoc, getTrackedChangesFromDoc, getTrackedChangesFromSnapshot };

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

@@ -5,6 +5,10 @@ import { Node } from "prosemirror-model";
 //#region src/ai-edits/snapshot.d.ts
 /** @internal Numbering references collected during the snapshot's document walk. */
 declare const numberingReferenceKeysOf: (snapshot: FolioAIEditSnapshot) => readonly string[];
+/** @internal Tables collected during the snapshot's document walk. */
+declare const storyTablesOf: (snapshot: FolioAIEditSnapshot) => readonly FolioStoryTable[];
+/** @internal The immutable ProseMirror document that produced this snapshot. */
+declare const sourceDocumentOf: (snapshot: FolioAIEditSnapshot) => Node;
 declare const normalizeFolioAIBlockText: (text: string) => string;
 /**
  * Whether a block carries text a reader would see.
@@ -70,14 +74,12 @@ type FolioStoryTable = {
  * Every table of one story in document order, nested tables included and
  * hidden rows' subtrees excluded.
  *
- * The single place a story's tables are numbered. `table.tableIndex` on a
- * block, the geometry a comparison copies out of the target and the geometry
- * it checks its own work against all read this list, so no second walk can
- * number the same document differently.
+ * Uses the same traversal classification as the snapshot's integrated census,
+ * so both surfaces skip and number the same nodes in the same order.
  */
 declare const folioStoryTables: (doc: Node) => FolioStoryTable[];
 declare const createFolioAIEditSnapshot: (doc: Node) => FolioAIEditSnapshot;
 /** @internal Use for an EditorState that owns the document's style resolver. */
 declare const createFolioAIEditSnapshotWithStyleResolver: (doc: Node, styleResolver: RunStyleResolver | null) => FolioAIEditSnapshot;
 //#endregion
-export { FolioStoryTable, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, trailingBodyBlockId };
+export { FolioStoryTable, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, sourceDocumentOf, storyTablesOf, trailingBodyBlockId };

package/dist/ai-edits/snapshot.js

@@ -9,9 +9,14 @@ import { buildCleanBlockText } from "./clean-text.js";
 import { panic } from "better-result";
 import { TableMap } from "prosemirror-tables";
 //#region src/ai-edits/snapshot.ts
-const numberingReferenceKeysBySnapshot = /* @__PURE__ */ new WeakMap();
+const metadataBySnapshot = /* @__PURE__ */ new WeakMap();
+const metadataOf = (snapshot) => metadataBySnapshot.get(snapshot) ?? panic("Metadata was requested for a snapshot that did not record it");
 /** @internal Numbering references collected during the snapshot's document walk. */
-const numberingReferenceKeysOf = (snapshot) => numberingReferenceKeysBySnapshot.get(snapshot) ?? panic("A numbering census was requested for a snapshot that did not record one");
+const numberingReferenceKeysOf = (snapshot) => metadataOf(snapshot).numberingReferenceKeys;
+/** @internal Tables collected during the snapshot's document walk. */
+const storyTablesOf = (snapshot) => metadataOf(snapshot).storyTables;
+/** @internal The immutable ProseMirror document that produced this snapshot. */
+const sourceDocumentOf = (snapshot) => metadataOf(snapshot).sourceDocument;
 const normalizeFolioAIBlockText = (text) => text.replace(/\s+/gu, " ").trim();
 /**
 * Whether a block carries text a reader would see.
@@ -96,21 +101,28 @@ const TABLE_ROLE_ROW = "row";
 * whole subtree, so a table nested inside a hidden row is hidden with it.
 */
 const isHiddenTableRow = (node) => node.type.name === TABLE_ROW_NODE_NAME && node.attrs["hidden"] === true;
+const STORY_TABLE_CONTAINER = "container";
+const STORY_TABLE_HIDDEN_SUBTREE = "hidden-subtree";
+const STORY_TABLE = "table";
+/** Shared visibility and table-role rule for both story projection walks. */
+const classifyNonTextblockStoryTableNode = (node) => {
+	if (isHiddenTableRow(node)) return STORY_TABLE_HIDDEN_SUBTREE;
+	return node.type.spec["tableRole"] === TABLE_ROLE_TABLE ? STORY_TABLE : STORY_TABLE_CONTAINER;
+};
 /**
 * Every table of one story in document order, nested tables included and
 * hidden rows' subtrees excluded.
 *
-* The single place a story's tables are numbered. `table.tableIndex` on a
-* block, the geometry a comparison copies out of the target and the geometry
-* it checks its own work against all read this list, so no second walk can
-* number the same document differently.
+* Uses the same traversal classification as the snapshot's integrated census,
+* so both surfaces skip and number the same nodes in the same order.
 */
 const folioStoryTables = (doc) => {
 	const tables = [];
 	doc.descendants((node, pos) => {
 		if (node.isTextblock) return false;
-		if (isHiddenTableRow(node)) return false;
-		if (node.type.spec["tableRole"] === TABLE_ROLE_TABLE) tables.push({
+		const disposition = classifyNonTextblockStoryTableNode(node);
+		if (disposition === STORY_TABLE_HIDDEN_SUBTREE) return false;
+		if (disposition === STORY_TABLE) tables.push({
 			index: tables.length,
 			start: pos,
 			node
@@ -154,14 +166,25 @@ const createFolioAIEditSnapshotInternal = (doc, styleResolver) => {
 	const hashCounts = /* @__PURE__ */ new Map();
 	const usedBlockIds = /* @__PURE__ */ new Set();
 	const numberingReferenceKeys = /* @__PURE__ */ new Set();
-	const tableIndexByStart = new Map(folioStoryTables(doc).map(({ start, index }) => [start, index]));
+	const tables = [];
+	const tableIndexByStart = /* @__PURE__ */ new Map();
 	const path = [];
 	let blockIndex = 0;
 	let blankIndex = 0;
 	doc.descendants((node, pos, _parent, index) => {
 		while (pos >= (path.at(-1)?.end ?? Number.POSITIVE_INFINITY)) path.pop();
 		if (!node.isTextblock) {
-			if (isHiddenTableRow(node)) return false;
+			const disposition = classifyNonTextblockStoryTableNode(node);
+			if (disposition === STORY_TABLE_HIDDEN_SUBTREE) return false;
+			if (disposition === STORY_TABLE) {
+				const tableIndex = tables.length;
+				tables.push({
+					index: tableIndex,
+					start: pos,
+					node
+				});
+				tableIndexByStart.set(pos, tableIndex);
+			}
 			if (!node.isLeaf) path.push({
 				node,
 				start: pos,
@@ -254,7 +277,11 @@ const createFolioAIEditSnapshotInternal = (doc, styleResolver) => {
 		blocks,
 		anchors
 	};
-	numberingReferenceKeysBySnapshot.set(snapshot, [...numberingReferenceKeys]);
+	metadataBySnapshot.set(snapshot, {
+		numberingReferenceKeys: [...numberingReferenceKeys],
+		sourceDocument: doc,
+		storyTables: tables
+	});
 	return snapshot;
 };
 const createFolioAIEditSnapshot = (doc) => createFolioAIEditSnapshotInternal(doc, null);
@@ -479,4 +506,4 @@ const isEmptyPreviewRunStyle = ({ bold, italic, underline, strike, fontFamily, f
 const sameDirectFormatting = (left, right) => left === void 0 && isEmptyPreviewRunStyle(right) || left !== void 0 && left.bold === right.bold && left.italic === right.italic && left.underline === right.underline && left.strike === right.strike && left.fontFamily === right.fontFamily && left.fontSizePt === right.fontSizePt && left.color === right.color;
 const isUnstyledPreviewRun = ({ bold, italic, underline, strike, fontFamily, fontSizePt, color }) => bold === void 0 && italic === void 0 && underline === void 0 && strike === void 0 && fontFamily === void 0 && fontSizePt === void 0 && color === void 0;
 //#endregion
-export { createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, trailingBodyBlockId };
+export { createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, sourceDocumentOf, storyTablesOf, trailingBodyBlockId };