@stll/folio-core 0.33.0 → 0.33.1

package/dist/display-list/primitives.d.ts

@@ -15,7 +15,7 @@ import { hasComplexScript, isComplexScriptCodePoint } from "../utils/scriptSegme
  * advances rightward from its origin whatever the paragraph does.
  */
 declare const glyphCellOffsetsPx: (run: DisplayGlyphRun) => readonly number[];
-declare const DISPLAY_PRIMITIVE_KINDS: ("glyphRun" | "rect" | "line" | "image" | "clipGroup" | "rotateGroup" | "opacityGroup")[];
+declare const DISPLAY_PRIMITIVE_KINDS: ("line" | "rect" | "image" | "glyphRun" | "clipGroup" | "rotateGroup" | "opacityGroup")[];
 /**
  * Dash geometry of each stroke pattern, as multiples of the stroke thickness.
  *

package/dist/docx/hyperlinkParser.d.ts

@@ -16,6 +16,14 @@ import { XmlElement } from "./xmlParser.js";
  * @returns Parsed Hyperlink object
  */
 declare function parseHyperlink(node: XmlElement, rels: document_d_exports.RelationshipMap | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Hyperlink;
+/**
+ * One `w:hyperlink` child, or `null` for markup the model does not carry.
+ *
+ * Exposed so a caller that has to segment a hyperlink — one holding revision
+ * wrappers, which the model nests the other way round — parses its plain
+ * children exactly as {@link parseHyperlink} does.
+ */
+declare function parseHyperlinkChild(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, inScopeXmlns: Record<string, string>): document_d_exports.Hyperlink["children"][number] | null;
 /**
  * Get the display text of a hyperlink
  *
@@ -104,4 +112,4 @@ declare function createExternalHyperlink(url: string, children: document_d_expor
   target?: string;
 }): document_d_exports.Hyperlink;
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };

package/dist/docx/hyperlinkParser.js

@@ -71,22 +71,28 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
-	const children = getChildElements(node);
-	for (const child of children) switch (getLocalName(child.name)) {
-		case "r":
-			hyperlink.children.push(parseRun(child, styles, theme, rels, media, inScopeXmlns));
-			break;
-		case "bookmarkStart":
-			hyperlink.children.push(parseBookmarkStart(child));
-			break;
-		case "bookmarkEnd":
-			hyperlink.children.push(parseBookmarkEnd(child));
-			break;
-		default: break;
+	for (const child of getChildElements(node)) {
+		const parsed = parseHyperlinkChild(child, styles, theme, rels, media, inScopeXmlns);
+		if (parsed) hyperlink.children.push(parsed);
 	}
 	return hyperlink;
 }
 /**
+* One `w:hyperlink` child, or `null` for markup the model does not carry.
+*
+* Exposed so a caller that has to segment a hyperlink — one holding revision
+* wrappers, which the model nests the other way round — parses its plain
+* children exactly as {@link parseHyperlink} does.
+*/
+function parseHyperlinkChild(node, styles, theme, rels, media, inScopeXmlns) {
+	switch (getLocalName(node.name)) {
+		case "r": return parseRun(node, styles, theme, rels, media, inScopeXmlns);
+		case "bookmarkStart": return parseBookmarkStart(node);
+		case "bookmarkEnd": return parseBookmarkEnd(node);
+		default: return null;
+	}
+}
+/**
 * Get the display text of a hyperlink
 *
 * Concatenates text from all child runs.
@@ -219,4 +225,4 @@ function createExternalHyperlink(url, children, options) {
 	};
 }
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };

package/dist/docx/paraIdRangeNormalization.d.ts

@@ -0,0 +1,40 @@
+//#region src/docx/paraIdRangeNormalization.d.ts
+/**
+ * Keep every paragraph id a package carries inside the range the schema gives
+ * it.
+ *
+ * `w14:paraId`, `w14:textId` and the comment-part ids that reference a
+ * paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
+ * `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
+ * digits without that bound, and folio preserves the ids a document arrives
+ * with — so a package can carry an out-of-range id in, and a save that copies
+ * it through hands a consumer a package it will refuse.
+ *
+ * {@link paraIdInRange} is the one mapping, and it is a pure function of the
+ * value alone. That is what lets the parser and the save agree without
+ * consulting each other: a paragraph's id in the model is the id the file gets,
+ * so bringing an id into range does not make a document's own identity move
+ * under it between reading and writing. The package pass below is the same
+ * mapping applied to every attribute that carries such an id, so a paragraph
+ * and every reference to it move together.
+ */
+/**
+ * `value` when it already fits, and a value derived from it when it does not.
+ *
+ * The replacement is derived from the id being replaced and from nothing else.
+ * A package-aware search for a free id would read better here and would be
+ * wrong: the parser has no package to search, and an id that means one
+ * paragraph while reading and another while writing is worse than the
+ * vanishing chance of two rewritten ids landing on one value, which is a
+ * duplicate rather than a package a consumer refuses.
+ */
+declare const paraIdInRange: (value: string) => string;
+/**
+ * Rewrite out-of-range paragraph ids across a whole package.
+ *
+ * Returns the parts unchanged when every id already fits, so a save of a
+ * document that never carried one is byte-identical.
+ */
+declare const normalizeParaIdRangeInXmlParts: (parts: ReadonlyMap<string, string>) => Map<string, string>;
+//#endregion
+export { normalizeParaIdRangeInXmlParts, paraIdInRange };

package/dist/docx/paraIdRangeNormalization.js

@@ -0,0 +1,64 @@
+import { deterministicHexId } from "../utils/hexId.js";
+//#region src/docx/paraIdRangeNormalization.ts
+/**
+* Keep every paragraph id a package carries inside the range the schema gives
+* it.
+*
+* `w14:paraId`, `w14:textId` and the comment-part ids that reference a
+* paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
+* `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
+* digits without that bound, and folio preserves the ids a document arrives
+* with — so a package can carry an out-of-range id in, and a save that copies
+* it through hands a consumer a package it will refuse.
+*
+* {@link paraIdInRange} is the one mapping, and it is a pure function of the
+* value alone. That is what lets the parser and the save agree without
+* consulting each other: a paragraph's id in the model is the id the file gets,
+* so bringing an id into range does not make a document's own identity move
+* under it between reading and writing. The package pass below is the same
+* mapping applied to every attribute that carries such an id, so a paragraph
+* and every reference to it move together.
+*/
+/** Exclusive upper bound on a paragraph id: the values are 31-bit. */
+const MAX_PARA_ID_EXCLUSIVE = 2147483648;
+/**
+* Every attribute that carries a paragraph id or the text-revision marker
+* written beside one: the paragraph's own `w14:paraId` / `w14:textId` (the
+* parser accepts a `w:` prefix too), the comment part's `w15:paraId` and the
+* `w15:paraIdParent` that links a reply to its thread, and the durable-comment
+* part's `w16cid:paraId`.
+*/
+const PARA_ID_ATTRIBUTE = /\b(w|w14|w15|w16cid):(paraId|paraIdParent|textId)=(?<quote>["'])([0-9A-Fa-f]{8})\k<quote>/gu;
+/** A candidate part is one that mentions any of those attributes at all. */
+const PARA_ID_CANDIDATE = /\b(?:w|w14|w15|w16cid):(?:paraId|paraIdParent|textId)=/u;
+/**
+* `value` when it already fits, and a value derived from it when it does not.
+*
+* The replacement is derived from the id being replaced and from nothing else.
+* A package-aware search for a free id would read better here and would be
+* wrong: the parser has no package to search, and an id that means one
+* paragraph while reading and another while writing is worse than the
+* vanishing chance of two rewritten ids landing on one value, which is a
+* duplicate rather than a package a consumer refuses.
+*/
+const paraIdInRange = (value) => Number.parseInt(value, 16) < MAX_PARA_ID_EXCLUSIVE ? value : deterministicHexId(value);
+/**
+* Rewrite out-of-range paragraph ids across a whole package.
+*
+* Returns the parts unchanged when every id already fits, so a save of a
+* document that never carried one is byte-identical.
+*/
+const normalizeParaIdRangeInXmlParts = (parts) => {
+	const normalized = new Map(parts);
+	for (const [path, xml] of parts) {
+		if (!PARA_ID_CANDIDATE.test(xml)) continue;
+		const rewritten = xml.replaceAll(PARA_ID_ATTRIBUTE, (whole, prefix, name, quote, value) => {
+			const replacement = paraIdInRange(value);
+			return replacement === value ? whole : `${prefix}:${name}=${quote}${replacement}${quote}`;
+		});
+		if (rewritten !== xml) normalized.set(path, rewritten);
+	}
+	return normalized;
+};
+//#endregion
+export { normalizeParaIdRangeInXmlParts, paraIdInRange };

package/dist/docx/paragraphParser.js

@@ -2,8 +2,9 @@ import { isValidHexColor } from "../utils/colorResolver.js";
 import { isValidHexId } from "../utils/hexId.js";
 import { parseBookmarkEnd as parseBookmarkEnd$1, parseBookmarkStart as parseBookmarkStart$1 } from "./bookmarkParser.js";
 import { parseFieldType } from "./fieldParser.js";
-import { parseHyperlink as parseHyperlink$1 } from "./hyperlinkParser.js";
+import { parseHyperlink as parseHyperlink$1, parseHyperlinkChild } from "./hyperlinkParser.js";
 import { markerFormattingFromLevel } from "./numberingParser.js";
+import { paraIdInRange } from "./paraIdRangeNormalization.js";
 import { BorderStyleSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, TabLeaderSchema, TabStopAlignmentSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
 import { consolidateParagraphContent } from "./runConsolidator.js";
 import { parseRun, parseRunProperties } from "./runParser.js";
@@ -646,6 +647,80 @@ function pushInlineSdtSegments({ contents, properties, parsedContent }) {
 function parseHyperlink(node, rels, styles, theme, media, rootXmlns = {}) {
 	return parseHyperlink$1(node, rels, styles, theme, media, rootXmlns);
 }
+/** The revision wrapper a `w:hyperlink` child is, when it is one. */
+const hyperlinkRevisionWrapperType = (node) => {
+	switch (getLocalName(node.name)) {
+		case "ins": return "insertion";
+		case "del": return "deletion";
+		case "moveFrom": return "moveFrom";
+		case "moveTo": return "moveTo";
+		default: return;
+	}
+};
+const isHyperlinkChildContent = (content) => content.type === "run" || content.type === "bookmarkStart" || content.type === "bookmarkEnd";
+/**
+* A `w:hyperlink` as paragraph content, with any revision wrapper it holds
+* hoisted around it.
+*
+* OOXML nests `w:ins`/`w:del` INSIDE `w:hyperlink`; the model nests the
+* hyperlink inside the revision, because a revision is the unit a redline
+* reads and a link that is half deleted is two links to it. This is the exact
+* inverse of what the serializer writes, so a package survives the round trip.
+*/
+function parseHyperlinkParagraphContents(node, rels, styles, theme, media, rootXmlns) {
+	const children = getChildElements(node);
+	if (!children.some((child) => hyperlinkRevisionWrapperType(child) !== void 0)) return [parseHyperlink(node, rels, styles, theme, media, rootXmlns)];
+	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
+	const shell = parseHyperlink(node, rels, styles, theme, media, rootXmlns);
+	const linkOver = (linkChildren) => ({
+		...shell,
+		children: [...linkChildren]
+	});
+	const contents = [];
+	let plain = [];
+	const flushPlain = () => {
+		if (plain.length > 0) {
+			contents.push(linkOver(plain));
+			plain = [];
+		}
+	};
+	for (const child of children) {
+		const wrapperType = hyperlinkRevisionWrapperType(child);
+		if (wrapperType === void 0) {
+			const parsed = parseHyperlinkChild(child, styles, theme, rels, media, inScopeXmlns);
+			if (parsed) plain.push(parsed);
+			continue;
+		}
+		flushPlain();
+		const wrapped = parseParagraphContents(child, styles, theme, null, rels, media, wrapperType === "deletion" || wrapperType === "moveFrom" ? "deletion" : "default", inScopeXmlns);
+		const content = [];
+		let linked = [];
+		const flushLinked = () => {
+			if (linked.length > 0) {
+				content.push(linkOver(linked));
+				linked = [];
+			}
+		};
+		for (const item of wrapped) {
+			if (isHyperlinkChildContent(item)) {
+				linked.push(item);
+				continue;
+			}
+			flushLinked();
+			if (isTrackedChangeWrapperChild(item)) content.push(item);
+		}
+		flushLinked();
+		pushTrackedChangeWrapper({
+			contents,
+			type: wrapperType,
+			info: parseTrackedChangeInfo(child),
+			content,
+			preserveEmpty: true
+		});
+	}
+	flushPlain();
+	return contents;
+}
 /**
 * Parse bookmark start (w:bookmarkStart)
 * Delegates to bookmarkParser module.
@@ -798,7 +873,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				break;
 			}
 			case "hyperlink":
-				contents.push(parseHyperlink(child, rels, styles, theme, media, inScopeXmlns));
+				contents.push(...parseHyperlinkParagraphContents(child, rels, styles, theme, media, inScopeXmlns));
 				break;
 			case "bookmarkStart":
 				contents.push(parseBookmarkStart(child));
@@ -961,9 +1036,9 @@ function parseParagraph(node, styles, theme, numbering, rels = null, media = nul
 		content: []
 	};
 	const paraId = getAttribute(node, "w14", "paraId") ?? getAttribute(node, "w", "paraId");
-	if (paraId && isValidHexId(paraId)) paragraph.paraId = paraId;
+	if (paraId && isValidHexId(paraId)) paragraph.paraId = paraIdInRange(paraId);
 	const textId = getAttribute(node, "w14", "textId") ?? getAttribute(node, "w", "textId");
-	if (textId && isValidHexId(textId)) paragraph.textId = textId;
+	if (textId && isValidHexId(textId)) paragraph.textId = paraIdInRange(textId);
 	if (!options?.inHeaderFooter && paragraphStartsWithRenderedPageBreak(node)) paragraph.renderedPageBreakBefore = true;
 	const pPr = findChild(node, "w", "pPr");
 	if (pPr) {

package/dist/docx/revisionIdNormalization.d.ts

@@ -1,4 +1,18 @@
 //#region src/docx/revisionIdNormalization.d.ts
+declare const RevisionIdCollisionError_base: import("better-result").TaggedErrorClass<"RevisionIdCollisionError">;
+/**
+ * Two revision elements in one package claimed the same `w:id`.
+ *
+ * `w:id` on a revision element is unique across the package, so a collision is
+ * a package a consumer may reject rather than a cosmetic detail. The
+ * normalization below hands every id it emits to one choke point, which throws
+ * this rather than letting the duplicate reach the ZIP.
+ */
+declare class RevisionIdCollisionError extends RevisionIdCollisionError_base<{
+  message: string;
+  revisionId: number;
+  part: string;
+}> {}
 declare const REVISION_ELEMENT_NAMES: Set<string>;
 /**
  * Keep physical tracked-change element ids unique across a package.
@@ -10,4 +24,4 @@ declare const REVISION_ELEMENT_NAMES: Set<string>;
  */
 declare const normalizeRevisionIdsInXmlParts: (parts: ReadonlyMap<string, string>) => Map<string, string>;
 //#endregion
-export { REVISION_ELEMENT_NAMES, normalizeRevisionIdsInXmlParts };
+export { REVISION_ELEMENT_NAMES, RevisionIdCollisionError, normalizeRevisionIdsInXmlParts };

package/dist/docx/revisionIdNormalization.js

@@ -1,7 +1,17 @@
 import { rewriteStreamingXmlDecimalAttributes } from "./streamingXmlParser.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, findAttributeByNamespaceUri, getLocalName, getNamespaceUri } from "./xmlParser.js";
 import { XmlResourceLimitError, assertXmlResourceLimits } from "./xmlResourceLimits.js";
+import { TaggedError } from "better-result";
 //#region src/docx/revisionIdNormalization.ts
+/**
+* Two revision elements in one package claimed the same `w:id`.
+*
+* `w:id` on a revision element is unique across the package, so a collision is
+* a package a consumer may reject rather than a cosmetic detail. The
+* normalization below hands every id it emits to one choke point, which throws
+* this rather than letting the duplicate reach the ZIP.
+*/
+var RevisionIdCollisionError = class extends TaggedError("RevisionIdCollisionError") {};
 const REVISION_ELEMENT_NAMES = /* @__PURE__ */ new Set([
 	"cellDel",
 	"cellIns",
@@ -76,19 +86,27 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	for (const [path, xml] of candidates) {
 		const ids = occurrencesByPath.get(path);
 		if (!ids) continue;
+		const claim = (id) => {
+			if (seen.has(id)) throw new RevisionIdCollisionError({
+				message: `Revision id ${String(id)} is claimed twice in ${path}`,
+				revisionId: id,
+				part: path
+			});
+			seen.add(id);
+		};
 		if (!repeatedPaths.has(path) && ids.every((id) => !seen.has(id))) {
-			for (const id of ids) seen.add(id);
+			for (const id of ids) claim(id);
 			continue;
 		}
 		const rewritten = rewriteStreamingXmlDecimalAttributes(xml, (element) => {
 			const attribute = revisionAttribute(element);
 			if (!attribute) return null;
 			if (!seen.has(attribute.id)) {
-				seen.add(attribute.id);
+				claim(attribute.id);
 				return null;
 			}
 			const replacement = allocate();
-			seen.add(replacement);
+			claim(replacement);
 			return /* @__PURE__ */ new Map([[attribute.name, String(replacement)]]);
 		});
 		if (rewritten.status === "unsupported") throw new XmlResourceLimitError({
@@ -100,4 +118,4 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	return normalized;
 };
 //#endregion
-export { REVISION_ELEMENT_NAMES, normalizeRevisionIdsInXmlParts };
+export { REVISION_ELEMENT_NAMES, RevisionIdCollisionError, normalizeRevisionIdsInXmlParts };

package/dist/docx/rezip.d.ts

@@ -105,6 +105,12 @@ declare function updateMultipleFiles(originalBuffer: ArrayBuffer, updates: Map<s
 /**
  * Apply file updates to an already-loaded JSZip instance and generate the output.
  * Use this when the zip is already loaded to avoid a redundant decompression pass.
+ *
+ * This is the selective save's exit, so it owes the package the same id passes
+ * {@link generateDocxZip} runs: a save that rewrites only the changed
+ * paragraphs still has to see the parts it left alone, both to know which
+ * revision ids are free and because an out-of-range paragraph id can sit in a
+ * part it never touched.
  */
 declare function applyUpdatesToZip(zip: JSZip, updates: Map<string, string | ArrayBuffer>, options?: RepackOptions): Promise<ArrayBuffer>;
 /**

package/dist/docx/rezip.js

@@ -6,6 +6,7 @@ import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
 import { parseNumbering } from "./numberingParser.js";
 import { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries } from "./packageParts.js";
+import { normalizeParaIdRangeInXmlParts } from "./paraIdRangeNormalization.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRevisionIdsInXmlParts } from "./revisionIdNormalization.js";
 import { appendNumberingDefs, buildPatchedNotePartXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
@@ -407,19 +408,34 @@ async function processNewHyperlinks(parts, zip, compressionLevel) {
 	}
 }
 /**
-* The single exit for a repacked package. Reconciliation runs here rather than
-* at each caller so no save path can emit a package whose relationships or
-* content types name a part it does not hold.
+* Bring the ids a package addresses itself by inside the bounds the format
+* gives them.
+*
+* Both bounds belong to the package rather than to a part, and neither is
+* something one serializer can see on its own. A revision `w:id` is unique
+* across the package, and one logical revision serializes as several physical
+* wrappers — a word diff cut around unchanged words, a revision split around a
+* hyperlink. A paragraph id is 31-bit, and a paragraph is referenced by id
+* from parts other than the one it lives in. So the passes run at the exits,
+* over every `word/*.xml` part including the ones a save left untouched.
 */
-const generateDocxZip = async (zip, compressionLevel) => {
-	await reconcilePackageReferences(zip, compressionLevel);
+const normalizePackageIdsInZip = async (zip, compressionLevel) => {
 	const xmlParts = /* @__PURE__ */ new Map();
 	for (const [path, file] of Object.entries(zip.files)) if (!file.dir && path.startsWith("word/") && path.endsWith(".xml")) xmlParts.set(path, await file.async("text"));
-	const normalizedParts = normalizeRevisionIdsInXmlParts(xmlParts);
+	const normalizedParts = normalizeParaIdRangeInXmlParts(normalizeRevisionIdsInXmlParts(xmlParts));
 	for (const [path, xml] of normalizedParts) if (xml !== xmlParts.get(path)) zip.file(path, xml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
+};
+/**
+* The single exit for a repacked package. Reconciliation runs here rather than
+* at each caller so no save path can emit a package whose relationships or
+* content types name a part it does not hold.
+*/
+const generateDocxZip = async (zip, compressionLevel) => {
+	await reconcilePackageReferences(zip, compressionLevel);
+	await normalizePackageIdsInZip(zip, compressionLevel);
 	return zip.generateAsync({
 		type: "arraybuffer",
 		compression: "DEFLATE",
@@ -758,14 +774,21 @@ async function updateMultipleFiles(originalBuffer, updates, options = {}) {
 /**
 * Apply file updates to an already-loaded JSZip instance and generate the output.
 * Use this when the zip is already loaded to avoid a redundant decompression pass.
+*
+* This is the selective save's exit, so it owes the package the same id passes
+* {@link generateDocxZip} runs: a save that rewrites only the changed
+* paragraphs still has to see the parts it left alone, both to know which
+* revision ids are free and because an out-of-range paragraph id can sit in a
+* part it never touched.
 */
-function applyUpdatesToZip(zip, updates, options = {}) {
+async function applyUpdatesToZip(zip, updates, options = {}) {
 	const { compressionLevel = 6 } = options;
 	for (const [path, content] of updates) zip.file(path, content, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
-	return zip.generateAsync({
+	await normalizePackageIdsInZip(zip, compressionLevel);
+	return await zip.generateAsync({
 		type: "arraybuffer",
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }

package/dist/docx/serializer/paragraphSerializer.js

@@ -210,10 +210,8 @@ function serializeParagraphPropertyChange(change) {
 	const normalizedPreviousPPr = previousPPrInner.length > 0 ? `<w:pPr>${previousPPrInner}</w:pPr>` : "<w:pPr/>";
 	return `<w:pPrChange ${attrs.join(" ")}>${normalizedPreviousPPr}</w:pPrChange>`;
 }
-/**
-* Serialize a hyperlink (w:hyperlink)
-*/
-function serializeHyperlink(hyperlink) {
+/** The attribute list of a `w:hyperlink`, without its children. */
+function hyperlinkAttributes(hyperlink) {
 	const attrs = [];
 	if (hyperlink.rId) attrs.push(`r:id="${escapeXml(hyperlink.rId)}"`);
 	if (hyperlink.anchor) attrs.push(`w:anchor="${escapeXml(hyperlink.anchor)}"`);
@@ -222,12 +220,19 @@ function serializeHyperlink(hyperlink) {
 	if (hyperlink.history === true) attrs.push("w:history=\"1\"");
 	else if (hyperlink.history === false) attrs.push("w:history=\"0\"");
 	if (hyperlink.docLocation) attrs.push(`w:docLocation="${escapeXml(hyperlink.docLocation)}"`);
-	const childrenXml = hyperlink.children.map((child) => {
-		if (child.type === "run") return serializeRun(child);
-		if (child.type === "bookmarkStart") return serializeBookmarkStart(child);
-		return serializeBookmarkEnd(child);
-	}).join("");
-	return `<w:hyperlink${attrs.length > 0 ? ` ${attrs.join(" ")}` : ""}>${childrenXml}</w:hyperlink>`;
+	return attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+}
+/** One `w:hyperlink` child, with the caller deciding how a run is written. */
+function serializeHyperlinkChild(child, serializeChildRun) {
+	if (child.type === "run") return serializeChildRun(child);
+	return child.type === "bookmarkStart" ? serializeBookmarkStart(child) : serializeBookmarkEnd(child);
+}
+/**
+* Serialize a hyperlink (w:hyperlink)
+*/
+function serializeHyperlink(hyperlink) {
+	const childrenXml = hyperlink.children.map((child) => serializeHyperlinkChild(child, serializeRun)).join("");
+	return `<w:hyperlink${hyperlinkAttributes(hyperlink)}>${childrenXml}</w:hyperlink>`;
 }
 /**
 * Serialize bookmark start (w:bookmarkStart)
@@ -397,20 +402,39 @@ function serializeTrackedChange(tag, change) {
 			return rewriteRunTextAsDeleted(contentXml);
 		}).join("");
 	};
-	const contentXml = change.content.map((item) => {
-		if (item.type === "run") {
-			if (tag === "del" || tag === "moveFrom") return serializeDeletedRun(item);
-			return serializeRun(item);
-		}
-		if (item.type === "hyperlink") return serializeHyperlink(item);
+	const serializeContentRun = (run) => tag === "del" || tag === "moveFrom" ? serializeDeletedRun(run) : serializeRun(run);
+	const serializeWrappedItem = (item) => {
+		if (item.type === "run") return serializeContentRun(item);
 		if (item.type === "simpleField" || item.type === "complexField") {
 			const xml = item.type === "simpleField" ? serializeSimpleField(item) : serializeComplexField(item);
 			return tag === "del" || tag === "moveFrom" ? rewriteRunTextAsDeleted(xml) : xml;
 		}
 		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") return serializeTrackedChange(trackedChangeTag(item), item);
 		return item.type === "bookmarkStart" ? serializeBookmarkStart(item) : serializeBookmarkEnd(item);
-	}).join("");
-	return `<w:${tag} ${attrs.join(" ")}>${contentXml}</w:${tag}>`;
+	};
+	const open = `<w:${tag} ${attrs.join(" ")}>`;
+	const close = `</w:${tag}>`;
+	const wrap = (inner) => inner.length === 0 ? "" : `${open}${inner}${close}`;
+	if (change.content.length === 0) return `${open}${close}`;
+	const segments = [];
+	const pending = [];
+	const flushPending = () => {
+		if (pending.length > 0) {
+			segments.push(wrap(pending.join("")));
+			pending.length = 0;
+		}
+	};
+	for (const item of change.content) {
+		if (item.type === "hyperlink") {
+			flushPending();
+			const childrenXml = item.children.map((child) => serializeHyperlinkChild(child, serializeContentRun)).join("");
+			segments.push(`<w:hyperlink${hyperlinkAttributes(item)}>${open}${childrenXml}${close}</w:hyperlink>`);
+			continue;
+		}
+		pending.push(serializeWrappedItem(item));
+	}
+	flushPending();
+	return segments.join("");
 }
 /** Emit the `<w:commentReference>` run Word places after a comment range end. */
 function serializeCommentReferenceRun(id) {

package/dist/docx/serializer/tableSerializer.js

@@ -277,11 +277,30 @@ function serializeTableCellPropertyChange(change) {
 	return `<w:tcPrChange ${attrs}>${previousTcPrInner.length > 0 ? `<w:tcPr>${previousTcPrInner}</w:tcPr>` : "<w:tcPr/>"}</w:tcPrChange>`;
 }
 /**
-* Serialize table grid (w:tblGrid)
+* Columns the grid has to declare: the widest row's span total, because a grid
+* narrower than a row leaves cells with no column to sit in.
 */
-function serializeTableGrid(columnWidths) {
-	if (!columnWidths || columnWidths.length === 0) return "";
-	return `<w:tblGrid>${columnWidths.map((w) => `<w:gridCol w:w="${intAttr(w)}"/>`).join("")}</w:tblGrid>`;
+function gridColumnCount(table) {
+	let widest = 0;
+	for (const row of table.rows) {
+		let columns = 0;
+		for (const cell of row.cells) columns += cell.formatting?.gridSpan ?? 1;
+		widest = Math.max(widest, columns);
+	}
+	return widest;
+}
+/**
+* Serialize table grid (w:tblGrid).
+*
+* `w:tblGrid` is required on every `w:tbl` and `w:w` is optional on a
+* `w:gridCol`, so a table whose column widths were never measured — one the
+* comparison creates, say — still declares a grid, just without widths.
+*/
+function serializeTableGrid(table) {
+	const columnWidths = table.columnWidths;
+	if (columnWidths && columnWidths.length > 0) return `<w:tblGrid>${columnWidths.map((w) => `<w:gridCol w:w="${intAttr(w)}"/>`).join("")}</w:tblGrid>`;
+	const columns = gridColumnCount(table);
+	return columns === 0 ? "<w:tblGrid/>" : `<w:tblGrid>${"<w:gridCol/>".repeat(columns)}</w:tblGrid>`;
 }
 /**
 * Serialize cell content (paragraphs, nested tables)
@@ -320,11 +339,7 @@ function serializeTableRow(row, serializeParagraph) {
 * @returns XML string for the table
 */
 function serializeTable(table, serializeParagraph) {
-	const parts = [];
-	const tblPrXml = serializeTableFormatting(table.formatting, table.propertyChanges);
-	if (tblPrXml) parts.push(tblPrXml);
-	const tblGridXml = serializeTableGrid(table.columnWidths);
-	if (tblGridXml) parts.push(tblGridXml);
+	const parts = [serializeTableFormatting(table.formatting, table.propertyChanges) || "<w:tblPr/>", serializeTableGrid(table)];
 	for (const row of table.rows) parts.push(serializeTableRow(row, serializeParagraph));
 	return `<w:tbl>${parts.join("")}</w:tbl>`;
 }

package/dist/index.d.ts

@@ -10,8 +10,8 @@ import { AIBarStatus, AIChatMode, AICitation, AICitationSource, AIGenerateInput,
 import { ApplyResult, applySuggestions } from "./ai-suggestions/apply.js";
 import { ResolvedAnchor, isSuggestionStale, resolveSuggestionAnchor } from "./ai-suggestions/conflict.js";
 import { PositionalText, buildPositionalText } from "./ai-suggestions/text-positions.js";
-import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant } from "./compare/verification.js";
-import { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError } from "./compare/types.js";
+import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant, FinalParagraphMarkDeletion } from "./compare/verification.js";
+import { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError } from "./compare/types.js";
 import { MAX_COMPARE_OPERATIONS, compareDocx } from "./compare/compare.js";
 import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocumentPreset, DocumentStyleSet } from "./style-sets/types.js";
 import { CreateEmptyDocumentOptions, createEmptyDocument } from "./utils/createDocument.js";
@@ -38,4 +38,4 @@ import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 type Document = document_d_exports.Document;
 type DocxConformanceClass = document_d_exports.DocxConformanceClass;
-export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, CompareDocxApplyError, type CompareDocxError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFormatRange, type CompareResult, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, 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 FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, CompareDocxApplyError, type CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFormatRange, type CompareResult, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, 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 FinalParagraphMarkDeletion, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };