@stll/folio-core 0.55.0 → 0.57.0

package/dist/docx/saveDiagnostics.d.ts

@@ -1,8 +1,19 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
 //#region src/docx/saveDiagnostics.d.ts
 /** Save diagnostics describe fidelity fallbacks without including document content. */
 type SaveDiagnostic = {
   type: "sourceReplayMismatch";
   part: string;
+} | {
+  type: "selectiveSaveRefused";
+  part: string;
+} | {
+  type: "sourceReplayUnavailable";
+  part: string;
+} | {
+  type: "canonicalResourceReplacement";
+  gap: typeof CANONICAL_GAP.resourceReplacement;
+  part: string;
 };
 type SaveDiagnosticOptions = {
   onDiagnostic?: ((diagnostic: SaveDiagnostic) => void) | undefined;

package/dist/docx/selectiveSave.d.ts

@@ -1,7 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 import { SaveDiagnosticOptions } from "./saveDiagnostics.js";
+import { DocumentBodyAuthorityOptions } from "./serializer/documentSerializer.js";
 //#region src/docx/selectiveSave.d.ts
-type SelectiveSaveOptions = SaveDiagnosticOptions & {
+type SelectiveSaveOptions = SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
   /** Changed paragraph IDs to selectively patch */
   changedParaIds: Set<string>;
   /** Whether paragraph membership, order, or block structure changed. */

package/dist/docx/selectiveSave.js

@@ -7,16 +7,17 @@ import { parseNumbering } from "./numberingParser.js";
 import { normalizeImportedNumericIds } from "./numericIdNormalization.js";
 import { isUnsafePackagePath } from "./packageParts.js";
 import { RELATIONSHIP_TYPES } from "./relsParser.js";
-import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
+import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedHyperlinkBindings, hasUnmaterializedInlineResources, planAddedStyles, publishCanonicalImageResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
 import "./selectiveSaveFlags.js";
 import { buildPatchedDocumentXml, buildPatchedNoteXml, collectAddedNumberingDefs, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
-import { planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
+import { hasOwnedCommentsPart, planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
 import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { buildStructuralDocumentPatch } from "./structuralXmlPatch.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+import { writeZipPart } from "@stll/docx-core/zip";
 //#region src/docx/selectiveSave.ts
 /**
 * Splice edited footnote/endnote paragraphs into their parts and return the
@@ -200,9 +201,11 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	if (!validateFolioDocumentModel(doc).valid) return null;
 	const comments = doc.package.document.comments ?? [];
 	const hasComments = comments.length > 0;
+	const ownsCommentsPart = hasOwnedCommentsPart(doc);
 	const commentPlan = planCommentParts(comments);
 	try {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
+		if (await hasUnmaterializedHyperlinkBindings(doc, zip)) return null;
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
 		if (originalBuffer !== doc.originalBuffer) {
 			const sourceParts = /* @__PURE__ */ new Map();
@@ -211,14 +214,27 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				if (file.dir || !lowerPath.startsWith("word/") || !lowerPath.endsWith(".xml")) continue;
 				sourceParts.set(path, await file.async("text"));
 			}
-			for (const [path, xml] of normalizeImportedNumericIds(sourceParts)) if (xml !== sourceParts.get(path)) zip.file(path, xml);
+			for (const [path, xml] of normalizeImportedNumericIds(sourceParts)) if (xml !== sourceParts.get(path)) writeZipPart({
+				zip,
+				path,
+				data: xml
+			});
 		}
+		if (options.bodyAuthority === "canonical") await publishCanonicalImageResources({
+			document: doc,
+			zip,
+			compressionLevel: 6
+		});
 		const updates = /* @__PURE__ */ new Map();
 		if (changedParaIds.size > 0 || structuralChange) {
 			const docXmlFile = zip.file("word/document.xml");
 			if (!docXmlFile) return null;
 			const originalDocXml = await docXmlFile.async("text");
-			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml));
+			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml), {
+				xml: originalDocXml,
+				bodyAuthority: options.bodyAuthority,
+				onDiagnostic: options.onDiagnostic
+			});
 			const bodyParaIds = collectParaIds(serializedDocXml);
 			const originalBodyParaIds = structuralChange ? collectParaIds(originalDocXml) : void 0;
 			if (structuralChange && doc.package.numbering) {
@@ -244,30 +260,45 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				updates.set("word/document.xml", patchedDocXml);
 			}
 		}
-		const sourceCommentsFile = zip.file("word/comments.xml");
-		if (hasComments || sourceCommentsFile) {
+		const sourceCommentsFile = findZipEntryCaseInsensitive(zip, "word/comments.xml");
+		const commentsPartPath = sourceCommentsFile?.name ?? "word/comments.xml";
+		if (hasComments || ownsCommentsPart || sourceCommentsFile) {
 			const sourceCommentsXml = sourceCommentsFile ? await sourceCommentsFile.async("text") : void 0;
 			const commentsXml = serializeComments(commentPlan, sourceCommentsXml === void 0 ? void 0 : readRootNamespaceBindings(sourceCommentsXml));
-			if (commentsXml !== sourceCommentsXml) updates.set("word/comments.xml", commentsXml);
+			if (commentsXml !== sourceCommentsXml) updates.set(commentsPartPath, commentsXml);
 		}
-		if (hasComments) {
+		if (hasComments || ownsCommentsPart) {
 			const ctFile = zip.file("[Content_Types].xml");
 			if (ctFile) {
 				const ctXml = await ctFile.async("text");
-				if (!ctXml.includes("/word/comments.xml")) updates.set("[Content_Types].xml", ctXml.replace("</Types>", `<Override PartName="/word/comments.xml" ContentType="${COMMENTS_CONTENT_TYPE}"/></Types>`));
+				if (!ctXml.toLowerCase().includes("/word/comments.xml")) updates.set("[Content_Types].xml", ctXml.replace("</Types>", `<Override PartName="/${commentsPartPath}" ContentType="${COMMENTS_CONTENT_TYPE}"/></Types>`));
 			}
 			const relsPath = "word/_rels/document.xml.rels";
 			const relsFile = zip.file(relsPath);
 			if (relsFile) {
 				const relsXml = await relsFile.async("text");
-				if (!relsXml.includes("comments.xml")) {
+				if (!relsXml.toLowerCase().includes("comments.xml")) {
 					const maxId = findMaxRId(relsXml);
-					updates.set(relsPath, relsXml.replace("</Relationships>", `<Relationship Id="rId${maxId + 1}" Type="${RELATIONSHIP_TYPES.comments}" Target="comments.xml"/></Relationships>`));
+					updates.set(relsPath, relsXml.replace("</Relationships>", `<Relationship Id="rId${maxId + 1}" Type="${RELATIONSHIP_TYPES.comments}" Target="${commentsPartPath.slice(5)}"/></Relationships>`));
 				}
 			}
 		}
 		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
 		if (!await patchNumberingPart(zip, doc, updates)) return null;
+		const styles = await planAddedStyles(doc, zip);
+		switch (styles.type) {
+			case "unchanged": break;
+			case "patch":
+				updates.set(styles.path, styles.xml);
+				break;
+			case "materialize":
+				options.onDiagnostic?.({
+					type: "selectiveSaveRefused",
+					part: "word/styles.xml"
+				});
+				return null;
+			default: return styles;
+		}
 		for (const [path, xml] of await collectHeaderFooterUpdates(doc, {
 			sourceZip: zip,
 			onDiagnostic: options.onDiagnostic

package/dist/docx/selectiveXmlPatch.js

@@ -35,7 +35,7 @@ function isXmlNameBoundary(char) {
 */
 function findParagraphOffsets(xml, paraId) {
 	const escaped = escapeRegExp(paraId);
-	const pattern = new RegExp(`<w:p[\\s][^>]*w14:paraId="${escaped}"`, "gu");
+	const pattern = new RegExp(`<w:p[\\s][^>]*w14:paraId\\s*=\\s*(["'])${escaped}\\1`, "gu");
 	const matches = [];
 	let match;
 	while ((match = pattern.exec(xml)) !== null) matches.push(match.index);
@@ -191,7 +191,7 @@ function scanParagraphs(xml) {
 		const tagEnd = xml.indexOf(">", tagStart);
 		if (tagEnd === -1) break;
 		const openTag = xml.slice(tagStart, tagEnd + 1);
-		const paraId = /\bw14:paraId="(?<id>[^"]+)"/u.exec(openTag)?.groups?.["id"];
+		const paraId = /\bw14:paraId\s*=\s*(?<quote>["'])(?<id>[^"']+)\k<quote>/u.exec(openTag)?.groups?.["id"];
 		const container = {
 			inFallback: depth.fallback > 0,
 			inAlternateContent: depth.alternateContent > 0,
@@ -236,7 +236,7 @@ function countParagraphElements(xml) {
 */
 function collectParaIds(xml) {
 	const ids = /* @__PURE__ */ new Map();
-	const pattern = /w14:paraId="(?<id>[^"]+)"/gu;
+	const pattern = /w14:paraId\s*=\s*(?<quote>["'])(?<id>[^"']+)\k<quote>/gu;
 	let match;
 	while ((match = pattern.exec(xml)) !== null) {
 		const id = match.groups["id"];
@@ -245,7 +245,7 @@ function collectParaIds(xml) {
 	return ids;
 }
 /** Paragraph ids folio writes and this module may have to remove again. */
-const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(?:para|text)Id="[^"]*"/gu;
+const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(paraId|textId)="[^"]*"/gu;
 /**
 * The replacement for a paragraph whose source open tag carries no paraId.
 *
@@ -262,7 +262,9 @@ const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(?:para|text)Id="[^"]*"/gu;
 const withoutMintedIds = (paragraphXml, sourceOpenTag) => {
 	const tagEnd = paragraphXml.indexOf(">");
 	if (tagEnd === -1) return paragraphXml;
-	return paragraphXml.slice(0, tagEnd + 1).replace(MINTED_PARA_ID_ATTRIBUTE, (attribute) => sourceOpenTag.includes(attribute.trim()) ? attribute : "") + paragraphXml.slice(tagEnd + 1);
+	return paragraphXml.slice(0, tagEnd + 1).replace(MINTED_PARA_ID_ATTRIBUTE, (attribute, name) => {
+		return new RegExp(`\\bw14:${name}\\s*=\\s*(["'])[^"']*\\1`, "u").test(sourceOpenTag) ? attribute : "";
+	}) + paragraphXml.slice(tagEnd + 1);
 };
 const storyOf = ({ textBoxDepth }) => textBoxDepth > 0 ? "text-box" : "main";
 const sameContainer = (a, b) => a.inAlternateContent === b.inAlternateContent && a.textBoxDepth === b.textBoxDepth && a.tableDepth === b.tableDepth;

package/dist/docx/serializer/commentSerializer.d.ts

@@ -1,5 +1,8 @@
+import { document_d_exports } from "../../types/document.js";
 import { Comment } from "../../types/content.js";
 //#region src/docx/serializer/commentSerializer.d.ts
+/** An owned empty part survives deletion of its final thread. */
+declare const hasOwnedCommentsPart: (document: document_d_exports.Document) => boolean;
 /**
  * What every comment part is written from: one ordered list of comment ids, and
  * the facts each id carries.
@@ -52,4 +55,4 @@ declare function serializeComments({ order, byId }: CommentPartPlan, sourceBindi
  */
 declare function serializeCommentsExtended(plan: CommentPartPlan): string | null;
 //#endregion
-export { CommentPartPlan, planCommentParts, serializeComments, serializeCommentsExtended };
+export { CommentPartPlan, hasOwnedCommentsPart, planCommentParts, serializeComments, serializeCommentsExtended };

package/dist/docx/serializer/commentSerializer.js

@@ -5,12 +5,15 @@ import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
 import { escapeXmlAttribute } from "@stll/docx-core";
+import { COMMENT_PART_RELATIONSHIPS } from "@stll/docx-core/model";
 //#region src/docx/serializer/commentSerializer.ts
 /**
 * Comment Serializer
 *
 * Serializes Comment[] to OOXML comments.xml format.
 */
+/** An owned empty part survives deletion of its final thread. */
+const hasOwnedCommentsPart = (document) => [...document.package.relationships?.values() ?? []].some(({ type }) => type === COMMENT_PART_RELATIONSHIPS.comments.type);
 const DEFAULT_ANNOTATION_REFERENCE_PROPERTIES = "<w:rPr><w:rStyle w:val=\"CommentReference\"/></w:rPr>";
 const PARAGRAPH_PROPERTIES_END = "</w:pPr>";
 const serializeAnnotationReference = (formatting) => {
@@ -169,7 +172,7 @@ function buildCommentExtendedEntries({ order, byId, threadParaIdById, threadedId
 		entries.push({
 			paraId,
 			...parentParaId !== void 0 ? { paraIdParent: parentParaId } : {},
-			done: done ?? false
+			...done === void 0 ? {} : { done }
 		});
 	}
 	return entries.length > 0 ? entries : null;
@@ -185,7 +188,8 @@ function serializeCommentsExtended(plan) {
 	if (!entries) return null;
 	const body = entries.map((entry) => {
 		const parentAttr = entry.paraIdParent !== void 0 ? ` w15:paraIdParent="${escapeXmlAttribute(entry.paraIdParent)}"` : "";
-		return `<w15:commentEx w15:paraId="${escapeXmlAttribute(entry.paraId)}"${parentAttr} w15:done="${entry.done ? "1" : "0"}"/>`;
+		const doneAttr = entry.done === void 0 ? "" : ` w15:done="${entry.done ? "1" : "0"}"`;
+		return `<w15:commentEx w15:paraId="${escapeXmlAttribute(entry.paraId)}"${parentAttr}${doneAttr}/>`;
 	}).join("");
 	return XML_DECLARATION + serializePartElement({
 		partPath: "word/commentsExtended.xml",
@@ -196,4 +200,4 @@ function serializeCommentsExtended(plan) {
 	});
 }
 //#endregion
-export { planCommentParts, serializeComments, serializeCommentsExtended };
+export { hasOwnedCommentsPart, planCommentParts, serializeComments, serializeCommentsExtended };

package/dist/docx/serializer/documentSerializer.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { SaveDiagnosticOptions } from "../saveDiagnostics.js";
 //#region src/docx/serializer/documentSerializer.d.ts
 /**
  * Serialize a DocumentBody to document.xml body content
@@ -15,7 +16,13 @@ declare function serializeDocumentBody(body: document_d_exports.DocumentBody): s
  *   prefix only the source document bound keeps its URI
  * @returns Complete XML string for document.xml
  */
-declare function serializeDocument(doc: document_d_exports.Document, sourceBindings?: ReadonlyMap<string, string>): string;
+type DocumentBodyAuthorityOptions = {
+  /** Canonical saves preserve trusted source blocks; default saves serialize the model. */
+  bodyAuthority?: "canonical" | "model" | undefined;
+};
+declare function serializeDocument(doc: document_d_exports.Document, sourceBindings?: ReadonlyMap<string, string>, source?: SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
+  xml?: string | undefined;
+}): string;
 /**
  * Serialize just the document body (useful for partial updates)
  *
@@ -59,4 +66,4 @@ declare function createSimpleDocument(paragraphs: {
   styleId?: string;
 }[]): document_d_exports.Document;
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { DocumentBodyAuthorityOptions, createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/documentSerializer.js

@@ -1,3 +1,5 @@
+import { getDocumentSourceBaseline } from "../headerFooterVerbatim.js";
+import { buildDocumentBlockReplay, canReplayDocumentSource } from "../storyBlockReplay.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
@@ -84,24 +86,41 @@ function serializeDocumentBody(body) {
 	if (body.finalSectionProperties) parts.push(serializeSectionProperties(body.finalSectionProperties));
 	return parts.join("");
 }
-/**
-* Serialize a complete Document to valid document.xml
-*
-* @param doc - The document to serialize
-* @param sourceBindings - Root `xmlns:*` of the part being replaced, so a
-*   prefix only the source document bound keeps its URI
-* @returns Complete XML string for document.xml
-*/
-function serializeDocument(doc, sourceBindings) {
+const replayableDocumentSources = /* @__PURE__ */ new WeakMap();
+function serializeDocument(doc, sourceBindings, source) {
 	resetAutoIdCounter();
+	const baseline = source?.bodyAuthority === "canonical" ? getDocumentSourceBaseline(doc) : { type: "missing" };
+	const sourceMatches = baseline.type === "captured" && (source?.xml === void 0 || source.xml === baseline.xml);
+	if (baseline.type === "captured" && sourceMatches && JSON.stringify(doc.package.document) === baseline.fingerprint) {
+		if (replayableDocumentSources.get(baseline.body) === baseline.xml) return baseline.xml;
+		if (canReplayDocumentSource(baseline.xml, baseline.body)) {
+			replayableDocumentSources.set(baseline.body, baseline.xml);
+			return baseline.xml;
+		}
+	}
 	const body = serializeDocumentBackground(doc.package.document.background) + `<w:body>${serializeDocumentBody(doc.package.document)}</w:body>`;
-	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>" + serializePartElement({
+	const serializedXml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>" + serializePartElement({
 		partPath: "word/document.xml",
 		rootName: "w:document",
 		baselinePrefixes: DOCUMENT_BASELINE_PREFIXES,
 		sourceBindings,
 		body
 	});
+	if (baseline.type === "missing") return serializedXml;
+	if (baseline.type === "captured" && sourceMatches) {
+		const replay = buildDocumentBlockReplay({
+			sourceXml: baseline.xml,
+			baseline: baseline.body,
+			current: doc.package.document,
+			serializedXml
+		});
+		if (replay !== null) return replay;
+	}
+	source?.onDiagnostic?.({
+		type: "sourceReplayMismatch",
+		part: "word/document.xml"
+	});
+	return serializedXml;
 }
 /**
 * Serialize just the document body (useful for partial updates)