@stll/folio-core 0.7.0 → 0.9.0

package/dist/document-operations.d.ts

@@ -67,19 +67,24 @@ type FolioDocumentOperationIssue = {
   retryable: boolean;
   recovery: FolioDocumentOperationRecovery;
 };
+type FolioDocumentOperationStory = "main" | {
+  type: "header" | "footer";
+  relationshipId: string;
+};
 /** One typed target affected by a successfully applied document operation. */
 type FolioDocumentOperationAffectedTarget = {
   type: "block";
-  story: "main";
+  story: FolioDocumentOperationStory;
   blockId: string;
   effect: "updated" | "deleted" | "commented";
 } | {
   type: "textRange";
   range: FolioAITextRangeHandle;
   effect: "formatted" | "commented";
+  story?: Exclude<FolioDocumentOperationStory, "main">;
 } | {
   type: "insertion";
-  story: "main";
+  story: FolioDocumentOperationStory;
   anchorBlockId: string;
   position: "before" | "after";
   content: "block" | "signatureTable";
@@ -123,6 +128,7 @@ type ApplyFolioDocumentOperationsOptions = {
   view: FolioAIEditView;
   snapshot: FolioAIEditSnapshot;
   batch: FolioDocumentOperationBatch;
+  story?: FolioDocumentOperationStory;
   author?: string;
   createCommentId?: (text: string) => number;
   createUndoHandle?: () => FolioDocumentOperationUndoHandle;
@@ -131,9 +137,10 @@ declare const applyFolioDocumentOperations: ({
   view,
   snapshot,
   batch,
+  story,
   author,
   createCommentId,
   createUndoHandle
 }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
-export { ApplyFolioDocumentOperationsOptions, 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, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationStatus, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { ApplyFolioDocumentOperationsOptions, 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, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -438,54 +438,56 @@ const getFolioDocumentOperationIssues = (operations, skipped) => {
 		};
 	});
 };
-const getPrimaryAffectedTarget = (operation) => {
+const getPrimaryAffectedTarget = (operation, story) => {
 	switch (operation.type) {
 		case "replaceInBlock":
 		case "replaceBlock": return {
 			type: "block",
-			story: "main",
+			story,
 			blockId: operation.blockId,
 			effect: "updated"
 		};
 		case "replaceRange": return {
 			type: "block",
-			story: "main",
+			story,
 			blockId: operation.range.blockId,
 			effect: "updated"
 		};
 		case "commentOnRange": return {
 			type: "textRange",
 			range: operation.range,
-			effect: "commented"
+			effect: "commented",
+			...story !== "main" && { story }
 		};
 		case "formatRange": return {
 			type: "textRange",
 			range: operation.range,
-			effect: "formatted"
+			effect: "formatted",
+			...story !== "main" && { story }
 		};
 		case "insertAfterBlock":
 		case "insertBeforeBlock": return {
 			type: "insertion",
-			story: "main",
+			story,
 			anchorBlockId: operation.blockId,
 			position: operation.type === "insertBeforeBlock" ? "before" : "after",
 			content: "block"
 		};
 		case "deleteBlock": return {
 			type: "block",
-			story: "main",
+			story,
 			blockId: operation.blockId,
 			effect: "deleted"
 		};
 		case "commentOnBlock": return {
 			type: "block",
-			story: "main",
+			story,
 			blockId: operation.blockId,
 			effect: "commented"
 		};
 		case "insertSignatureTable": return {
 			type: "insertion",
-			story: "main",
+			story,
 			anchorBlockId: operation.blockId,
 			position: operation.position ?? "after",
 			content: "signatureTable"
@@ -493,7 +495,12 @@ const getPrimaryAffectedTarget = (operation) => {
 	}
 };
 /** Build deterministic affected-target receipts from operations and their applied entries. */
-const getFolioDocumentOperationReceipts = (operations, applied) => {
+const getFolioDocumentOperationReceipts = (operations, applied) => getFolioDocumentOperationReceiptsForStory({
+	operations,
+	applied,
+	story: "main"
+});
+const getFolioDocumentOperationReceiptsForStory = ({ operations, applied, story }) => {
 	const appliedById = /* @__PURE__ */ new Map();
 	applied.forEach((operation) => {
 		appliedById.set(operation.id, operation);
@@ -502,7 +509,7 @@ const getFolioDocumentOperationReceipts = (operations, applied) => {
 	operations.forEach((operation, operationIndex) => {
 		const appliedOperation = appliedById.get(operation.id);
 		if (!appliedOperation) return;
-		const affected = [getPrimaryAffectedTarget(operation)];
+		const affected = [getPrimaryAffectedTarget(operation, story)];
 		if (appliedOperation.commentId !== void 0) affected.push({
 			type: "comment",
 			commentId: appliedOperation.commentId
@@ -515,7 +522,7 @@ const getFolioDocumentOperationReceipts = (operations, applied) => {
 	});
 	return receipts;
 };
-const applyFolioDocumentOperations = ({ view, snapshot, batch, author, createCommentId, createUndoHandle }) => {
+const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle }) => {
 	const parsedBatch = parseFolioDocumentOperationBatch(batch);
 	const apply = ({ targetView, targetCreateCommentId = createCommentId, preview = false }) => {
 		return (preview ? previewFolioAIEditOperations : applyFolioAIEditOperations)({
@@ -556,7 +563,11 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, author, createCom
 			applied: previewResult.applied.map(({ id }) => ({ id })),
 			skipped: previewResult.skipped,
 			issues: getFolioDocumentOperationIssues(parsedBatch.operations, previewResult.skipped),
-			receipts: getFolioDocumentOperationReceipts(parsedBatch.operations, previewResult.applied),
+			receipts: getFolioDocumentOperationReceiptsForStory({
+				operations: parsedBatch.operations,
+				applied: previewResult.applied,
+				story
+			}),
 			undoHandle: null
 		};
 	}
@@ -570,7 +581,11 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, author, createCom
 		status: "committed",
 		...result,
 		issues: getFolioDocumentOperationIssues(parsedBatch.operations, result.skipped),
-		receipts: getFolioDocumentOperationReceipts(parsedBatch.operations, result.applied),
+		receipts: getFolioDocumentOperationReceiptsForStory({
+			operations: parsedBatch.operations,
+			applied: result.applied,
+			story
+		}),
 		undoHandle: result.applied.length > 0 && createUndoHandle !== void 0 ? createUndoHandle() : null
 	};
 };

package/dist/docx/blockContentParser.js

@@ -3,10 +3,10 @@ import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
+import { convertBulletToUnicode } from "./bulletMarkers.js";
+import { padDecimal } from "./numberingParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { parseTable } from "./tableParser.js";
-import { padDecimal } from "./numberingParser.js";
-import { convertBulletToUnicode } from "./bulletMarkers.js";
 //#region src/docx/blockContentParser.ts
 const toRoman = (numParam) => {
 	let num = numParam;
@@ -49,23 +49,42 @@ const formatNumber = (value, numFmt) => {
 		case "lowerRoman": return toRoman(value).toLowerCase();
 		case "upperRoman": return toRoman(value);
 		case "bullet": return "•";
+		case "none": return "";
 		default: return String(value);
 	}
 };
-const computeListMarker = (paragraph, numbering, listCounters, abstractCounters) => {
+const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList }) => {
 	const listRendering = paragraph.listRendering;
-	if (!listRendering || !numbering) return;
+	if (!listRendering || !numbering) {
+		previousList.abstractNumId = null;
+		previousList.fromStyle = false;
+		previousList.numId = null;
+		return;
+	}
 	const { numId, level } = listRendering;
-	if (numId === 0) return;
-	if (!listCounters.has(numId)) listCounters.set(numId, Array.from({ length: 9 }).fill(NaN));
+	if (numId === 0) {
+		previousList.abstractNumId = null;
+		previousList.fromStyle = false;
+		previousList.numId = null;
+		return;
+	}
+	const firstEncounter = !listCounters.has(numId);
+	if (firstEncounter) listCounters.set(numId, Array.from({ length: 9 }).fill(NaN));
 	const counters = listCounters.get(numId);
 	if (!counters) return;
 	const abstractNumId = numbering.getAbstractNumId(numId);
 	const styleNumbering = paragraph.formatting?.numPrFromStyle;
-	if (abstractNumId !== null && styleNumbering) {
+	let resumedAbstractCounters;
+	const resumesRestartedInstance = firstEncounter && listRendering.startOverride === void 0 && abstractNumId !== null && previousList.abstractNumId === abstractNumId && previousList.numId !== null && previousList.numId !== numId && restartedNumIds.has(previousList.numId);
+	const resumesStyleInstance = firstEncounter && !styleNumbering && listRendering.startOverride === void 0 && abstractNumId !== null && previousList.abstractNumId === abstractNumId && previousList.fromStyle === true;
+	if (abstractNumId !== null && (styleNumbering || resumesRestartedInstance || resumesStyleInstance)) {
 		const latestAbstractCounters = abstractCounters.get(abstractNumId);
-		if (latestAbstractCounters) for (let i = 0; i < counters.length; i += 1) counters[i] = latestAbstractCounters[i] ?? NaN;
+		if (latestAbstractCounters) {
+			for (let i = 0; i < counters.length; i += 1) counters[i] = latestAbstractCounters[i] ?? NaN;
+			resumedAbstractCounters = latestAbstractCounters;
+		}
 	}
+	if (listRendering.startOverride !== void 0 || resumesRestartedInstance || previousList.numId === numId && restartedNumIds.has(numId)) restartedNumIds.add(numId);
 	if (abstractNumId !== null && level > 0) {
 		const latestAbstractCounters = abstractCounters.get(abstractNumId);
 		if (counters.slice(0, level).every(Number.isNaN)) for (let i = 0; i < level; i += 1) {
@@ -81,10 +100,22 @@ const computeListMarker = (paragraph, numbering, listCounters, abstractCounters)
 		const childCounter = counters[level + 1];
 		counters[level + 1] = (childCounter === void 0 || Number.isNaN(childCounter) ? 0 : childCounter) + childAdvances;
 	}
-	if (abstractNumId !== null) abstractCounters.set(abstractNumId, [...counters]);
+	if (abstractNumId !== null) {
+		if (resumedAbstractCounters) for (const [otherNumId, otherCounters] of listCounters) {
+			if (otherNumId === numId || numbering.getAbstractNumId(otherNumId) !== abstractNumId || !otherCounters.every((value, index) => Object.is(value, resumedAbstractCounters[index]))) continue;
+			for (let i = 0; i < otherCounters.length; i += 1) otherCounters[i] = counters[i] ?? NaN;
+		}
+		abstractCounters.set(abstractNumId, [...counters]);
+	}
+	previousList.abstractNumId = abstractNumId;
+	previousList.fromStyle = Boolean(styleNumbering);
+	previousList.numId = numId;
 	const pattern = listRendering.marker;
 	if (listRendering.isBullet) {
 		listRendering.marker = convertBulletToUnicode(pattern || "");
+		previousList.abstractNumId = null;
+		previousList.fromStyle = false;
+		previousList.numId = null;
 		return;
 	}
 	let computedMarker = pattern;
@@ -103,6 +134,12 @@ const computeListMarker = (paragraph, numbering, listCounters, abstractCounters)
 const parseBlockContent = (parent, styles, theme, numbering, rels, media, options) => parseBlockContentWithState(parent, styles, theme, numbering, rels, media, {
 	listCounters: /* @__PURE__ */ new Map(),
 	abstractCounters: /* @__PURE__ */ new Map(),
+	restartedNumIds: /* @__PURE__ */ new Set(),
+	previousList: {
+		abstractNumId: null,
+		fromStyle: false,
+		numId: null
+	},
 	options: {
 		...options,
 		rootXmlns: mergeXmlnsDeclarations(options?.rootXmlns ?? {}, parent)
@@ -118,7 +155,13 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
 			prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
 			enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media);
-			computeListMarker(paragraph, numbering, state.listCounters, state.abstractCounters);
+			computeListMarker(paragraph, {
+				numbering,
+				listCounters: state.listCounters,
+				abstractCounters: state.abstractCounters,
+				restartedNumIds: state.restartedNumIds,
+				previousList: state.previousList
+			});
 			content.push(paragraph);
 			continue;
 		}

package/dist/docx/commentParser.js

@@ -75,7 +75,7 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 	for (const child of children) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "comment") continue;
 		const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
-		const author = getAttribute(child, "w", "author") ?? "Unknown";
+		const author = getAttribute(child, "w", "author")?.trim() || "Unknown";
 		const rawInitials = getAttribute(child, "w", "initials");
 		const initials = rawInitials !== null ? String(rawInitials) : void 0;
 		const rawDate = getAttribute(child, "w", "date");

package/dist/docx/compatibility.d.ts

@@ -2,11 +2,39 @@ import { document_d_exports } from "../types/document.js";
 
 //#region src/docx/compatibility.d.ts
 type DocxCompatibilityReason = "opaqueDrawing";
+type FolioDocxCompatibilityHost = "browser" | "server" | "unknown";
+type FolioDocxCompatibilityProfile = document_d_exports.DocxConformanceClass;
+type DocxCompatibilityContext = {
+  host: FolioDocxCompatibilityHost;
+  profile: FolioDocxCompatibilityProfile;
+};
+type InspectDocxCompatibilityOptions = Partial<DocxCompatibilityContext>;
+type DocxCompatibilityPart = {
+  type: "document";
+} | {
+  type: "header" | "footer";
+  relationshipId: string;
+} | {
+  type: "footnote" | "endnote";
+  id: number;
+};
+type DocxCompatibilityLocation = {
+  part: DocxCompatibilityPart;
+  path: string;
+  blockId?: string;
+};
+type DocxCompatibilityIssue = {
+  code: DocxCompatibilityReason;
+  location: DocxCompatibilityLocation;
+};
 type DocxCompatibility = {
+  schemaVersion: 1;
+  context: DocxCompatibilityContext;
   canSafelyEdit: boolean;
+  issues: DocxCompatibilityIssue[];
   reasons: DocxCompatibilityReason[];
   unsupportedContentCount: number;
 };
-declare function inspectDocxCompatibility(doc: document_d_exports.Document): DocxCompatibility;
+declare const inspectDocxCompatibility: (doc: document_d_exports.Document, options?: InspectDocxCompatibilityOptions) => DocxCompatibility;
 //#endregion
-export { DocxCompatibility, DocxCompatibilityReason, inspectDocxCompatibility };
+export { DocxCompatibility, DocxCompatibilityContext, DocxCompatibilityIssue, DocxCompatibilityLocation, DocxCompatibilityPart, DocxCompatibilityReason, FolioDocxCompatibilityHost, FolioDocxCompatibilityProfile, InspectDocxCompatibilityOptions, inspectDocxCompatibility };

package/dist/docx/compatibility.js

@@ -1,77 +1,156 @@
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/compatibility.ts
-const COMPATIBLE_DOCX = {
-	canSafelyEdit: true,
-	reasons: [],
-	unsupportedContentCount: 0
-};
-function inspectDocxCompatibility(doc) {
+const resolveCompatibilityContext = (doc, options) => ({
+	host: options.host ?? "unknown",
+	profile: options.profile ?? doc.package.conformanceClass ?? DOCX_CONFORMANCE_CLASSES.UNKNOWN
+});
+const inspectDocxCompatibility = (doc, options = {}) => {
+	const context = resolveCompatibilityContext(doc, options);
 	const reasons = /* @__PURE__ */ new Set();
-	let unsupportedContentCount = 0;
-	const record = (reason) => {
-		reasons.add(reason);
-		unsupportedContentCount += 1;
+	const issues = [];
+	const record = (location) => {
+		const code = "opaqueDrawing";
+		reasons.add(code);
+		issues.push({
+			code,
+			location
+		});
 	};
-	inspectBlocks(doc.package.document.content, record);
-	for (const header of doc.package.headers?.values() ?? []) inspectHeaderFooter(header, record);
-	for (const footer of doc.package.footers?.values() ?? []) inspectHeaderFooter(footer, record);
-	for (const footnote of doc.package.footnotes ?? []) inspectBlocks(footnote.content, record);
-	for (const endnote of doc.package.endnotes ?? []) inspectBlocks(endnote.content, record);
-	if (unsupportedContentCount === 0) return COMPATIBLE_DOCX;
+	inspectBlocks(doc.package.document.content, {
+		part: { type: "document" },
+		path: "package.document.content",
+		record
+	});
+	for (const [relationshipId, header] of doc.package.headers?.entries() ?? []) inspectHeaderFooter(header, {
+		part: {
+			type: "header",
+			relationshipId
+		},
+		path: `package.headers.get(${JSON.stringify(relationshipId)}).content`,
+		record
+	});
+	for (const [relationshipId, footer] of doc.package.footers?.entries() ?? []) inspectHeaderFooter(footer, {
+		part: {
+			type: "footer",
+			relationshipId
+		},
+		path: `package.footers.get(${JSON.stringify(relationshipId)}).content`,
+		record
+	});
+	for (const footnote of doc.package.footnotes ?? []) inspectBlocks(footnote.content, {
+		part: {
+			type: "footnote",
+			id: footnote.id
+		},
+		path: `package.footnotes[id=${footnote.id}].content`,
+		record
+	});
+	for (const endnote of doc.package.endnotes ?? []) inspectBlocks(endnote.content, {
+		part: {
+			type: "endnote",
+			id: endnote.id
+		},
+		path: `package.endnotes[id=${endnote.id}].content`,
+		record
+	});
 	return {
-		canSafelyEdit: false,
+		schemaVersion: 1,
+		context,
+		canSafelyEdit: issues.length === 0,
+		issues,
 		reasons: Array.from(reasons),
-		unsupportedContentCount
+		unsupportedContentCount: issues.length
 	};
-}
-function inspectBlocks(blocks, record) {
-	for (const block of blocks) {
+};
+function inspectBlocks(blocks, context) {
+	for (const [blockIndex, block] of blocks.entries()) {
+		const blockPath = `${context.path}[${blockIndex}]`;
 		if (block.type === "paragraph") {
-			inspectParagraphContent(block.content, record);
+			inspectParagraphContent(block.content, {
+				...block.paraId === void 0 ? {} : { blockId: block.paraId },
+				part: context.part,
+				path: `${blockPath}.content`,
+				record: context.record
+			});
 			continue;
 		}
 		if (block.type === "table") {
-			for (const row of block.rows) for (const cell of row.cells) inspectBlocks(cell.content, record);
+			for (const [rowIndex, row] of block.rows.entries()) for (const [cellIndex, cell] of row.cells.entries()) inspectBlocks(cell.content, {
+				part: context.part,
+				path: `${blockPath}.rows[${rowIndex}].cells[${cellIndex}].content`,
+				record: context.record
+			});
 			continue;
 		}
-		inspectBlocks(block.content, record);
+		inspectBlocks(block.content, {
+			part: context.part,
+			path: `${blockPath}.content`,
+			record: context.record
+		});
 	}
 }
-function inspectHeaderFooter(headerFooter, record) {
-	inspectBlocks(headerFooter.content, record);
+function inspectHeaderFooter(headerFooter, context) {
+	inspectBlocks(headerFooter.content, context);
 }
-function inspectParagraphContent(content, record) {
-	for (const item of content) {
+function inspectParagraphContent(content, context) {
+	for (const [itemIndex, item] of content.entries()) {
+		const itemContext = {
+			...context,
+			path: `${context.path}[${itemIndex}]`
+		};
 		if (item.type === "run") {
-			inspectRun(item, record);
+			inspectRun(item, itemContext);
 			continue;
 		}
 		if (item.type === "hyperlink") {
-			inspectHyperlink(item, record);
+			inspectHyperlink(item, itemContext);
 			continue;
 		}
 		if (item.type === "inlineSdt") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "simpleField") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "complexField") {
-			for (const run of item.fieldCode) inspectRun(run, record);
-			for (const run of item.fieldResult) inspectRun(run, record);
+			for (const [runIndex, run] of item.fieldCode.entries()) inspectRun(run, {
+				...itemContext,
+				path: `${itemContext.path}.fieldCode[${runIndex}]`
+			});
+			for (const [runIndex, run] of item.fieldResult.entries()) inspectRun(run, {
+				...itemContext,
+				path: `${itemContext.path}.fieldResult[${runIndex}]`
+			});
 		}
 	}
 }
-function inspectHyperlink(hyperlink, record) {
-	for (const child of hyperlink.children) if (child.type === "run") inspectRun(child, record);
+function inspectHyperlink(hyperlink, context) {
+	for (const [childIndex, child] of hyperlink.children.entries()) if (child.type === "run") inspectRun(child, {
+		...context,
+		path: `${context.path}.children[${childIndex}]`
+	});
 }
-function inspectRun(run, record) {
-	for (const content of run.content) if (content.type === "drawing" && content.rawXml) record("opaqueDrawing");
+function inspectRun(run, context) {
+	for (const [contentIndex, content] of run.content.entries()) if (content.type === "drawing" && content.rawXml) context.record({
+		...context.blockId === void 0 ? {} : { blockId: context.blockId },
+		part: context.part,
+		path: `${context.path}.content[${contentIndex}]`
+	});
 }
 //#endregion
 export { inspectDocxCompatibility };

package/dist/docx/conformance.d.ts

@@ -0,0 +1,6 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/conformance.d.ts
+declare const detectDocxConformanceClass: (documentXml: string | null) => document_d_exports.DocxConformanceClass;
+//#endregion
+export { detectDocxConformanceClass };

package/dist/docx/conformance.js

@@ -0,0 +1,18 @@
+import { getLocalName, getNamespacePrefix, parseXmlDocument } from "./xmlParser.js";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+//#region src/docx/conformance.ts
+const STRICT_MAIN_NAMESPACE = "http://purl.oclc.org/ooxml/wordprocessingml/main";
+const TRANSITIONAL_MAIN_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const detectDocxConformanceClass = (documentXml) => {
+	if (documentXml === null) return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+	const root = parseXmlDocument(documentXml);
+	if (root === null || getLocalName(root.name ?? "") !== "document") return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+	const prefix = getNamespacePrefix(root.name ?? "");
+	const namespaceAttribute = prefix === null ? "xmlns" : `xmlns:${prefix}`;
+	const namespace = root.attributes?.[namespaceAttribute];
+	if (namespace === STRICT_MAIN_NAMESPACE) return DOCX_CONFORMANCE_CLASSES.STRICT;
+	if (namespace === TRANSITIONAL_MAIN_NAMESPACE) return DOCX_CONFORMANCE_CLASSES.TRANSITIONAL;
+	return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+};
+//#endregion
+export { detectDocxConformanceClass };

package/dist/docx/encryption/agileDecryption.js

@@ -1,5 +1,5 @@
-import { bytesEqual, joinBytes, padToBlock, passwordToUtf16Le, toArrayBuffer, writeUint32Le } from "./cryptoBytes.js";
 import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+import { bytesEqual, joinBytes, padToBlock, passwordToUtf16Le, toArrayBuffer, writeUint32Le } from "./cryptoBytes.js";
 //#region src/docx/encryption/agileDecryption.ts
 /**
 * Agile Encryption decryption (Office 2010+) using Web Crypto.

package/dist/docx/encryption/encryptionInfo.js

@@ -1,5 +1,5 @@
-import { decodeBase64 } from "./cryptoBytes.js";
 import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+import { decodeBase64 } from "./cryptoBytes.js";
 //#region src/docx/encryption/encryptionInfo.ts
 /**
 * Parse the EncryptionInfo stream for Agile Encryption (Office 2010+).

package/dist/docx/encryption/openEncryptedDocx.js

@@ -1,5 +1,5 @@
-import { toArrayBuffer } from "./cryptoBytes.js";
 import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+import { toArrayBuffer } from "./cryptoBytes.js";
 import { decryptAgileEncryptedPackage } from "./agileDecryption.js";
 import { readEncryptedPackageStreams } from "./compoundFile.js";
 import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./containerFormat.js";

package/dist/docx/ensureParaIds.d.ts

@@ -0,0 +1,29 @@
+//#region src/docx/ensureParaIds.d.ts
+declare const EnsureParaIdsError_base: import("better-result").TaggedErrorClass<"EnsureParaIdsError", {
+  message: string;
+  cause?: unknown;
+}>;
+/** A malformed or unsupported package prevented paragraph-ID normalization. */
+declare class EnsureParaIdsError extends EnsureParaIdsError_base {}
+/** Counts and normalized bytes returned by {@link ensureParaIds}. */
+type EnsureParaIdsResult = {
+  /** The normalized `.docx`; the input bytes verbatim when `alreadyComplete`. */docx: Uint8Array; /** Paragraphs that received a paraId (missing or all-zero before). */
+  assigned: number; /** Duplicate paraIds reassigned (the first occurrence keeps the id). */
+  deduplicated: number; /** True when the input already had full, unique coverage. */
+  alreadyComplete: boolean;
+};
+/** Controls mutation of package metadata that has security implications. */
+type EnsureParaIdsOptions = {
+  /**
+   * Allow normalization to invalidate existing OPC digital signatures.
+   * Callers must warn the user before opting in.
+   */
+  allowSignedPackageMutation?: boolean;
+};
+/**
+ * Backfill `w14:paraId` on every paragraph of a `.docx` buffer. All package,
+ * XML, and compression failures are surfaced as {@link EnsureParaIdsError}.
+ */
+declare const ensureParaIds: (docx: Uint8Array | ArrayBuffer, options?: EnsureParaIdsOptions) => Promise<EnsureParaIdsResult>;
+//#endregion
+export { EnsureParaIdsError, EnsureParaIdsOptions, EnsureParaIdsResult, ensureParaIds };