@stll/folio-core 0.52.0 → 0.54.0

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

@@ -1,5 +1,7 @@
 import { expectPageBreakRunAttrs } from "../prosemirror/attrs/index.js";
 import { runFormattingInlineAtomCleanText, runFormattingInlineControlCharacter } from "../prosemirror/runFormattingInlineCarriers.js";
+import { createNoteReferenceNumbering, noteReferenceMarker } from "../utils/noteReferenceLabels.js";
+import { noteReferenceOf } from "./note-references.js";
 //#region src/ai-edits/clean-text.ts
 const EMPTY_CLEAN_TEXT_STRUCTURAL_BOUNDARIES = Object.freeze([]);
 const cutsIntoSpan = ({ offset, length }, boundaryOffset) => boundaryOffset > offset && boundaryOffset < offset + length;
@@ -24,7 +26,7 @@ const resolveCleanTextRange = ({ cleanBlock, startOffset, endOffset }) => {
 	let from = baseFrom;
 	let to = baseTo;
 	for (const boundary of structuralBoundaries) {
-		if (boundary.type === "field") {
+		if (boundary.type === "field" || boundary.type === "noteReference") {
 			if (cutsIntoSpan(boundary, startOffset) || cutsIntoSpan(boundary, endOffset)) return null;
 			continue;
 		}
@@ -47,12 +49,48 @@ const COMMENT_MARK = "comment";
 const HIDDEN_MARK = "hidden";
 const isOmittedFromCleanView = (node) => node.marks.some((mark) => mark.type.name === DELETION_MARK || mark.type.name === HIDDEN_MARK);
 const DEFAULT_BUILD_CLEAN_BLOCK_TEXT_OPTIONS = { fieldResults: "text" };
-const buildCleanBlockText = (blockNode, blockFrom, { fieldResults } = DEFAULT_BUILD_CLEAN_BLOCK_TEXT_OPTIONS) => {
+/**
+* The marker a reference reads as: the story's number when the labels know
+* the note, else the next number of a block-local sequence.
+*/
+const noteReferenceLabelFor = (node, labels, local) => {
+	const reference = noteReferenceOf(node);
+	if (reference === null) return null;
+	const known = labels?.labelOf(reference);
+	if (known !== void 0) return known;
+	const { displayNumber } = local().next(reference.noteType, reference.noteId);
+	return noteReferenceMarker(reference.noteType, displayNumber);
+};
+const buildCleanBlockText = (blockNode, blockFrom, { fieldResults, noteReferences } = DEFAULT_BUILD_CLEAN_BLOCK_TEXT_OPTIONS) => {
 	let text = "";
 	const offsets = [];
 	let structuralBoundaries;
 	let lastEnd = blockFrom + 1;
+	const labels = noteReferences === "sourceText" ? void 0 : noteReferences;
+	let localNumbering;
+	const local = () => localNumbering ??= createNoteReferenceNumbering();
 	blockNode.descendants((node, pos) => {
+		if (noteReferences !== "sourceText" && node.isText && !isOmittedFromCleanView(node)) {
+			const reference = noteReferenceOf(node);
+			const label = reference === null ? null : noteReferenceLabelFor(node, labels, local);
+			if (reference !== null && label !== null) {
+				const from = blockFrom + 1 + pos;
+				const to = from + node.nodeSize;
+				(structuralBoundaries ??= []).push({
+					type: "noteReference",
+					offset: text.length,
+					length: label.length,
+					from,
+					to,
+					noteType: reference.noteType,
+					noteId: reference.noteId
+				});
+				for (let index = 0; index < label.length; index++) offsets.push(from);
+				text += label;
+				lastEnd = to;
+				return false;
+			}
+		}
 		if (node.type.name === "pageBreakRun") {
 			const from = blockFrom + 1 + pos;
 			const { clear } = expectPageBreakRunAttrs(node);
@@ -114,12 +152,20 @@ const buildCleanBlockText = (blockNode, blockFrom, { fieldResults } = DEFAULT_BU
 *
 * 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.
+* post-tracked-changes view. A footnote or endnote reference reads as its
+* marker (`[^1]`), numbered within the block.
+*/
+const buildAnnotatedBlockText = (blockNode) => buildAnnotatedBlockTextWithNoteReferences(blockNode, void 0);
+/**
+* {@link buildAnnotatedBlockText} with a story's reference numbering, so a
+* reference reads as the marker every other reader of the story shows.
 */
-const buildAnnotatedBlockText = (blockNode) => {
+const buildAnnotatedBlockTextWithNoteReferences = (blockNode, noteReferences) => {
 	const segments = [];
+	let localNumbering;
+	const local = () => localNumbering ??= createNoteReferenceNumbering();
 	blockNode.descendants((node) => {
-		const text = node.isText ? node.text : runFormattingInlineAtomCleanText(node);
+		const text = node.isText ? noteReferenceLabelFor(node, noteReferences, local) ?? node.text : runFormattingInlineAtomCleanText(node);
 		if (text === void 0 || text === null) return true;
 		const annotation = annotationOf(node.marks);
 		const previous = segments.at(-1);
@@ -165,4 +211,4 @@ const renderAnnotatedSegment = ({ annotation, text }) => {
 	return inner;
 };
 //#endregion
-export { buildAnnotatedBlockText, buildCleanBlockText, resolveCleanTextRange };
+export { buildAnnotatedBlockText, buildAnnotatedBlockTextWithNoteReferences, buildCleanBlockText, resolveCleanTextRange };

package/dist/ai-edits/comment-lifecycle.d.ts

@@ -0,0 +1,18 @@
+import { document_d_exports } from "../types/document.js";
+import { Node } from "prosemirror-model";
+//#region src/ai-edits/comment-lifecycle.d.ts
+/** Ids of the comments an editor document anchors: by mark, reference or point anchor. */
+declare const anchoredCommentIdsInProseDoc: (doc: Node) => Set<number>;
+/** Ids of the comments a model story's blocks hold any marker of. */
+declare const anchoredCommentIdsInBlocks: (blocks: readonly document_d_exports.BlockContent[]) => Set<number>;
+/**
+ * `comments` without the threads whose root lost its anchor: the root, and
+ * every reply that threads under it. A reply's own markers repeat its root's
+ * range, so a reply is judged by its root, never on its own.
+ */
+declare const withoutLostCommentThreads: (comments: readonly document_d_exports.Comment[], { anchoredBefore, anchoredNow }: {
+  anchoredBefore: ReadonlySet<number>;
+  anchoredNow: ReadonlySet<number>;
+}) => document_d_exports.Comment[];
+//#endregion
+export { anchoredCommentIdsInBlocks, anchoredCommentIdsInProseDoc, withoutLostCommentThreads };

package/dist/ai-edits/comment-lifecycle.js

@@ -0,0 +1,52 @@
+import { visitCommentMarkers } from "../docx/commentAnchorIndex.js";
+import { readCommentReferenceAttrs } from "../prosemirror/commentReferenceAttrs.js";
+import "../prosemirror/extensions/nodes/CommentReferenceExtension.js";
+import "../prosemirror/extensions/nodes/RangeAnchorExtension.js";
+import { readRangeAnchorAttrs } from "../prosemirror/rangeAnchorAttrs.js";
+//#region src/ai-edits/comment-lifecycle.ts
+/** Ids of the comments an editor document anchors: by mark, reference or point anchor. */
+const anchoredCommentIdsInProseDoc = (doc) => {
+	const ids = /* @__PURE__ */ new Set();
+	doc.descendants((node) => {
+		if (node.type.name === "commentReference") {
+			const attrs = readCommentReferenceAttrs(node);
+			if (attrs.ok) ids.add(attrs.value.commentId);
+		} else if (node.type.name === "rangeAnchor") {
+			const attrs = readRangeAnchorAttrs(node);
+			if (attrs.ok && attrs.value.start.type === "commentRangeStart") ids.add(attrs.value.start.id);
+		}
+		for (const mark of node.marks) {
+			const commentId = mark.attrs["commentId"];
+			if (mark.type.name === "comment" && typeof commentId === "number") ids.add(commentId);
+		}
+		return true;
+	});
+	return ids;
+};
+/** Ids of the comments a model story's blocks hold any marker of. */
+const anchoredCommentIdsInBlocks = (blocks) => {
+	const ids = /* @__PURE__ */ new Set();
+	visitCommentMarkers(blocks, ({ item }) => ids.add(item.id));
+	return ids;
+};
+/**
+* `comments` without the threads whose root lost its anchor: the root, and
+* every reply that threads under it. A reply's own markers repeat its root's
+* range, so a reply is judged by its root, never on its own.
+*/
+const withoutLostCommentThreads = (comments, { anchoredBefore, anchoredNow }) => {
+	const dropped = /* @__PURE__ */ new Set();
+	for (const comment of comments) if (comment.parentId === void 0 && anchoredBefore.has(comment.id) && !anchoredNow.has(comment.id)) dropped.add(comment.id);
+	if (dropped.size === 0) return [...comments];
+	let grew = true;
+	while (grew) {
+		grew = false;
+		for (const comment of comments) if (!dropped.has(comment.id) && comment.parentId !== void 0 && dropped.has(comment.parentId)) {
+			dropped.add(comment.id);
+			grew = true;
+		}
+	}
+	return comments.filter((comment) => !dropped.has(comment.id));
+};
+//#endregion
+export { anchoredCommentIdsInBlocks, anchoredCommentIdsInProseDoc, withoutLostCommentThreads };

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

@@ -1,11 +1,12 @@
 import { document_d_exports } from "../types/document.js";
 import { FolioTableTemplates } from "./table-template.js";
 import { FolioAIBlock, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
-import { FolioReplacementBackground, FolioRevisionStamp, FolioWordDiffOptions } from "./apply.js";
+import { FolioReplacementBackground, FolioRevisionStamp, FolioUndefinedStylePolicy, FolioWordDiffOptions } from "./apply.js";
 import { ImportReferencedStyleDefinitionsResult } from "../compare/style-resources.js";
 import { InlineProvenanceTargetOptions } from "../compare/inline-provenance.js";
 import { MatchInlineAtomsOptions } from "../compare/inline-atoms.js";
 import { FolioDocumentOperationBatch, FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult } from "../document-operations.js";
+import { FolioPendingSuggestionLoadResult, FolioPendingSuggestionRecord } from "./pending-suggestions.js";
 import { FolioReviewChange, FolioReviewChangeKind } from "./read.js";
 import { FolioStoryTable } from "./snapshot.js";
 import { TableGeometryPairing } from "./table-geometry.js";
@@ -159,6 +160,13 @@ type FolioApplyDocumentOperationsToStoryOptions = FolioApplyDocumentOperationsOp
    * the target document — keeps them instead.
    */
   replacementBackground?: FolioReplacementBackground;
+  /**
+   * What an operation naming a paragraph style the document does not define
+   * does. Refusing it is the default; a caller copying another document's
+   * style references — `compareDocx` and `generateRedlineDocx` reproducing the
+   * revised document — keeps them instead.
+   */
+  undefinedStyles?: FolioUndefinedStylePolicy;
 };
 type FolioHeaderFooterStoryHandle = Extract<FolioEditableDocumentStoryHandle, {
   type: "header" | "footer";
@@ -200,6 +208,7 @@ type StoryInlineAtomsResult = {
   documentChanged: boolean;
 } | {
   status: "unalignable";
+  detail?: string;
 } | {
   status: "budget-exceeded";
 };
@@ -288,8 +297,17 @@ type FolioReviewComment = {
   text: string;
   /** The document text the comment is anchored to, or `""` when unanchored. */
   anchoredText: string;
-  /** Stable id of the anchored body block, or `null` when the anchor is absent. */
+  /**
+   * Stable id of the anchored block, or `null` when the anchor is absent. The
+   * id is the one {@link FolioDocxReviewer.snapshotStory} gives the block in
+   * {@link FolioReviewComment.story}.
+   */
   blockId: string | null;
+  /**
+   * The story holding the anchor — the body, a header or footer, a footnote or
+   * an endnote — or `null` when the anchor is absent.
+   */
+  story: FolioDocumentStoryHandle | null;
   replies: FolioReviewCommentReply[];
   /** Whether the comment is marked resolved / done. */
   done: boolean;
@@ -323,6 +341,8 @@ declare class FolioDocxReviewer {
   private state;
   private readonly secondaryStoryStates;
   private readonly removedHeaderFooterStories;
+  /** Notes whose reference a resolution removed: a note exists only through its reference. */
+  private readonly removedNoteStories;
   private readonly sectionReferenceRemovals;
   private importedStyles;
   private readonly importedMedia;
@@ -331,7 +351,10 @@ declare class FolioDocxReviewer {
   private readonly resolvedStoryExpectations;
   private readonly createdComments;
   private readonly usedCommentIds;
+  /** Comments the body anchored when it was loaded, read as the editor projects it. */
+  private readonly loadedMainCommentIds;
   private readonly documentOperationUndoEntries;
+  private readonly pendingSuggestions;
   /**
    * Resolved-state overrides recorded by {@link resolveComment}, keyed by
    * comment id. Applied on read ({@link getComments}) and on write
@@ -359,6 +382,10 @@ declare class FolioDocxReviewer {
    * the anchor map the apply layer resolves operations against.
    */
   snapshot(): FolioAIEditSnapshot;
+  /** Export staged AI operations for storage by the host, outside the DOCX. */
+  exportPendingSuggestions(): FolioPendingSuggestionRecord[];
+  /** Validate saved proposals against this document before restaging them. */
+  loadPendingSuggestions(records: readonly unknown[]): FolioPendingSuggestionLoadResult[];
   /**
    * The package's numbering, flattened to what a reader sees: one entry per
    * numbering instance and level, with the format and level text that produce
@@ -419,8 +446,10 @@ declare class FolioDocxReviewer {
    */
   applyDocumentOperations(batch: FolioDocumentOperationBatch, options?: FolioApplyDocumentOperationsOptions): FolioDocumentOperationResult;
   /** Apply a versioned operation batch to one editable document story. */
-  applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff, tableTemplates, replacementBackground }: FolioApplyDocumentOperationsToStoryOptions): FolioDocumentOperationResult;
+  applyDocumentOperationsToStory({ story, batch, snapshot, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }: FolioApplyDocumentOperationsToStoryOptions): FolioDocumentOperationResult;
+  /** Apply a batch; the notes whose references it deletes or removes follow them. */
   private applyDocumentOperationsInternal;
+  private applyDocumentOperationsToStoryState;
   /** Undo the latest unchanged document-operation batch and its created comments. */
   undoDocumentOperations(undoHandle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
   /**
@@ -446,6 +475,10 @@ declare class FolioDocxReviewer {
    * one per non-empty part: `[header default] …`, `[footer default] …`,
    * `[footnote #N] …`, `[endnote #N] …`. Lines reflect in-memory edits. Empty
    * parts and separator notes are omitted.
+   *
+   * A header or footer is labelled with the role its section references give
+   * it (`default`, `first`, `even`); in a document with several sections, also
+   * with the sections that show it: `[header first (sections 1, 3)] …`.
    */
   getNotesAsText(): string;
   private listStoryHandlesInternal;
@@ -472,10 +505,12 @@ declare class FolioDocxReviewer {
    * {@link getComments} or its id; the reply threads under that comment's root
    * (Word threads are flat). On {@link toBuffer} the reply is written as a real
    * Word reply — linked via `commentsExtended.xml` and given its own
-   * `commentRange` markers + reference anchored on the parent's range. Returns
+   * `commentRange` markers + reference anchored on the parent's range. The
+   * live document carries the same anchor. Returns
    * the created reply, or `null` when the target comment is absent.
    */
   replyTo(target: FolioReviewComment | number, input: FolioReviewReplyInput): FolioReviewCommentReply | null;
+  private anchorReplyInEditor;
   /**
    * Mark a comment thread resolved, or reopen a previously resolved one. Pass
    * the id from {@link getComments} / {@link FolioReviewComment.id}. Applies
@@ -491,6 +526,13 @@ declare class FolioDocxReviewer {
   resolveComment(commentId: string, options?: {
     resolved?: boolean;
   }): boolean;
+  /**
+   * Where each header and footer part is shown, as the live section
+   * references state it: its role (`w:type`) and the 1-based section, in
+   * section order. A part's own `hdrFtrType` holds one role, and one part can
+   * serve several sections, in different roles.
+   */
+  private headerFooterPlacements;
   private currentFinalSectionProperties;
   private stageFinalSectionProperties;
   private stageMappedSectionBoundaries;
@@ -510,9 +552,16 @@ declare class FolioDocxReviewer {
    */
   rejectChange(target: FolioReviewChange | number): boolean;
   private rejectChangeInternal;
+  /** Convert one pending suggestion into an ordinary tracked change. */
+  acceptSuggestion(suggestionId: string, options?: {
+    author?: string;
+  }): boolean;
+  /** Remove one pending suggestion without applying it. */
+  rejectSuggestion(suggestionId: string): boolean;
   /**
-   * Accept every tracked change in the package. Returns the number of changes
-   * present before the sweep.
+   * Accept every ordinary tracked change in the package. Pending suggestions
+   * remain staged until {@link acceptSuggestion} is called. Returns the number
+   * of ordinary changes present before the sweep.
    *
    * Every story, not just the body: a revision in a header or a footnote is
    * one a reviewer meant to resolve, and leaving it behind means an accepted
@@ -524,6 +573,23 @@ declare class FolioDocxReviewer {
   private resolveWithSectionReferenceHistory;
   private resolveEveryFinalSectionChange;
   private resolveEveryStory;
+  /**
+   * Change the body the way a note follows its reference: a note whose
+   * reference goes, goes too, as a note no text refers to does; a note whose
+   * reference an edit deletes as a tracked change has its text deleted with
+   * it; a note whose reference's deletion is rejected gets back the text that
+   * deletion took.
+   */
+  private withNotesFollowingReferences;
+  /** Delete the text of each note whose reference went from live to a tracked deletion. */
+  private deleteNotesWithTheirReferences;
+  /**
+   * The notes a story other than the body refers to (a header, a footer, a
+   * comment, another note), leaving out references inside the `skipped` notes.
+   */
+  private noteKeysReferencedOutsideBody;
+  private resolveEveryStoryOnce;
+  private acceptOrdinaryChangesWithSuggestions;
   /** The current document model with edits merged back in. */
   toDocument(): document_d_exports.Document;
   private captureReviewerState;
@@ -551,6 +617,14 @@ declare class FolioDocxReviewer {
    */
   private trySelectiveSave;
   private getEditableStoryState;
+  /**
+   * A secondary story as its editable state holds it: the loaded state's
+   * document once an operation has loaded it, otherwise the conversion loading
+   * performs — with the same deterministic block ids — without retaining a
+   * state for a story nothing edits.
+   */
+  private readSecondaryStoryDoc;
+  private secondaryStoryDoc;
   private requireEditableStoryState;
   private setEditableStoryState;
   private getHeaderFooterStory;
@@ -575,7 +649,17 @@ declare class FolioDocxReviewer {
   private mergeEditedSecondaryStories;
   /** Apply any {@link resolveComment} overrides recorded for these comments. */
   private withResolvedOverrides;
-  /** Map each anchored comment id to its anchored text and containing block id. */
+  /**
+   * `comments` without the threads an edit left anchored nowhere: anchored in
+   * a story when it was loaded (or created anchored by this reviewer), and
+   * anchored in no story now. See `comment-lifecycle.ts`.
+   */
+  private keptCommentThreads;
+  /**
+   * Map each anchored comment id to its anchored text, its containing block id
+   * and the story holding it. A comment can be anchored in any story, so every
+   * story is read, not only the body.
+   */
   private commentAnchors;
   /** Allocate outside every parsed or newly-created comment and reply id. */
   private nextCommentId;