@stll/folio-core 0.32.2 → 0.33.0

package/dist/ai-edits/__fixtures__/paragraphs.d.ts

@@ -0,0 +1,17 @@
+//#region src/ai-edits/__fixtures__/paragraphs.d.ts
+/**
+ * The smallest `.docx` that carries a list of paragraphs, generated rather
+ * than committed as bytes so a test's input is legible in its own diff.
+ */
+type ParagraphsDocxOptions = {
+  /**
+   * Wrap the paragraphs in a single table cell, followed by one body
+   * paragraph. The cell's last paragraph then has a sibling in the document
+   * and none in its own container, which is the case a paragraph-mark
+   * deletion must refuse.
+   */
+  inTableCell?: boolean;
+};
+declare const buildParagraphsDocx: (paragraphs: readonly string[], { inTableCell }?: ParagraphsDocxOptions) => Promise<ArrayBuffer>;
+//#endregion
+export { ParagraphsDocxOptions, buildParagraphsDocx };

package/dist/ai-edits/__fixtures__/paragraphs.js

@@ -0,0 +1,33 @@
+import JSZip from "jszip";
+//#region src/ai-edits/__fixtures__/paragraphs.ts
+/**
+* The smallest `.docx` that carries a list of paragraphs, generated rather
+* than committed as bytes so a test's input is legible in its own diff.
+*/
+const NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const RELATIONSHIPS = "http://schemas.openxmlformats.org/package/2006/relationships";
+const OFFICE_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const WORDPROCESSING = "application/vnd.openxmlformats-officedocument.wordprocessingml";
+/** Pinned, with no folder entries, so two builds produce identical bytes. */
+const ZIP_ENTRY_OPTIONS = {
+	date: new Date(Date.UTC(2e3, 0, 1)),
+	createFolders: false
+};
+const escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const paragraphXml = (text) => `<w:p><w:r><w:t xml:space="preserve">${escapeXml(text)}</w:t></w:r></w:p>`;
+const buildParagraphsDocx = async (paragraphs, { inTableCell } = {}) => {
+	const paragraphsXml = paragraphs.map(paragraphXml).join("");
+	const body = inTableCell ? `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr><w:tblGrid><w:gridCol w:w="9360"/></w:tblGrid><w:tr><w:tc><w:tcPr><w:tcW w:w="9360" w:type="dxa"/></w:tcPr>${paragraphsXml}</w:tc></w:tr></w:tbl>` + paragraphXml("After the table.") : paragraphsXml;
+	const parts = {
+		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${WORDPROCESSING}.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="${WORDPROCESSING}.styles+xml"/></Types>`,
+		"_rels/.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/officeDocument" Target="word/document.xml"/></Relationships>`,
+		"word/_rels/document.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/styles" Target="styles.xml"/></Relationships>`,
+		"word/styles.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="${NAMESPACE}"><w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style></w:styles>`,
+		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}"><w:body>${body}<w:sectPr><w:pgSz w:w="12240" w:h="15840"/></w:sectPr></w:body></w:document>`
+	};
+	const zip = new JSZip();
+	for (const name of Object.keys(parts).toSorted()) zip.file(name, parts[name] ?? "", ZIP_ENTRY_OPTIONS);
+	return await zip.generateAsync({ type: "arraybuffer" });
+};
+//#endregion
+export { buildParagraphsDocx };

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

@@ -1,4 +1,5 @@
 import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./types.js";
+import { WordDiffGranularity } from "./word-diff.js";
 import { EditorState, Transaction } from "prosemirror-state";
 //#region src/ai-edits/apply.d.ts
 /**
@@ -14,6 +15,20 @@ type FolioAIEditView = {
   state: EditorState;
   dispatch: (transaction: Transaction) => void;
 };
+/**
+ * Fixed revision provenance, for callers whose output must be reproducible.
+ * Both halves of the stamp travel together because either one left to the
+ * ambient clock (`new Date()` for the date, a `Date.now()`-seeded cursor for
+ * the ids) makes the produced package differ between two runs over the same
+ * inputs. `idSeed` starts a contiguous range the batch allocates from, so it
+ * must sit above every revision id the target document already carries.
+ */
+type FolioRevisionStamp = {
+  /** ISO-8601 date stamped on every `w:ins` / `w:del` this batch produces. */
+  date: string;
+  /** First revision id the batch may allocate. */
+  idSeed: number;
+};
 type ApplyFolioAIEditOperationsOptions = {
   view: FolioAIEditView;
   snapshot: FolioAIEditSnapshot;
@@ -23,8 +38,39 @@ type ApplyFolioAIEditOperationsOptions = {
   /** Optional author initials (w:initials) stamped alongside the author. */
   initials?: string;
   createCommentId?: (text: string) => number;
+  /** Omit to stamp revisions from the wall clock and the shared id cursor. */
+  revisionStamp?: FolioRevisionStamp;
+  /** How a replacement's redline is cut. */
+  wordDiff?: FolioWordDiffOptions;
+};
+/**
+ * How an apply batch cuts the redline for a replacement. Word-level by
+ * default; character granularity marks the changed letters inside a token,
+ * which reads well for a reference or a date. Normalization is deliberately
+ * absent: a batch that leaves a difference unmarked does not accept back to
+ * the text the caller asked for.
+ */
+type FolioWordDiffOptions = {
+  granularity?: WordDiffGranularity;
+};
+/**
+ * An apply result plus where the batch left the revision-id counter.
+ *
+ * A caller writing several batches into one package — a comparison walking
+ * the main story, then each header, footer and note — has to give every batch
+ * a seed above the last id the previous one used, or two stories claim the
+ * same `w:id` and a consumer resolving one revision resolves the other with
+ * it. The batch is the only thing that knows how many ids it took, so it says
+ * so rather than making the caller guess a stride.
+ */
+type FolioAIEditApplyOutcome = FolioAIEditApplyResult & {
+  /**
+   * First revision id a following batch may allocate: one past the last id
+   * this batch used, or the seed it started from when it allocated none.
+   */
+  nextRevisionId: number;
 };
-declare const applyFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyResult;
-declare const previewFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyResult;
+declare const applyFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyOutcome;
+declare const previewFolioAIEditOperations: (options: ApplyFolioAIEditOperationsOptions) => FolioAIEditApplyOutcome;
 //#endregion
-export { FolioAIEditView, applyFolioAIEditOperations, previewFolioAIEditOperations };
+export { FolioAIEditApplyOutcome, FolioAIEditView, FolioRevisionStamp, FolioWordDiffOptions, applyFolioAIEditOperations, previewFolioAIEditOperations };