@stll/folio-core 0.52.0 → 0.54.0

package/dist/document-operations.d.ts

@@ -1,7 +1,7 @@
 import { document_d_exports } from "./types/document.js";
 import { FolioTableTemplates } from "./ai-edits/table-template.js";
 import { FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditNormalization, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAITextRangeHandle } from "./ai-edits/types.js";
-import { FolioAIEditView, FolioReplacementBackground, FolioRevisionStamp, FolioWordDiffOptions } from "./ai-edits/apply.js";
+import { FolioAIEditView, FolioReplacementBackground, FolioRevisionStamp, FolioUndefinedStylePolicy, FolioWordDiffOptions } from "./ai-edits/apply.js";
 //#region src/document-operations.d.ts
 declare const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION: 1;
 /** Direct paragraph-alignment values accepted by the operation contract. */
@@ -132,6 +132,8 @@ type FolioDocumentOperationIssue = {
   code: FolioAIEditSkippedOperation["reason"];
   retryable: boolean;
   recovery: FolioDocumentOperationRecovery;
+  /** The skip's detail, when it has one; see {@link FolioAIEditSkippedOperation.message}. */
+  message?: string;
 };
 type FolioDocumentOperationStory = "main" | {
   type: "header";
@@ -289,7 +291,14 @@ type ApplyFolioDocumentOperationsOptions = {
    * revised document — keeps them instead.
    */
   replacementBackground?: FolioReplacementBackground;
+  /**
+   * What an operation naming a paragraph style the document does not define
+   * does. Refusing it (`missingStyle`) is the default; a caller copying the
+   * style references of another document — a comparison reproducing the
+   * revised one — keeps them instead.
+   */
+  undefinedStyles?: FolioUndefinedStylePolicy;
 };
-declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
+declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
 export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -1,5 +1,10 @@
-import { applyFolioAIEditOperations, previewFolioAIEditOperations } from "./ai-edits/apply.js";
+import { applyFolioAIEditOperations, previewFolioAIEditOperationsWithResult } from "./ai-edits/apply.js";
+import { describeModelError, findIntroducedModelErrors } from "./ai-edits/result-validation.js";
+import { LIST_KINDS } from "./docx/listNumberingInstances.js";
 import { isNumberingReference } from "./docx/numberingReference.js";
+import { completeNumberingForDoc } from "./prosemirror/listInstanceReferences.js";
+import { outlineLevelFromAttrValue } from "./prosemirror/outlineLevelAttr.js";
+import { getStatedDocumentNumbering } from "./prosemirror/plugins/documentNumbering.js";
 import { LINE_SPACING_RULE_VALUES, PARAGRAPH_ALIGNMENT_VALUES } from "./types/documentEnumValues.js";
 import { TaggedError } from "better-result";
 import { sanitizeXmlCharacters } from "@stll/docx-core";
@@ -293,11 +298,40 @@ const readClearableParagraphIndentation = ({ value, key, path }) => {
 	}
 	return indentation;
 };
+/** `w:ilvl` names one of an abstract numbering's nine levels. */
+const MAX_NEW_LIST_LEVEL = 8;
+const LIST_KIND_SET = new Set(LIST_KINDS);
+const isListKind = (value) => LIST_KIND_SET.has(value);
+/** `{ start: "new", kind, level? }`: a list the operation starts. */
+const readNewListReference = (candidate, numberingPath) => {
+	assertAllowedKeys(candidate, numberingPath, [
+		"start",
+		"kind",
+		"level"
+	]);
+	const kind = candidate["kind"];
+	if (typeof kind !== "string" || !isListKind(kind)) return invalidBatch(`${numberingPath}.kind`, `expected one of ${LIST_KINDS.join(", ")}`);
+	if (candidate["level"] === void 0) return {
+		start: "new",
+		kind
+	};
+	const level = readNonNegativeInteger(candidate, "level", numberingPath);
+	if (level > MAX_NEW_LIST_LEVEL) return invalidBatch(`${numberingPath}.level`, `expected at most ${MAX_NEW_LIST_LEVEL}`);
+	return {
+		start: "new",
+		kind,
+		level
+	};
+};
 const readClearableNumbering = ({ value, key, path }) => {
 	const candidate = value[key];
 	if (candidate === void 0 || candidate === null) return candidate;
 	const numberingPath = `${path}.${key}`;
 	if (!isPlainObject(candidate)) return invalidBatch(numberingPath, "expected an object or null when provided");
+	if (candidate["start"] !== void 0) {
+		if (candidate["start"] !== "new") return invalidBatch(`${numberingPath}.start`, "expected \"new\"");
+		return readNewListReference(candidate, numberingPath);
+	}
 	assertAllowedKeys(candidate, numberingPath, ["numId", "level"]);
 	const numId = readNonNegativeInteger(candidate, "numId", numberingPath);
 	if (!isNumberingReference(numId)) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
@@ -326,12 +360,22 @@ const readTableRows = (value, path) => {
 	if (parsed.some((row) => row.length !== width)) return invalidBatch(rowsPath, "expected every row to hold the same number of cells");
 	return parsed;
 };
+const readClearableOutlineLevel = (value, path) => {
+	const candidate = value["outlineLevel"];
+	if (candidate === void 0 || candidate === null) return candidate;
+	if (!isPlainObject(candidate)) return invalidBatch(`${path}.outlineLevel`, "expected an outline level");
+	assertAllowedKeys(candidate, `${path}.outlineLevel`, ["kind", "level"]);
+	const outlineLevel = outlineLevelFromAttrValue(candidate);
+	if (outlineLevel === null) return invalidBatch(`${path}.outlineLevel`, "expected a valid outline level");
+	return outlineLevel;
+};
 const readParagraphProperties = ({ value, key, path }) => {
 	const candidate = value[key];
 	const propertiesPath = `${path}.${key}`;
 	if (!isPlainObject(candidate)) return invalidBatch(propertiesPath, "expected an object");
 	assertAllowedKeys(candidate, propertiesPath, [
 		"styleId",
+		"outlineLevel",
 		"listLevel",
 		"numbering",
 		"alignment",
@@ -339,6 +383,7 @@ const readParagraphProperties = ({ value, key, path }) => {
 		"indentation"
 	]);
 	const styleId = candidate["styleId"] === null ? null : readOptionalString(candidate, "styleId", propertiesPath);
+	const outlineLevel = readClearableOutlineLevel(candidate, propertiesPath);
 	const listLevel = readClearableNonNegativeInteger(candidate, "listLevel", propertiesPath);
 	const numbering = readClearableNumbering({
 		value: candidate,
@@ -360,9 +405,10 @@ const readParagraphProperties = ({ value, key, path }) => {
 		key: "indentation",
 		path: propertiesPath
 	});
-	if (styleId === void 0 && listLevel === void 0 && numbering === void 0 && alignment === void 0 && spacing === void 0 && indentation === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
+	if (styleId === void 0 && outlineLevel === void 0 && listLevel === void 0 && numbering === void 0 && alignment === void 0 && spacing === void 0 && indentation === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
 	return {
 		...styleId !== void 0 && { styleId },
+		...outlineLevel !== void 0 && { outlineLevel },
 		...listLevel !== void 0 && { listLevel },
 		...numbering !== void 0 && { numbering },
 		...alignment !== void 0 && { alignment },
@@ -515,6 +561,7 @@ const OPERATION_KEY_DECISIONS = {
 		pageBreakBefore: true,
 		hardPageBreak: true,
 		styleId: true,
+		outlineLevel: true,
 		comment: true
 	},
 	insertBeforeBlock: {
@@ -532,6 +579,7 @@ const OPERATION_KEY_DECISIONS = {
 		pageBreakBefore: true,
 		hardPageBreak: true,
 		styleId: true,
+		outlineLevel: true,
 		comment: true
 	},
 	replaceBlock: {
@@ -783,6 +831,7 @@ const parseDocumentOperation = (value, index) => {
 		const pageBreakBefore = readOptionalBoolean(value, "pageBreakBefore", path);
 		const hardPageBreak = readOptionalHardPageBreak(value, path);
 		const styleId = value["styleId"] === null ? null : readOptionalString(value, "styleId", path);
+		const outlineLevel = readClearableOutlineLevel(value, path);
 		const moveId = readOptionalString(value, "moveId", path);
 		const listLevel = readClearableNonNegativeInteger(value, "listLevel", path);
 		const numbering = readClearableNumbering({
@@ -810,7 +859,7 @@ const parseDocumentOperation = (value, index) => {
 		const formattingScope = value["formattingScope"];
 		if (formattingScope !== void 0 && formattingScope !== "firstParagraph" && formattingScope !== "allParagraphs") return invalidBatch(`${path}.formattingScope`, "expected \"firstParagraph\" or \"allParagraphs\" when provided");
 		const text = readString(value, "text", path);
-		if (hardPageBreak !== void 0 && text.length > 0) return invalidBatch(`${path}.text`, "expected empty text with hardPageBreak");
+		if (hardPageBreak !== void 0 && text.length > 0) return invalidBatch(`${path}.text`, "omit hardPageBreak to insert text, or set text to \"\" to insert a hard page break");
 		if (hardPageBreak !== void 0 && pageBreakBefore !== void 0) return invalidBatch(`${path}.pageBreakBefore`, "cannot combine hardPageBreak with pageBreakBefore");
 		if (hardPageBreak !== void 0 && lineBreakMode !== void 0) return invalidBatch(`${path}.lineBreakMode`, "cannot combine hardPageBreak with lineBreakMode");
 		return {
@@ -831,6 +880,7 @@ const parseDocumentOperation = (value, index) => {
 			...pageBreakBefore !== void 0 && { pageBreakBefore },
 			...hardPageBreak !== void 0 && { hardPageBreak },
 			...styleId !== void 0 && { styleId },
+			...outlineLevel !== void 0 && { outlineLevel },
 			...comment !== void 0 && { comment }
 		};
 	}
@@ -1014,22 +1064,31 @@ const recoveryByReason = {
 	pendingRunPropertyChange: "resolveTrackedChange",
 	noopOperation: "removeOperation",
 	documentVersionMismatch: "refreshDocument",
-	documentNotEditable: "retryLater"
+	documentNotEditable: "retryLater",
+	payloadDoesNotFit: "changeTarget",
+	overlappingOperation: "refreshDocument",
+	splitsCharacter: "changeTarget",
+	protectedReference: "narrowMatch",
+	missingStyle: "refreshDocument",
+	missingNumbering: "refreshDocument",
+	invalidResult: "refreshDocument",
+	pendingDeletion: "resolveTrackedChange"
 };
 const getFolioDocumentOperationIssues = (operations, skipped) => {
 	const indexById = /* @__PURE__ */ new Map();
 	operations.forEach(({ id }, index) => {
 		indexById.set(id, index);
 	});
-	return skipped.map(({ id, reason }) => {
+	return skipped.map(({ id, reason, message }) => {
 		const operationIndex = indexById.get(id) ?? -1;
 		return {
 			operationId: id,
 			operationIndex,
 			path: `$.operations[${operationIndex}]`,
 			code: reason,
-			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange",
-			recovery: recoveryByReason[reason]
+			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
+			recovery: recoveryByReason[reason],
+			...message !== void 0 && { message }
 		};
 	});
 };
@@ -1183,26 +1242,173 @@ const getFolioDocumentOperationReceiptsForStory = ({ operations, applied, story
 	});
 	return receipts;
 };
-const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground }) => {
+const NO_COMMIT = () => {};
+/** Skips reported in the order of the operations they belong to. */
+const inOperationOrder = (operations, skipped) => {
+	const indexById = new Map(operations.map(({ id }, index) => [id, index]));
+	return [...skipped].sort((left, right) => (indexById.get(left.id) ?? -1) - (indexById.get(right.id) ?? -1));
+};
+const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }) => {
 	const parsedBatch = parseFolioDocumentOperationBatch(batch);
-	const apply = ({ targetView, targetCreateCommentId = createCommentId, preview = false }) => {
-		return (preview ? previewFolioAIEditOperations : applyFolioAIEditOperations)({
-			view: targetView,
+	const isAtomic = parsedBatch.atomic === true;
+	const beforeDoc = view.state.doc;
+	const packageNumbering = getStatedDocumentNumbering(view.state);
+	const attempt = (operations, preview) => {
+		const common = {
 			snapshot,
-			operations: parsedBatch.operations,
+			operations,
 			mode: parsedBatch.mode ?? "tracked-changes",
 			...author !== void 0 && { author },
-			...targetCreateCommentId !== void 0 && { createCommentId: targetCreateCommentId },
 			...revisionStamp !== void 0 && { revisionStamp },
 			...wordDiff !== void 0 && { wordDiff },
 			...tableTemplates !== void 0 && { tableTemplates },
-			...replacementBackground !== void 0 && { replacementBackground }
+			...replacementBackground !== void 0 && { replacementBackground },
+			...undefinedStyles !== void 0 && { undefinedStyles }
+		};
+		if (preview) return {
+			...previewFolioAIEditOperationsWithResult({
+				...common,
+				view,
+				...createCommentId !== void 0 && { createCommentId }
+			}),
+			commit: NO_COMMIT
+		};
+		const held = {};
+		const commentIds = [];
+		return {
+			outcome: applyFolioAIEditOperations({
+				...common,
+				view: {
+					state: view.state,
+					dispatch: (transaction) => {
+						held.transaction = transaction;
+					}
+				},
+				...createCommentId !== void 0 && { createCommentId: (text) => {
+					const id = createCommentId(text);
+					commentIds.push(id);
+					return id;
+				} }
+			}),
+			doc: held.transaction?.doc ?? null,
+			commentIds,
+			commit: () => {
+				if (held.transaction !== void 0) view.dispatch(held.transaction);
+			}
+		};
+	};
+	const introducedErrors = (run) => {
+		if (run.doc === null || run.outcome.applied.length === 0) return [];
+		const numbering = packageNumbering === void 0 ? void 0 : completeNumberingForDoc(packageNumbering ?? void 0, run.doc) ?? null;
+		return findIntroducedModelErrors(beforeDoc, run.doc, {
+			numbering,
+			createdCommentIds: run.commentIds,
+			...author !== void 0 && { commentAuthor: author }
 		});
 	};
-	const preview = () => apply({
-		targetView: view,
-		preview: true
-	});
+	/**
+	* An attempt on the refusal path, where the applier runs on subsets of the
+	* batch it was not asked to apply: a throw there is one more reason to
+	* refuse, never a reason to fail a batch the first run could apply.
+	*/
+	const checkedAttempt = (operations, preview) => {
+		try {
+			const run = attempt(operations, preview);
+			return {
+				run,
+				error: introducedErrors(run)[0]
+			};
+		} catch (error) {
+			return {
+				run: null,
+				error: {
+					path: "package.document",
+					message: `the operation could not be applied (${error instanceof Error ? error.message : String(error)}).`,
+					severity: "error"
+				}
+			};
+		}
+	};
+	/**
+	* Which applied operations produced the unsaveable result: each one is
+	* previewed alone against the unchanged story. When none fails alone, the
+	* failure is their combination, and every one of them is refused.
+	*/
+	const refuseInvalidResult = (run, firstError) => {
+		const operationsById = new Map(parsedBatch.operations.map((operation) => [operation.id, operation]));
+		const refused = [];
+		for (const { id } of run.outcome.applied) {
+			const operation = operationsById.get(id);
+			if (operation === void 0) continue;
+			const alone = checkedAttempt([operation], true).error;
+			if (alone !== void 0) refused.push({
+				id,
+				reason: "invalidResult",
+				message: describeModelError(alone)
+			});
+		}
+		if (refused.length > 0) return refused;
+		return run.outcome.applied.map(({ id }) => ({
+			id,
+			reason: "invalidResult",
+			message: describeModelError(firstError)
+		}));
+	};
+	/**
+	* Apply (or preview) the batch and check the result with the save-time
+	* validator before anything reaches the caller. Operations whose result would
+	* not save are skipped with `invalidResult`; in a best-effort batch the rest
+	* is applied again without them, in an atomic one nothing is.
+	*/
+	const guardedAttempt = (preview) => {
+		const first = attempt(parsedBatch.operations, preview);
+		const [firstError] = introducedErrors(first);
+		if (firstError === void 0) return {
+			outcome: {
+				...first.outcome,
+				skipped: inOperationOrder(parsedBatch.operations, first.outcome.skipped)
+			},
+			commit: first.commit
+		};
+		const refused = refuseInvalidResult(first, firstError);
+		const refusedIds = new Set(refused.map(({ id }) => id));
+		if (isAtomic) return {
+			outcome: {
+				...first.outcome,
+				applied: [],
+				skipped: inOperationOrder(parsedBatch.operations, [...first.outcome.skipped, ...refused])
+			},
+			commit: NO_COMMIT
+		};
+		const second = checkedAttempt(parsedBatch.operations.filter(({ id }) => !refusedIds.has(id)), preview);
+		if (second.run === null || second.error !== void 0) {
+			const reported = second.run?.outcome ?? first.outcome;
+			return {
+				outcome: {
+					...reported,
+					applied: [],
+					skipped: inOperationOrder(parsedBatch.operations, [
+						...reported.skipped.filter(({ id }) => !refusedIds.has(id)),
+						...refused,
+						...reported.applied.filter(({ id }) => !refusedIds.has(id)).map(({ id }) => ({
+							id,
+							reason: "invalidResult",
+							message: describeModelError(second.error ?? firstError)
+						}))
+					])
+				},
+				commit: NO_COMMIT
+			};
+		}
+		return {
+			outcome: {
+				...second.run.outcome,
+				skipped: inOperationOrder(parsedBatch.operations, [...second.run.outcome.skipped, ...refused])
+			},
+			commit: second.run.commit
+		};
+	};
+	const preview = () => guardedAttempt(true).outcome;
 	const atomicResult = (previewResult, status) => {
 		const skippedById = new Map(previewResult.skipped.map((operation) => [operation.id, operation]));
 		const skipped = parsedBatch.operations.map(({ id }) => skippedById.get(id) ?? {
@@ -1223,7 +1429,7 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 	};
 	if (parsedBatch.dryRun === true) {
 		const previewResult = preview();
-		if (parsedBatch.atomic === true && previewResult.skipped.length > 0) return atomicResult(previewResult, "previewed");
+		if (isAtomic && previewResult.skipped.length > 0) return atomicResult(previewResult, "previewed");
 		return {
 			version: 1,
 			status: "previewed",
@@ -1240,11 +1446,14 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 			nextRevisionId: previewResult.nextRevisionId
 		};
 	}
-	if (parsedBatch.atomic === true) {
+	if (isAtomic) {
 		const previewResult = preview();
 		if (previewResult.skipped.length > 0) return atomicResult(previewResult, "rejected");
 	}
-	const result = apply({ targetView: view });
+	const guarded = guardedAttempt(false);
+	const result = guarded.outcome;
+	if (isAtomic && result.skipped.some(({ reason }) => reason === "invalidResult")) return atomicResult(result, "rejected");
+	guarded.commit();
 	return {
 		version: 1,
 		status: "committed",

package/dist/docx/altChunk.d.ts

@@ -0,0 +1,8 @@
+//#region src/docx/altChunk.d.ts
+declare const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
+declare const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1000000;
+/** The captured fragment's expanded name, not its source prefix, identifies w:altChunk. */
+declare const isAltChunkMarkup: (xml: string) => boolean;
+declare const getAltChunkRelationshipId: (xml: string) => string | undefined;
+//#endregion
+export { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, ALT_CHUNK_READER_DIAGNOSTIC, getAltChunkRelationshipId, isAltChunkMarkup };

package/dist/docx/altChunk.js

@@ -0,0 +1,17 @@
+import { OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, getAttribute, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+//#region src/docx/altChunk.ts
+const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
+const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1e6;
+const OFFICE_RELATIONSHIPS_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** The captured fragment's expanded name, not its source prefix, identifies w:altChunk. */
+const isAltChunkMarkup = (xml) => {
+	const element = getChildElements(parseXml(xml, OOXML_NAMESPACE_SCOPE)).at(0);
+	return element?.type === "element" && getLocalName(element.name) === "altChunk" && WORDPROCESSINGML_NAMESPACE_URIS.has(element.namespaceUri ?? "");
+};
+const getAltChunkRelationshipId = (xml) => {
+	const element = getChildElements(parseXml(xml, OOXML_NAMESPACE_SCOPE)).at(0);
+	if (element?.type !== "element" || getLocalName(element.name) !== "altChunk" || !WORDPROCESSINGML_NAMESPACE_URIS.has(element.namespaceUri ?? "")) return;
+	return getAttribute(element, OFFICE_RELATIONSHIPS_NAMESPACE_URI, "id") ?? void 0;
+};
+//#endregion
+export { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, ALT_CHUNK_READER_DIAGNOSTIC, getAltChunkRelationshipId, isAltChunkMarkup };

package/dist/docx/archiveInflation.d.ts

@@ -0,0 +1,127 @@
+import JSZip from "jszip";
+//#region src/docx/archiveInflation.d.ts
+declare module "jszip" {
+  interface JSZipObject {
+    /**
+     * Chunked read of the entry content, missing from the published typings.
+     * `nodeStream` is this stream wrapped in a Node.js `Readable`, which
+     * browsers and web workers cannot provide; the stream itself is
+     * platform-neutral.
+     */
+    internalStream(type: "uint8array"): JSZip.JSZipStreamHelper<Uint8Array>;
+  }
+}
+/**
+ * Default ceiling on inflated bytes per compressed byte.
+ *
+ * Document parts in the repository's fixtures stay under 75:1, and parts over a
+ * mebibyte under 15:1. A DEFLATE stream tops out near 1032:1, which is the
+ * shape of an entry made of one repeated byte.
+ */
+declare const DOCX_MAX_COMPRESSION_RATIO = 200;
+/**
+ * Inflated size below which the ratio cap does not apply.
+ *
+ * A small part can compress extremely well without costing anything to hold,
+ * so the ratio only has to bound entries (and packages) large enough to
+ * matter. The byte caps still apply below this size.
+ */
+declare const DOCX_COMPRESSION_RATIO_GRACE_BYTES: number;
+/**
+ * Upper bound on the central-directory records in `bytes`, counted without
+ * parsing the archive and stopping once the count passes `stopAfter`.
+ *
+ * Every record JSZip reads starts with the record signature, so the number of
+ * signature occurrences cannot be lower than the number of entries JSZip would
+ * build, whatever the end-of-central-directory record claims.
+ */
+declare const countCentralDirectoryRecords: (bytes: Uint8Array, stopAfter: number) => number;
+/** Sizes a loaded entry declares in the central directory. */
+type ZipEntrySizes = {
+  readonly compressedBytes: number | null;
+  readonly uncompressedBytes: number | null;
+};
+/** Declared sizes of an entry JSZip loaded from an archive. */
+declare const getZipEntrySizes: (entry: JSZip.JSZipObject) => ZipEntrySizes;
+/**
+ * Whether a loaded entry is stored rather than compressed. A stored entry
+ * reads back exactly the bytes the archive carries, so it cannot expand.
+ */
+declare const isStoredZipEntry: (entry: JSZip.JSZipObject) => boolean;
+/**
+ * Whether the per-entry ratio cap applies to a part. Markup and text parts
+ * never compress anywhere near the cap. Binary parts can: an uncompressed
+ * bitmap of one colour compresses like a run of one byte. Those stay bounded
+ * by the byte caps and the package-wide ratio instead.
+ */
+declare const isRatioBoundedPart: (path: string) => boolean;
+/** The per-entry ratio cap for `path`: `maxRatio`, or none for a binary part. */
+declare const compressionRatioLimitFor: (path: string, maxRatio: number) => number;
+type CompressionRatioCheck = {
+  inflatedBytes: number;
+  compressedBytes: number | null;
+  maxRatio: number;
+};
+/**
+ * Whether `inflatedBytes` produced from `compressedBytes` passes the ratio cap.
+ * Sizes under {@link DOCX_COMPRESSION_RATIO_GRACE_BYTES} never do, and an
+ * unknown compressed size is left to the byte caps.
+ */
+declare const exceedsCompressionRatio: ({ inflatedBytes, compressedBytes, maxRatio }: CompressionRatioCheck) => boolean;
+/**
+ * Inflated bytes charged across one package. `aborted` stops every inflation
+ * sharing the budget at its next chunk, once one of them has failed the
+ * package.
+ */
+type InflationBudget = {
+  readonly maxTotalBytes: number;
+  inflatedBytes: number;
+  aborted: boolean;
+};
+declare const createInflationBudget: (maxTotalBytes: number) => InflationBudget;
+/**
+ * The bound an inflation stopped at.
+ *
+ * - `declared-size` — the entry produced more than its declared size.
+ * - `compression-ratio` — the entry passed the ratio cap for its compressed size.
+ * - `entry` — the entry passed the per-entry cap the caller set.
+ * - `total` — the package passed its cumulative budget.
+ * - `aborted` — another inflation sharing the budget already failed.
+ */
+type InflationLimit = "declared-size" | "compression-ratio" | "entry" | "total" | "aborted";
+type InflateEntryResult = {
+  readonly ok: true;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+} | {
+  readonly ok: false;
+  readonly limit: InflationLimit;
+};
+type InflateEntryOptions = {
+  entry: JSZip.JSZipObject;
+  /** Most bytes this entry may inflate to. */
+  maxEntryBytes: number;
+  /** Ratio cap while streaming; see {@link compressionRatioLimitFor}. */
+  maxCompressionRatio: number;
+  budget: InflationBudget;
+  /**
+   * `false` inflates the entry only to prove it stays within its bounds; the
+   * chunks are dropped and the result carries no bytes. A package part that
+   * is never read here is still inflated by a later save, so the bound has
+   * to be established for it too.
+   */
+  retain?: boolean;
+};
+/**
+ * Inflate one entry chunk by chunk, checking every bound before a chunk is
+ * kept. Pausing the stream abandons the rest of the entry, so a limit bounds
+ * memory rather than reporting an overrun afterwards.
+ *
+ * The budget is charged as chunks arrive, which keeps concurrent inflations
+ * of one package honest, and refunded when this entry stops at a limit or
+ * fails, since none of its bytes are kept. Stream errors (a corrupt entry)
+ * reject; limits resolve with `ok: false` for the caller to map onto its own
+ * error or skip policy.
+ */
+declare const inflateEntryWithinLimits: ({ entry, maxEntryBytes, maxCompressionRatio, budget, retain }: InflateEntryOptions) => Promise<InflateEntryResult>;
+//#endregion
+export { DOCX_COMPRESSION_RATIO_GRACE_BYTES, DOCX_MAX_COMPRESSION_RATIO, InflateEntryOptions, InflateEntryResult, InflationBudget, InflationLimit, ZipEntrySizes, compressionRatioLimitFor, countCentralDirectoryRecords, createInflationBudget, exceedsCompressionRatio, getZipEntrySizes, inflateEntryWithinLimits, isRatioBoundedPart, isStoredZipEntry };