@stll/folio-core 0.8.0 → 0.10.0

package/dist/ai-edits/headless.js

@@ -2,18 +2,19 @@ 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 { getHeaderFooterText } from "../docx/headerFooterParser.js";
+import { parseDocx } from "../docx/parser.js";
 import { deterministicHexId } from "../utils/hexId.js";
 import { repackDocx } from "../docx/rezip.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";
+import { proseDocToBlocks, updateDocumentContent } from "../prosemirror/conversion/fromProseDoc.js";
 import { getChangedParagraphIds, hasStructuralChanges, hasUntrackedChanges, ignoreTrackedChanges } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
 import { schema, singletonManager } from "../prosemirror/schema/index.js";
-import { toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
+import { footnoteToProseDoc, headerFooterToProseDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
+import { TaggedError } from "better-result";
 import { EditorState } from "prosemirror-state";
 //#region src/ai-edits/headless.ts
 /**
@@ -33,8 +34,7 @@ import { EditorState } from "prosemirror-state";
 * paragraphs in `document.xml` (leaving every untouched part byte-exact), with
 * a full repack as the fallback for structural edits.
 *
-* Scope: BODY blocks. Footnote / endnote note-body apply is intentionally out
-* of scope here and can build on the note serialization work separately.
+* Scope: main, header, footer, footnote, and endnote blocks.
 */
 /**
 * Standalone comment-id allocator for the reviewer. The React editor uses
@@ -114,6 +114,43 @@ const ensureDeterministicParaIdsInState = (state) => {
 	tr.setMeta("addToHistory", false);
 	return state.apply(tr);
 };
+const FOLIO_REVIEWED_VIEWS = Object.freeze([
+	"original",
+	"current-markup",
+	"final"
+]);
+const FOLIO_RESOLVED_REVIEWED_VIEWS = Object.freeze(["original", "final"]);
+var UnsupportedFolioReviewedViewError = class extends TaggedError("UnsupportedFolioReviewedViewError")() {};
+var FolioDocumentStoryNotFoundError = class extends TaggedError("FolioDocumentStoryNotFoundError")() {};
+const MAIN_STORY = Object.freeze({ type: "main" });
+const headerFooterStoryKey = ({ type, relationshipId }) => `${type}:${relationshipId}`;
+const noteStoryKey = ({ type, noteId }) => `${type}:${noteId}`;
+const secondaryStoryKey = (story) => story.type === "header" || story.type === "footer" ? headerFooterStoryKey(story) : noteStoryKey(story);
+const isFolioReviewedView = (value) => FOLIO_REVIEWED_VIEWS.some((view) => view === value);
+const isFolioResolvedReviewedView = (value) => FOLIO_RESOLVED_REVIEWED_VIEWS.some((view) => view === value);
+const applyCommandToState = (state, command) => {
+	let nextState = state;
+	command(state, (transaction) => {
+		nextState = nextState.apply(transaction);
+	});
+	return nextState;
+};
+const resolveReviewedState = (state, view) => {
+	if (view === "current-markup") return state;
+	return applyCommandToState(state, view === "original" ? rejectAllChanges() : acceptAllChanges());
+};
+const formatStoryStateForLLM = (state, annotated) => {
+	const snapshot = createFolioAIEditSnapshot(state.doc);
+	if (!annotated) return snapshot.blocks.map(formatBlockForLLM).join("\n");
+	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 : state.doc.nodeAt(from);
+		const text = node ? buildAnnotatedBlockText(node) : block.text;
+		return formatBlockLine(block, text);
+	}).join("\n");
+};
 /**
 * One LLM-ready line for a block: `[<blockId>] text`, with an `(h<level>)` tag
 * for headings and the list marker for list items, so a model can copy the
@@ -162,6 +199,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	baseDocument;
 	originalBuffer;
 	state;
+	secondaryStoryStates = /* @__PURE__ */ new Map();
 	createdComments = [];
 	documentOperationUndoEntries = [];
 	/**
@@ -206,6 +244,51 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	snapshot() {
 		return createFolioAIEditSnapshot(this.state.doc);
 	}
+	/** Return parsed package metadata without exposing the mutable document model. */
+	getDocumentProperties() {
+		const properties = this.baseDocument.package.properties;
+		if (!properties) return null;
+		return Object.freeze({
+			...properties,
+			...properties.created !== void 0 ? { created: new Date(properties.created.getTime()) } : {},
+			...properties.modified !== void 0 ? { modified: new Date(properties.modified.getTime()) } : {}
+		});
+	}
+	/** Snapshot one editable story into stable, operation-ready blocks. */
+	snapshotStory(story) {
+		const state = this.getEditableStoryState(story);
+		return state ? createFolioAIEditSnapshot(state.doc) : null;
+	}
+	/** Read one story through an immutable reviewed-view projection. */
+	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 sourceState = this.getEditableStoryState(story);
+		if (!sourceState) return null;
+		const state = resolveReviewedState(sourceState, view);
+		return {
+			story,
+			view,
+			snapshot: createFolioAIEditSnapshot(state.doc),
+			text: formatStoryStateForLLM(state, view === "current-markup"),
+			changes: getTrackedChangesFromDoc(state.doc)
+		};
+	}
+	/** Resolve one editable story to its original or final state. */
+	resolveReviewedStory({ 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;
+		this.setEditableStoryState(story, resolveReviewedState(sourceState, view));
+		return true;
+	}
 	/**
 	* Apply operations against the current state. Reuses the live-editor applier
 	* verbatim via a headless `{ state, dispatch }` seam; the resulting state
@@ -213,10 +296,15 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	*/
 	applyOperations(operations, options = {}) {
 		const { applied, skipped } = this.applyDocumentOperationsInternal({
-			version: 1,
-			operations,
-			mode: options.mode ?? "tracked-changes"
-		}, { ...options.snapshot !== void 0 && { snapshot: options.snapshot } }, false);
+			story: MAIN_STORY,
+			batch: {
+				version: 1,
+				operations,
+				mode: options.mode ?? "tracked-changes"
+			},
+			...options.snapshot !== void 0 && { snapshot: options.snapshot },
+			createUndoEntry: false
+		});
 		return {
 			applied,
 			skipped
@@ -229,21 +317,36 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* edit semantics.
 	*/
 	applyDocumentOperations(batch, options = {}) {
-		return this.applyDocumentOperationsInternal(batch, options, true);
+		return this.applyDocumentOperationsInternal({
+			story: MAIN_STORY,
+			batch,
+			...options.snapshot !== void 0 && { snapshot: options.snapshot },
+			createUndoEntry: true
+		});
+	}
+	/** Apply a versioned operation batch to one editable document story. */
+	applyDocumentOperationsToStory({ story, batch, snapshot }) {
+		return this.applyDocumentOperationsInternal({
+			story,
+			batch,
+			...snapshot !== void 0 && { snapshot },
+			createUndoEntry: true
+		});
 	}
-	applyDocumentOperationsInternal(batch, options, createUndoEntry) {
-		const beforeState = this.state;
+	applyDocumentOperationsInternal({ story, batch, snapshot, createUndoEntry }) {
+		const beforeState = this.requireEditableStoryState(story);
 		const createdCommentsLengthBefore = this.createdComments.length;
 		const view = {
-			state: this.state,
+			state: beforeState,
 			dispatch: (transaction) => {
 				view.state = view.state.apply(transaction);
 			}
 		};
 		const result = applyFolioDocumentOperations({
 			view,
-			snapshot: options.snapshot ?? this.snapshot(),
+			snapshot: snapshot ?? createFolioAIEditSnapshot(beforeState.doc),
 			batch,
+			story: story.type === "main" ? "main" : story,
 			author: this.author,
 			createCommentId: (text) => {
 				const comment = createReviewerComment(text, this.author);
@@ -255,11 +358,12 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 				id: `headless-${String(undoHandleCursor++)}`
 			}) }
 		});
-		this.state = view.state;
+		this.setEditableStoryState(story, view.state);
 		if (result.undoHandle !== null) this.documentOperationUndoEntries.push({
 			undoHandle: result.undoHandle,
+			story,
 			beforeState,
-			afterState: this.state,
+			afterState: view.state,
 			createdCommentsLengthBefore,
 			createdCommentsLengthAfter: this.createdComments.length
 		});
@@ -284,12 +388,12 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			undoHandle,
 			reason: "unknownHandle"
 		};
-		if (this.state !== entry.afterState || this.createdComments.length !== entry.createdCommentsLengthAfter) return {
+		if (this.requireEditableStoryState(entry.story) !== entry.afterState || this.createdComments.length !== entry.createdCommentsLengthAfter) return {
 			status: "rejected",
 			undoHandle,
 			reason: "documentChanged"
 		};
-		this.state = entry.beforeState;
+		this.setEditableStoryState(entry.story, entry.beforeState);
 		this.createdComments.length = entry.createdCommentsLengthBefore;
 		this.documentOperationUndoEntries.pop();
 		return {
@@ -317,31 +421,25 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* (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);
-			const text = node ? buildAnnotatedBlockText(node) : block.text;
-			return formatBlockLine(block, text);
-		}).join("\n");
+		return formatStoryStateForLLM(this.state, options.annotated === true);
 	}
 	/**
 	* 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.
+	* `[footnote #N] …`, `[endnote #N] …`. Lines reflect in-memory edits. Empty
+	* parts and separator notes are omitted.
 	*/
 	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));
+			for (const [relationshipId, hf] of map) {
+				const handle = {
+					type: label,
+					relationshipId
+				};
+				const text = this.getHeaderFooterStoryText(handle, hf);
 				if (text.length > 0) lines.push(`[${label} ${hf.hdrFtrType}] ${text}`);
 			}
 		};
@@ -349,12 +447,20 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		pushHeaderFooter(pkg.footers, "footer");
 		for (const footnote of pkg.footnotes ?? []) {
 			if (isSeparatorFootnote(footnote)) continue;
-			const text = normalizeFolioAIBlockText(getFootnoteText(footnote));
+			const handle = {
+				type: "footnote",
+				noteId: footnote.id
+			};
+			const text = this.getNoteStoryText(handle, footnote);
 			if (text.length > 0) lines.push(`[footnote #${footnote.id}] ${text}`);
 		}
 		for (const endnote of pkg.endnotes ?? []) {
 			if (isSeparatorEndnote(endnote)) continue;
-			const text = normalizeFolioAIBlockText(getEndnoteText(endnote));
+			const handle = {
+				type: "endnote",
+				noteId: endnote.id
+			};
+			const text = this.getNoteStoryText(handle, endnote);
 			if (text.length > 0) lines.push(`[endnote #${endnote.id}] ${text}`);
 		}
 		return lines.join("\n");
@@ -366,34 +472,46 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			handle: { type: "main" },
 			text: this.getContentAsText()
 		}];
-		for (const [relationshipId, header] of pkg.headers ?? []) stories.push({
-			handle: {
+		for (const [relationshipId, header] of pkg.headers ?? []) {
+			const handle = {
 				type: "header",
 				relationshipId
-			},
-			text: normalizeFolioAIBlockText(getHeaderFooterText(header))
-		});
-		for (const [relationshipId, footer] of pkg.footers ?? []) stories.push({
-			handle: {
+			};
+			stories.push({
+				handle,
+				text: this.getHeaderFooterStoryText(handle, header)
+			});
+		}
+		for (const [relationshipId, footer] of pkg.footers ?? []) {
+			const handle = {
 				type: "footer",
 				relationshipId
-			},
-			text: normalizeFolioAIBlockText(getHeaderFooterText(footer))
-		});
-		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) stories.push({
-			handle: {
+			};
+			stories.push({
+				handle,
+				text: this.getHeaderFooterStoryText(handle, footer)
+			});
+		}
+		for (const footnote of pkg.footnotes ?? []) if (!isSeparatorFootnote(footnote)) {
+			const handle = {
 				type: "footnote",
 				noteId: footnote.id
-			},
-			text: normalizeFolioAIBlockText(getFootnoteText(footnote))
-		});
-		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) stories.push({
-			handle: {
+			};
+			stories.push({
+				handle,
+				text: this.getNoteStoryText(handle, footnote)
+			});
+		}
+		for (const endnote of pkg.endnotes ?? []) if (!isSeparatorEndnote(endnote)) {
+			const handle = {
 				type: "endnote",
 				noteId: endnote.id
-			},
-			text: normalizeFolioAIBlockText(getEndnoteText(endnote))
-		});
+			};
+			stories.push({
+				handle,
+				text: this.getNoteStoryText(handle, endnote)
+			});
+		}
 		return stories;
 	}
 	/** Read one discovered story; returns null when its handle is no longer present. */
@@ -537,6 +655,7 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	/** The current document model with edits merged back in. */
 	toDocument() {
 		const document = updateDocumentContent(this.baseDocument, this.state.doc);
+		this.mergeEditedSecondaryStories(document);
 		if (this.createdComments.length > 0 || this.resolvedOverrides.size > 0) document.package.document.comments = this.withResolvedOverrides([...document.package.document.comments ?? [], ...this.createdComments]);
 		return document;
 	}
@@ -562,16 +681,136 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* is the graceful handling — no separate error surface is needed here.
 	*/
 	async trySelectiveSave(document) {
+		const changedParaIds = new Set(getChangedParagraphIds(this.state));
+		let structuralChange = hasStructuralChanges(this.state);
+		let untrackedChanges = hasUntrackedChanges(this.state);
+		for (const entry of this.secondaryStoryStates.values()) {
+			if (entry.handle.type !== "footnote" && entry.handle.type !== "endnote") continue;
+			for (const paraId of getChangedParagraphIds(entry.state)) changedParaIds.add(paraId);
+			structuralChange ||= hasStructuralChanges(entry.state);
+			untrackedChanges ||= hasUntrackedChanges(entry.state);
+		}
 		try {
 			return await attemptSelectiveSave(document, this.originalBuffer, {
-				changedParaIds: getChangedParagraphIds(this.state),
-				structuralChange: hasStructuralChanges(this.state),
-				hasUntrackedChanges: hasUntrackedChanges(this.state)
+				changedParaIds,
+				structuralChange,
+				hasUntrackedChanges: untrackedChanges
 			});
 		} catch {
 			return null;
 		}
 	}
+	getEditableStoryState(story) {
+		if (story.type === "main") return this.state;
+		const key = secondaryStoryKey(story);
+		const existing = this.secondaryStoryStates.get(key);
+		if (existing) return existing.state;
+		const source = story.type === "header" || story.type === "footer" ? this.getHeaderFooterStory(story) : this.getNoteStory(story);
+		if (!source) return null;
+		const conversionOptions = {
+			...this.baseDocument.package.styles !== void 0 && { styles: this.baseDocument.package.styles },
+			...this.baseDocument.package.theme !== void 0 && { theme: this.baseDocument.package.theme }
+		};
+		const state = ensureDeterministicParaIdsInState(EditorState.create({
+			schema,
+			doc: story.type === "header" || story.type === "footer" ? headerFooterToProseDoc(source.content, conversionOptions) : footnoteToProseDoc(source.content, conversionOptions),
+			plugins: singletonManager.getPlugins()
+		}));
+		this.secondaryStoryStates.set(key, {
+			handle: story,
+			initialState: state,
+			state
+		});
+		return state;
+	}
+	requireEditableStoryState(story) {
+		const state = this.getEditableStoryState(story);
+		if (state) return state;
+		throw new FolioDocumentStoryNotFoundError({
+			message: `Document story ${JSON.stringify(story)} was not found.`,
+			story
+		});
+	}
+	setEditableStoryState(story, state) {
+		if (story.type === "main") {
+			this.state = state;
+			return;
+		}
+		const entry = this.secondaryStoryStates.get(secondaryStoryKey(story));
+		if (!entry) throw new FolioDocumentStoryNotFoundError({
+			message: `Document story ${JSON.stringify(story)} was not found.`,
+			story
+		});
+		entry.state = state;
+	}
+	getHeaderFooterStory(story) {
+		return (story.type === "header" ? this.baseDocument.package.headers : this.baseDocument.package.footers)?.get(story.relationshipId);
+	}
+	getNoteStory(story) {
+		if (story.type === "footnote") return this.baseDocument.package.footnotes?.find((note) => note.id === story.noteId && !isSeparatorFootnote(note));
+		return this.baseDocument.package.endnotes?.find((note) => note.id === story.noteId && !isSeparatorEndnote(note));
+	}
+	getHeaderFooterStoryText(story, source) {
+		const state = this.secondaryStoryStates.get(headerFooterStoryKey(story))?.state;
+		return normalizeFolioAIBlockText(state?.doc.textContent ?? getHeaderFooterText(source));
+	}
+	getNoteStoryText(story, source) {
+		const state = this.secondaryStoryStates.get(noteStoryKey(story))?.state;
+		const sourceText = source.type === "footnote" ? getFootnoteText(source) : getEndnoteText(source);
+		return normalizeFolioAIBlockText(state?.doc.textContent ?? sourceText);
+	}
+	mergeEditedSecondaryStories(document) {
+		let headers;
+		let footers;
+		let footnotes;
+		let endnotes;
+		for (const entry of this.secondaryStoryStates.values()) {
+			if (entry.state === entry.initialState) continue;
+			if (entry.handle.type === "header" || entry.handle.type === "footer") {
+				const source = this.getHeaderFooterStory(entry.handle);
+				if (!source) continue;
+				const edited = {
+					...source,
+					content: proseDocToBlocks(entry.state.doc)
+				};
+				if (entry.handle.type === "header") {
+					headers ??= new Map(document.package.headers);
+					headers.set(entry.handle.relationshipId, edited);
+					continue;
+				}
+				footers ??= new Map(document.package.footers);
+				footers.set(entry.handle.relationshipId, edited);
+				continue;
+			}
+			if (entry.handle.type === "footnote") {
+				const { noteId } = entry.handle;
+				const source = this.baseDocument.package.footnotes?.find((note) => note.id === noteId && !isSeparatorFootnote(note));
+				if (!source) continue;
+				const edited = {
+					...source,
+					content: proseDocToBlocks(entry.state.doc)
+				};
+				footnotes ??= [...document.package.footnotes ?? []];
+				const index = footnotes.findIndex((note) => note.id === noteId);
+				if (index !== -1) footnotes[index] = edited;
+				continue;
+			}
+			const { noteId } = entry.handle;
+			const source = this.baseDocument.package.endnotes?.find((note) => note.id === noteId && !isSeparatorEndnote(note));
+			if (!source) continue;
+			const edited = {
+				...source,
+				content: proseDocToBlocks(entry.state.doc)
+			};
+			endnotes ??= [...document.package.endnotes ?? []];
+			const index = endnotes.findIndex((note) => note.id === noteId);
+			if (index !== -1) endnotes[index] = edited;
+		}
+		if (headers) document.package.headers = headers;
+		if (footers) document.package.footers = footers;
+		if (footnotes) document.package.footnotes = footnotes;
+		if (endnotes) document.package.endnotes = endnotes;
+	}
 	/**
 	* Count every tracked change an accept-all / reject-all sweep resolves: the
 	* inline insertion / deletion groups {@link getChanges} enumerates, plus the
@@ -654,4 +893,4 @@ const applyFolioAIEditsToBuffer = async (buffer, operations, options = {}) => {
 	};
 };
 //#endregion
-export { FolioDocxReviewer, applyFolioAIEditsToBuffer };
+export { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, FolioDocxReviewer, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView };

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

@@ -2,11 +2,11 @@ import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreview
 import { FolioAIEditView, applyFolioAIEditOperations } from "./apply.js";
 import { DocPositionRange, clampRangeToDocSize, resolveFolioAIBlockRange, resolveFolioAITextRange } from "./blockRange.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, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.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, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { FolioCommentAnchor, FolioReviewChange, FolioReviewChangeKind, getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
-import { FolioDocumentStory, FolioDocumentStoryHandle } from "./headless.js";
+import { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsToStoryOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioEditableDocumentStoryHandle, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, isFolioResolvedReviewedView, isFolioReviewedView } from "./headless.js";
 import { createFolioAIEditSnapshot, createFolioAITextRangeHandle, hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./scoped-reading.js";
 import { getFolioParaIdFromBlockId } from "../types/block-id.js";
 import { WordDiffSegment, diffWordSegments } from "./word-diff.js";
-export { type ApplyFolioDocumentOperationsOptions, type DocPositionRange, 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 FolioDocumentNavigationTarget, 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 FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, type FolioReviewChange, type FolioReviewChangeKind, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, type WordDiffSegment, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange };
+export { type ApplyFolioDocumentOperationsOptions, type DocPositionRange, 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, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, 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 FolioApplyDocumentOperationsToStoryOptions, type FolioCommentAnchor, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, type FolioEditableDocumentStoryHandle, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeKind, type FolioReviewedStory, type FolioReviewedView, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, type WordDiffSegment, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange };

package/dist/ai-edits/index.js

@@ -7,4 +7,5 @@ import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT
 import { clampRangeToDocSize, resolveFolioAIBlockRange, resolveFolioAITextRange } from "./blockRange.js";
 import { getCommentAnchorsFromDoc, getTrackedChangesFromDoc } from "./read.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./scoped-reading.js";
-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, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange };
+import { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, UnsupportedFolioReviewedViewError, isFolioResolvedReviewedView, isFolioReviewedView } from "./headless.js";
+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, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, applyFolioAIEditOperations, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, buildAnnotatedBlockText, clampRangeToDocSize, createFolioAIEditSnapshot, createFolioAITextRangeHandle, diffWordSegments, getCommentAnchorsFromDoc, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, getTrackedChangesFromDoc, hashFolioAIBlockText, isFolioDocumentOperationModeSupported, isFolioResolvedReviewedView, isFolioReviewedView, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, readFolioDocumentSection, resolveFolioAIBlockRange, resolveFolioAITextRange };

package/dist/ai-edits/snapshot.js

@@ -22,12 +22,28 @@ const createFolioAIEditSnapshot = (doc) => {
 	const draftBlocks = [];
 	const hashCounts = /* @__PURE__ */ new Map();
 	const usedBlockIds = /* @__PURE__ */ new Set();
+	const emptyAnchorState = {
+		candidate: null,
+		textblockCount: 0
+	};
 	let blockIndex = 0;
-	doc.descendants((node, pos) => {
+	doc.descendants((node, pos, parent) => {
 		if (!node.isTextblock) return;
 		const { text } = buildCleanBlockText(node, pos);
 		const normalizedText = normalizeFolioAIBlockText(text);
-		if (normalizedText.length === 0) return;
+		if (normalizedText.length === 0) {
+			if (parent?.type !== doc.type) return;
+			emptyAnchorState.textblockCount++;
+			if (emptyAnchorState.candidate === null) {
+				const paraIdAttr = node.attrs["paraId"];
+				emptyAnchorState.candidate = {
+					from: pos,
+					to: pos + node.nodeSize,
+					paraId: typeof paraIdAttr === "string" && paraIdAttr.length > 0 ? paraIdAttr : null
+				};
+			}
+			return;
+		}
 		const textHash = hashFolioAIBlockText(normalizedText);
 		hashCounts.set(textHash, (hashCounts.get(textHash) ?? 0) + 1);
 		blockIndex++;
@@ -72,10 +88,31 @@ const createFolioAIEditSnapshot = (doc) => {
 			hashOccurrenceCount: hashCounts.get(draft.anchor.textHash) ?? 0
 		};
 	}
-	return {
+	const emptyAnchorCandidate = emptyAnchorState.candidate;
+	if (blocks.length > 0 || emptyAnchorCandidate === null) return {
 		blocks,
 		anchors
 	};
+	const emptyDocumentAnchorId = deriveBlockId({
+		paraId: emptyAnchorCandidate.paraId,
+		index: 1,
+		taken: usedBlockIds
+	});
+	const normalizedText = "";
+	anchors[emptyDocumentAnchorId] = {
+		id: emptyDocumentAnchorId,
+		from: emptyAnchorCandidate.from,
+		to: emptyAnchorCandidate.to,
+		text: "",
+		normalizedText,
+		textHash: hashFolioAIBlockText(normalizedText),
+		hashOccurrenceCount: emptyAnchorState.textblockCount
+	};
+	return {
+		blocks,
+		anchors,
+		emptyDocumentAnchorId
+	};
 };
 const getBlockKind = (node, headingLevel) => {
 	const listMarker = node.attrs["listMarker"];

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

@@ -21,7 +21,8 @@ type FolioAIBlock = {
 };
 type FolioAIEditSnapshot = {
   blocks: FolioAIBlock[];
-  anchors: Record<string, FolioAIBlockAnchor>;
+  anchors: Record<string, FolioAIBlockAnchor>; /** Hidden empty paragraph used to anchor insertions when `blocks` is empty. */
+  emptyDocumentAnchorId?: string;
 };
 type FolioAIBlockAnchor = {
   id: string;