@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

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

@@ -0,0 +1,23 @@
+//#region src/ai-edits/clean-text.ts
+const DELETION_MARK = "deletion";
+const buildCleanBlockText = (blockNode, blockFrom) => {
+	let text = "";
+	const offsets = [];
+	let lastEnd = blockFrom + 1;
+	blockNode.descendants((node, pos) => {
+		if (!node.isText || node.text === void 0) return true;
+		if (node.marks.some((mark) => mark.type.name === DELETION_MARK)) return false;
+		const startPos = blockFrom + 1 + pos;
+		for (let i = 0; i < node.text.length; i++) offsets.push(startPos + i);
+		text += node.text;
+		lastEnd = startPos + node.text.length;
+		return true;
+	});
+	offsets.push(lastEnd);
+	return {
+		text,
+		offsets
+	};
+};
+//#endregion
+export { buildCleanBlockText };

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

@@ -0,0 +1,225 @@
+import { FolioAIBlock, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
+import { document_d_exports } from "../types/document.js";
+
+//#region src/ai-edits/headless.d.ts
+/** Options for {@link FolioDocxReviewer.fromBuffer}. */
+type FolioDocxReviewerOptions = {
+  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string;
+};
+/** Options for {@link FolioDocxReviewer.applyOperations}. */
+type FolioApplyOperationsOptions = {
+  /** `"tracked-changes"` (default) produces ins/del redlines; `"direct"` edits in place. */mode?: FolioAIEditApplyMode;
+  /**
+   * The snapshot the `operations`' block ids were built against. Omit to
+   * snapshot the reviewer's current state — correct for the common flow of
+   * `snapshot()` -> build ops -> `applyOperations()` on the same reviewer.
+   */
+  snapshot?: FolioAIEditSnapshot;
+};
+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. 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.
+   */
+  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;
+};
+/** Filter for {@link FolioDocxReviewer.getChanges}. */
+type FolioReviewChangeFilter = {
+  author?: string;
+  type?: FolioReviewChangeKind;
+};
+type FolioReviewCommentReply = {
+  id: number;
+  author: string;
+  date: string | null;
+  text: string;
+};
+/** Input for {@link FolioDocxReviewer.replyTo}. */
+type FolioReviewReplyInput = {
+  /** Reply body text. */text: string; /** Reply author; defaults to the reviewer's author. */
+  author?: string;
+  initials?: string;
+};
+/** A comment thread discovered in the document. */
+type FolioReviewComment = {
+  id: number;
+  author: string;
+  date: string | null; /** The comment body text, its paragraphs joined by newlines. */
+  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. */
+  blockId: string | null;
+  replies: FolioReviewCommentReply[]; /** Whether the comment is marked resolved / done. */
+  done: boolean;
+};
+/** Filter for {@link FolioDocxReviewer.getComments}. */
+type FolioReviewCommentFilter = {
+  author?: string;
+  done?: boolean;
+};
+/**
+ * Headless `.docx` reviewer. Parse a buffer, read blocks, apply
+ * `FolioAIEditOperation`s against the document model, and write the reviewed
+ * `.docx` back out — no editor instance, no DOM.
+ *
+ * @example
+ * ```ts
+ * const reviewer = await FolioDocxReviewer.fromBuffer(buffer, { author: "AI" });
+ * const { blocks } = reviewer.snapshot();
+ * reviewer.applyOperations([
+ *   { id: "1", type: "replaceInBlock", blockId: blocks[0].id, find: "$50k", replace: "$500k" },
+ * ]);
+ * const reviewed = await reviewer.toBuffer();
+ * ```
+ */
+declare class FolioDocxReviewer {
+  /** Default author for tracked changes and comments. */
+  readonly author: string;
+  private readonly baseDocument;
+  private readonly originalBuffer;
+  private state;
+  private readonly createdComments;
+  private constructor();
+  /** Parse a `.docx` buffer into a reviewer. */
+  static fromBuffer(buffer: ArrayBuffer, options?: FolioDocxReviewerOptions): Promise<FolioDocxReviewer>;
+  /**
+   * Snapshot the current document into AI-facing blocks (id, kind, text) plus
+   * the anchor map the apply layer resolves operations against.
+   */
+  snapshot(): FolioAIEditSnapshot;
+  /**
+   * Apply operations against the current state. Reuses the live-editor applier
+   * verbatim via a headless `{ state, dispatch }` seam; the resulting state
+   * (including any comments) is retained for {@link toBuffer}.
+   */
+  applyOperations(operations: FolioAIEditOperation[], options?: FolioApplyOperationsOptions): FolioAIEditApplyResult;
+  /**
+   * The body blocks with their stable ids, in document order — the same
+   * `FolioAIBlock` shape {@link snapshot} builds, reused verbatim so the ids
+   * feed straight back into {@link applyOperations} and accept / reject.
+   */
+  getContent(): FolioAIBlock[];
+  /**
+   * 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.
+   */
+  getContentAsText(): string;
+  /**
+   * The tracked changes (insertions and deletions) present in the body, read
+   * from the same `insertion` / `deletion` marks the editor renders. Each
+   * carries the revision id {@link acceptChange} / {@link rejectChange} resolve
+   * against. Runs of one revision within a block fold into a single entry.
+   */
+  getChanges(filter?: FolioReviewChangeFilter): FolioReviewChange[];
+  /**
+   * The comment threads in the document — comments parsed from the package plus
+   * any the reviewer authored — with their anchored text and containing block
+   * id. Only run text is read from a comment body; richer comment content
+   * (nested tracked changes, hyperlinks) is out of scope.
+   */
+  getComments(filter?: FolioReviewCommentFilter): FolioReviewComment[];
+  /**
+   * Add a reply to a comment thread. Pass a {@link FolioReviewComment} from
+   * {@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
+   * the created reply, or `null` when the target comment is absent.
+   */
+  replyTo(target: FolioReviewComment | number, input: FolioReviewReplyInput): FolioReviewCommentReply | null;
+  /**
+   * 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
+   * resolved state persists on {@link toBuffer}. Returns `false` when the
+   * revision is no longer present (already resolved, or never existed).
+   */
+  acceptChange(target: FolioReviewChange | number): boolean;
+  /**
+   * Reject an existing tracked change: an insertion's text is removed, a
+   * deletion's text is restored. See {@link acceptChange} for targeting.
+   */
+  rejectChange(target: FolioReviewChange | number): boolean;
+  /**
+   * Accept every tracked change in the body. Returns the number of changes
+   * present before the sweep. Runs unconditionally: the underlying command also
+   * resolves paragraph-level changes (`w:pPrChange`, paragraph-boundary
+   * ins/del) that {@link getChanges} does not enumerate. Note-body changes are
+   * out of scope.
+   */
+  acceptAll(): number;
+  /** Reject every tracked change in the body. See {@link acceptAll}. */
+  rejectAll(): number;
+  /** The current document model with edits merged back in. */
+  toDocument(): document_d_exports.Document;
+  /**
+   * Serialise the reviewed document to a new `.docx` buffer. Tries a selective
+   * patch first (only changed paragraphs are rewritten; every other byte of the
+   * original package is preserved), falling back to a full repack for
+   * structural edits — the same two-tier path the editor's save uses.
+   */
+  toBuffer(): Promise<ArrayBuffer>;
+  /**
+   * Attempt the selective patch, treating a throw the same as a decline. Odd
+   * source XML can make the paragraph diff throw rather than return `null`; a
+   * full repack is the correct lossless fallback in both cases, so the fallback
+   * is the graceful handling — no separate error surface is needed here.
+   */
+  private trySelectiveSave;
+  /**
+   * Count every tracked change an accept-all / reject-all sweep resolves: the
+   * inline insertion / deletion groups {@link getChanges} enumerates, plus
+   * paragraph-level changes (`pPrMark`, `_propertyChanges`) that live on
+   * paragraph attrs rather than inline marks.
+   */
+  private countTrackedChanges;
+  /** Map each snapshot block's start position to its stable id. */
+  private blockStartIds;
+  /** Map each anchored comment id to its anchored text and containing block id. */
+  private commentAnchors;
+  /**
+   * Drive a ProseMirror command against the reviewer's headless state via the
+   * same `{ state, dispatch }` seam {@link applyOperations} uses, retaining the
+   * resulting state for {@link toBuffer}.
+   */
+  private runCommand;
+}
+/** Options for {@link applyFolioAIEditsToBuffer}. */
+type ApplyFolioAIEditsToBufferOptions = {
+  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string; /** `"tracked-changes"` (default) produces ins/del redlines; `"direct"` edits in place. */
+  mode?: FolioAIEditApplyMode;
+  /**
+   * The snapshot the `operations`' block ids were built against. Omit to
+   * snapshot the freshly parsed buffer. Pass it when the ids were derived in a
+   * separate process (e.g. server-side `@stll/folio-core/server` block ids) so
+   * anchor resolution matches exactly.
+   */
+  snapshot?: FolioAIEditSnapshot;
+};
+/** Result of {@link applyFolioAIEditsToBuffer}. */
+type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
+  /** The reviewed `.docx` as a new buffer. */buffer: ArrayBuffer;
+};
+/**
+ * One-shot headless review: parse `buffer`, apply `operations`, and return the
+ * reviewed `.docx` buffer alongside the applied / skipped breakdown. Convenience
+ * wrapper over {@link FolioDocxReviewer} for callers that already hold the
+ * operations to run.
+ */
+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 };