@stll/folio-core 0.37.1 → 0.37.3

package/dist/docx/paragraphPropertySource.js

@@ -1,27 +1,151 @@
 import { visitDocxParagraphs } from "./paragraphTraversal.js";
-import { panic } from "better-result";
+import { TaggedError, panic } from "better-result";
+import { PluginKey } from "prosemirror-state";
 //#region src/docx/paragraphPropertySource.ts
 const paragraphPropertySources = /* @__PURE__ */ new WeakMap();
 const paragraphPropertySourceOwners = /* @__PURE__ */ new WeakMap();
 const proseParagraphSourceOwners = /* @__PURE__ */ new WeakMap();
 const paragraphPropertySourceCandidates = /* @__PURE__ */ new WeakMap();
 const paragraphPropertySourceTransferIds = /* @__PURE__ */ new WeakMap();
+const paragraphPropertySourceTokens = /* @__PURE__ */ new WeakMap();
+const documentParagraphPropertySourceBindingBrand = Symbol("documentParagraphPropertySourceBinding");
+const documentParagraphPropertySourceBinding = Symbol("paragraphPropertySourceBinding");
+const PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR = "_docxParagraphSourceToken";
+const PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR = "_docxParagraphSourceContract";
+/** Durable identity nested inside opaque collapsed-cell ProseMirror attrs; stripped on restore. */
+const TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR = "_docxParagraphSourceBinding";
+const PARAGRAPH_SOURCE_TOKEN_VERSION = "folio-ppr-v1";
+const PARAGRAPH_SOURCE_TOKEN_PREFIX = "p1d";
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const SOURCE_TOKEN = /^p1d:([0-9a-f]{32}):(0|[1-9a-z][0-9a-z]*)$/;
+const PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES = [
+	"contract_mismatch",
+	"duplicate_token",
+	"invalid_token",
+	"unknown_token"
+];
+const TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS = [
+	"complexity_limit",
+	"cyclic_or_aliased_graph",
+	"depth_limit",
+	"expected_array",
+	"expected_block",
+	"expected_cell",
+	"expected_inline_content",
+	"expected_paragraph",
+	"expected_record",
+	"expected_row",
+	"invalid_binding",
+	"invalid_block_type",
+	"invalid_cell_type",
+	"invalid_graph_value",
+	"invalid_inline_content_type",
+	"invalid_paragraph_type",
+	"invalid_row_type",
+	"malformed_source_token"
+];
+var ParagraphPropertySourceValidationError = class extends TaggedError("ParagraphPropertySourceValidationError") {};
+const contractForDigest = (sourceDigest) => {
+	if (!SHA256_HEX.test(sourceDigest)) panic("Paragraph-property source digest must be lowercase SHA-256 hex");
+	return `${PARAGRAPH_SOURCE_TOKEN_VERSION}:${sourceDigest}`;
+};
+const fingerprintFromContract = (contract) => {
+	const prefix = `${PARAGRAPH_SOURCE_TOKEN_VERSION}:`;
+	const digest = contract.startsWith(prefix) ? contract.slice(prefix.length) : "";
+	return SHA256_HEX.test(digest) ? digest.slice(0, 32) : null;
+};
+const tokenForOrdinal = (contract, ordinal) => {
+	const fingerprint = fingerprintFromContract(contract);
+	if (!fingerprint) panic("Cannot mint a paragraph-property token for an invalid source contract");
+	return `${PARAGRAPH_SOURCE_TOKEN_PREFIX}:${fingerprint}:${ordinal.toString(36)}`;
+};
+const isDocumentParagraphPropertySourceBinding = (value) => typeof value === "object" && value !== null && documentParagraphPropertySourceBindingBrand in value && value[documentParagraphPropertySourceBindingBrand] === true && "contract" in value && typeof value.contract === "string" && "sourceOwners" in value && value.sourceOwners instanceof Set && "sources" in value && value.sources instanceof Map;
+const setDocumentParagraphPropertySourceBinding = (document, binding) => {
+	if (!fingerprintFromContract(binding.contract)) panic("Cannot attach an invalid paragraph-property source contract");
+	if ((Object.hasOwn(document, documentParagraphPropertySourceBinding) ? Reflect.get(document, documentParagraphPropertySourceBinding) : void 0) === binding) return;
+	if (!Reflect.defineProperty(document, documentParagraphPropertySourceBinding, {
+		enumerable: true,
+		value: binding
+	})) panic("Cannot attach the paragraph-property source contract to the document");
+};
+const isParagraphPropertySourceToken = (token) => typeof token === "string" && SOURCE_TOKEN.test(token);
+/** True only for a body-story token derived from the exact source contract. */
+const paragraphPropertySourceTokenMatchesContract = (token, contract) => {
+	if (!isParagraphPropertySourceToken(token)) return false;
+	const match = SOURCE_TOKEN.exec(token);
+	const fingerprint = fingerprintFromContract(contract);
+	return match !== null && fingerprint !== null && match[1] === fingerprint;
+};
+/** Visit the v1 provenance scope in canonical OOXML body-story order. */
+const visitDocumentStoryParagraphs = (content, visit) => {
+	visitDocxParagraphs({ documentBody: { content } }, visit);
+};
 const assignParagraphPropertySource = (paragraph, source) => {
 	paragraphPropertySources.set(paragraph, source);
 	paragraphPropertySourceOwners.set(paragraph, paragraph);
 };
 const getParagraphPropertySource = (paragraph) => paragraphPropertySources.get(paragraph);
-const copyParagraphPropertySource = (target, source) => {
+/** Copy the captured `w:pPr` without claiming the source paragraph's durable identity. */
+const copyParagraphPropertyCapture = (target, source) => {
 	const propertySource = paragraphPropertySources.get(source);
 	if (propertySource) {
 		paragraphPropertySources.set(target, { ...propertySource });
 		paragraphPropertySourceOwners.set(target, paragraphPropertySourceOwners.get(source) ?? source);
 	}
+};
+const copyParagraphPropertySource = (target, source) => {
+	copyParagraphPropertyCapture(target, source);
 	const transferId = paragraphPropertySourceTransferIds.get(source);
 	if (transferId) paragraphPropertySourceTransferIds.set(target, transferId);
 	const candidate = paragraphPropertySourceCandidates.get(source);
 	if (candidate) paragraphPropertySourceCandidates.set(target, candidate);
+	const token = paragraphPropertySourceTokens.get(source);
+	if (token) paragraphPropertySourceTokens.set(target, token);
 };
+/** Bind parsed body paragraphs to one exact source package. */
+const assignDocumentParagraphPropertySourceContract = (document, sourceDigest) => {
+	const contract = contractForDigest(sourceDigest);
+	const sources = /* @__PURE__ */ new Map();
+	let ordinal = 0;
+	visitDocumentStoryParagraphs(document.package.document.content, (paragraph) => {
+		const token = tokenForOrdinal(contract, ordinal);
+		paragraphPropertySourceTokens.set(paragraph, token);
+		sources.set(token, paragraph);
+		ordinal += 1;
+	});
+	setDocumentParagraphPropertySourceBinding(document, Object.freeze({
+		[documentParagraphPropertySourceBindingBrand]: true,
+		contract,
+		sourceOwners: new Set(sources.values()),
+		sources
+	}));
+};
+const getDocumentParagraphPropertySourceBinding = (document) => {
+	if (!Object.hasOwn(document, documentParagraphPropertySourceBinding)) return;
+	const binding = Reflect.get(document, documentParagraphPropertySourceBinding);
+	if (!isDocumentParagraphPropertySourceBinding(binding) || !fingerprintFromContract(binding.contract)) panic("The document carries an invalid paragraph-property source contract");
+	return binding;
+};
+const getDocumentParagraphPropertySourceContract = (document) => getDocumentParagraphPropertySourceBinding(document)?.contract;
+const copyDocumentParagraphPropertySources = (document) => {
+	const sources = getDocumentParagraphPropertySourceBinding(document)?.sources;
+	return sources ? new Map(sources) : void 0;
+};
+const paragraphPropertySourceBelongsToDocument = (paragraph, document) => {
+	const owner = paragraphPropertySourceOwners.get(paragraph);
+	const binding = getDocumentParagraphPropertySourceBinding(document);
+	return owner !== void 0 && binding !== void 0 && binding.sourceOwners.has(owner);
+};
+const getProseDocumentParagraphPropertySourceContract = (document) => {
+	const contract = document.attrs[PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR];
+	return typeof contract === "string" && fingerprintFromContract(contract) ? contract : null;
+};
+const getProseParagraphPropertySourceToken = (paragraph) => paragraph.attrs[PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR];
+const copyDocumentParagraphPropertySourceContract = (target, source) => {
+	const binding = getDocumentParagraphPropertySourceBinding(source);
+	if (binding) setDocumentParagraphPropertySourceBinding(target, binding);
+};
+const getParagraphPropertySourceToken = (paragraph) => paragraphPropertySourceTokens.get(paragraph);
 /** Clone a paragraph while deliberately retaining its parsed `w:pPr` owner. */
 const cloneParagraphWithPropertySource = (paragraph, overrides) => {
 	const cloned = {
@@ -62,11 +186,436 @@ const cloneDocumentWithParagraphPropertySources = (document) => {
 		if (!target) panic("The cloned document lost a paragraph owner.");
 		copyParagraphPropertySource(target, source);
 	}
+	copyDocumentParagraphPropertySourceContract(cloned, document);
+	return cloned;
+};
+const paragraphsInTableCells = (cells) => {
+	const paragraphs = [];
+	for (const cell of cells) visitDocxParagraphs({ documentBody: { content: cell.content } }, (paragraph) => paragraphs.push(paragraph));
+	return paragraphs;
+};
+const isPropertySourceBindingRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const inspectTableCellParagraphPropertySourceBinding = (paragraph) => {
+	if (!Object.hasOwn(paragraph, "_docxParagraphSourceBinding")) return { status: "absent" };
+	const value = Reflect.get(paragraph, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR);
+	if (!isPropertySourceBindingRecord(value)) return { status: "invalid" };
+	const keys = Reflect.ownKeys(value);
+	if (keys.length === 1 && keys[0] === "type" && Object.hasOwn(value, "type") && value["type"] === "authored") return {
+		binding: { type: "authored" },
+		status: "authored"
+	};
+	if (keys.length === 2 && keys.includes("type") && keys.includes("token") && Object.hasOwn(value, "type") && value["type"] === "source" && Object.hasOwn(value, "token") && typeof value["token"] === "string") return {
+		binding: {
+			token: value["token"],
+			type: "source"
+		},
+		status: "source"
+	};
+	return { status: "invalid" };
+};
+const TABLE_CELL_PARAGRAPH_SOURCE_MAX_DEPTH = 128;
+const TABLE_CELL_PARAGRAPH_SOURCE_MAX_VALUES = 1e5;
+const ARRAY_INDEX = /^(?:0|[1-9][0-9]*)$/;
+const tableCellParagraphSourcePayloadMessages = {
+	complexity_limit: "The hidden table-cell payload exceeds its complexity limit.",
+	cyclic_or_aliased_graph: "The hidden table-cell payload contains a cyclic or aliased graph.",
+	depth_limit: "The hidden table-cell payload exceeds its nesting limit.",
+	expected_array: "The hidden table-cell payload field must be an array.",
+	expected_block: "The hidden table-cell payload contains a malformed block.",
+	expected_cell: "The hidden table-cell payload contains a malformed cell.",
+	expected_inline_content: "The hidden table-cell payload contains malformed inline content.",
+	expected_paragraph: "The hidden table-cell payload contains a malformed paragraph.",
+	expected_record: "The hidden table-cell payload contains a malformed object.",
+	expected_row: "The hidden table-cell payload contains a malformed row.",
+	invalid_binding: "A hidden table-cell paragraph has an invalid source binding.",
+	invalid_block_type: "The hidden table-cell payload contains an unsupported block type.",
+	invalid_cell_type: "The hidden table-cell payload contains an invalid cell type.",
+	invalid_graph_value: "The hidden table-cell payload contains an invalid graph value.",
+	invalid_inline_content_type: "The hidden table-cell payload contains an unsupported inline content type.",
+	invalid_paragraph_type: "The hidden table-cell payload contains an invalid paragraph type.",
+	invalid_row_type: "The hidden table-cell payload contains an invalid row type.",
+	malformed_source_token: "A hidden table-cell paragraph has a malformed source token."
+};
+const tableCellParagraphSourceValidationErrors = /* @__PURE__ */ new WeakSet();
+const invalidTableCellParagraphSourcePayload = (classification, path) => {
+	const error = new ParagraphPropertySourceValidationError({
+		code: "invalid_token",
+		classification,
+		message: tableCellParagraphSourcePayloadMessages[classification],
+		path
+	});
+	tableCellParagraphSourceValidationErrors.add(error);
+	throw error;
+};
+const tableCellBlockTraversalByType = {
+	blockSdt: "blockSdt",
+	paragraph: "paragraph",
+	table: "table"
+};
+const tableCellParagraphContentTraversalByType = {
+	bookmarkEnd: "leaf",
+	bookmarkStart: "leaf",
+	commentRangeEnd: "leaf",
+	commentRangeStart: "leaf",
+	commentReference: "leaf",
+	complexField: "complexField",
+	deletion: "content",
+	hyperlink: "children",
+	inlineSdt: "content",
+	insertion: "content",
+	mathEquation: "leaf",
+	moveFrom: "content",
+	moveFromRangeEnd: "leaf",
+	moveFromRangeStart: "leaf",
+	moveTo: "content",
+	moveToRangeEnd: "leaf",
+	moveToRangeStart: "leaf",
+	run: "run",
+	simpleField: "content"
+};
+const tableCellRunContentTraversalByType = {
+	break: "leaf",
+	drawing: "leaf",
+	endnoteRef: "leaf",
+	fieldChar: "leaf",
+	footnoteRef: "leaf",
+	instrText: "leaf",
+	noBreakHyphen: "leaf",
+	renderedPageBreak: "leaf",
+	shape: "shape",
+	softHyphen: "leaf",
+	symbol: "leaf",
+	tab: "leaf",
+	text: "leaf"
+};
+const isTableCellBlockContentType = (value) => typeof value === "string" && Object.hasOwn(tableCellBlockTraversalByType, value);
+const isTableCellParagraphContentType = (value) => typeof value === "string" && Object.hasOwn(tableCellParagraphContentTraversalByType, value);
+const isTableCellRunContentType = (value) => typeof value === "string" && Object.hasOwn(tableCellRunContentTraversalByType, value);
+const inspectTableCellParagraphSourceGraph = (value, path, depth, context) => {
+	if (depth > TABLE_CELL_PARAGRAPH_SOURCE_MAX_DEPTH) invalidTableCellParagraphSourcePayload("depth_limit", path);
+	context.values += 1;
+	if (context.values > TABLE_CELL_PARAGRAPH_SOURCE_MAX_VALUES) invalidTableCellParagraphSourcePayload("complexity_limit", path);
+	if (value === null || value === void 0 || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return;
+	if (typeof value !== "object") return invalidTableCellParagraphSourcePayload("invalid_graph_value", path);
+	if (context.seen.has(value)) return invalidTableCellParagraphSourcePayload("cyclic_or_aliased_graph", path);
+	context.seen.add(value);
+	context.objects.push(value);
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return invalidTableCellParagraphSourcePayload("invalid_graph_value", path);
+	for (const key of Reflect.ownKeys(value)) {
+		if (Array.isArray(value) && key === "length") {
+			if (value.length > TABLE_CELL_PARAGRAPH_SOURCE_MAX_VALUES) invalidTableCellParagraphSourcePayload("complexity_limit", path);
+			continue;
+		}
+		let childPath = `${path}.*`;
+		if (Array.isArray(value)) {
+			if (typeof key !== "string" || !ARRAY_INDEX.test(key)) return invalidTableCellParagraphSourcePayload("invalid_graph_value", `${path}[*]`);
+			childPath = `${path}[${key}]`;
+		}
+		if (typeof key !== "string") return invalidTableCellParagraphSourcePayload("invalid_graph_value", childPath);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (descriptor === void 0 || !descriptor.enumerable || !("value" in descriptor)) return invalidTableCellParagraphSourcePayload("invalid_graph_value", childPath);
+		inspectTableCellParagraphSourceGraph(descriptor.value, childPath, depth + 1, context);
+	}
+};
+const tableCellParagraphSourceArray = (value, path) => {
+	if (!Array.isArray(value)) return invalidTableCellParagraphSourcePayload("expected_array", path);
+	return value;
+};
+const tableCellParagraphSourceRecord = (value, path, classification) => {
+	if (!isPropertySourceBindingRecord(value)) return invalidTableCellParagraphSourcePayload(classification, path);
+	return value;
+};
+const isDecodedTableCellParagraph = (value) => isPropertySourceBindingRecord(value) && value["type"] === "paragraph" && Array.isArray(value["content"]);
+const isDecodedTableCell = (value) => isPropertySourceBindingRecord(value) && value["type"] === "tableCell" && Array.isArray(value["content"]);
+const visitDecodedTableCellRunContent = (value, path, context) => {
+	const content = tableCellParagraphSourceRecord(value, path, "expected_inline_content");
+	const contentType = content["type"];
+	if (!isTableCellRunContentType(contentType)) return invalidTableCellParagraphSourcePayload("invalid_inline_content_type", path);
+	const traversal = tableCellRunContentTraversalByType[contentType];
+	switch (traversal) {
+		case "shape": {
+			const shapePath = `${path}.shape`;
+			const rawTextBody = tableCellParagraphSourceRecord(content["shape"], shapePath, "expected_record")["textBody"];
+			if (rawTextBody === void 0 || rawTextBody === null) return;
+			const textBodyPath = `${shapePath}.textBody`;
+			const textBody = tableCellParagraphSourceRecord(rawTextBody, textBodyPath, "expected_record");
+			const blocks = tableCellParagraphSourceArray(textBody["content"], `${textBodyPath}.content`);
+			for (const [index, block] of blocks.entries()) visitDecodedTableCellBlock(block, `${textBodyPath}.content[${index}]`, context);
+			return;
+		}
+		case "leaf": return;
+		default: return traversal;
+	}
+};
+const visitDecodedTableCellRun = (run, path, context) => {
+	const content = tableCellParagraphSourceArray(run["content"], `${path}.content`);
+	for (const [index, item] of content.entries()) visitDecodedTableCellRunContent(item, `${path}.content[${index}]`, context);
+};
+const visitDecodedTableCellInlineContent = (value, path, context) => {
+	const content = tableCellParagraphSourceRecord(value, path, "expected_inline_content");
+	const contentType = content["type"];
+	if (!isTableCellParagraphContentType(contentType)) return invalidTableCellParagraphSourcePayload("invalid_inline_content_type", path);
+	const traversal = tableCellParagraphContentTraversalByType[contentType];
+	switch (traversal) {
+		case "run":
+			visitDecodedTableCellRun(content, path, context);
+			return;
+		case "children": {
+			const children = tableCellParagraphSourceArray(content["children"], `${path}.children`);
+			for (const [index, child] of children.entries()) visitDecodedTableCellInlineContent(child, `${path}.children[${index}]`, context);
+			return;
+		}
+		case "content": {
+			const children = tableCellParagraphSourceArray(content["content"], `${path}.content`);
+			for (const [index, child] of children.entries()) visitDecodedTableCellInlineContent(child, `${path}.content[${index}]`, context);
+			return;
+		}
+		case "complexField":
+			for (const field of ["fieldCode", "fieldResult"]) {
+				const runs = tableCellParagraphSourceArray(content[field], `${path}.${field}`);
+				for (const [index, runValue] of runs.entries()) {
+					const runPath = `${path}.${field}[${index}]`;
+					const run = tableCellParagraphSourceRecord(runValue, runPath, "expected_inline_content");
+					if (run["type"] !== "run") return invalidTableCellParagraphSourcePayload("invalid_inline_content_type", runPath);
+					visitDecodedTableCellRun(run, runPath, context);
+				}
+			}
+			return;
+		case "leaf": return;
+		default: return traversal;
+	}
+};
+const visitDecodedTableCellParagraph = (paragraph, path, context) => {
+	if (paragraph["type"] !== "paragraph") return invalidTableCellParagraphSourcePayload("invalid_paragraph_type", path);
+	if (!isDecodedTableCellParagraph(paragraph)) return invalidTableCellParagraphSourcePayload("expected_paragraph", path);
+	const inspection = inspectTableCellParagraphPropertySourceBinding(paragraph);
+	switch (inspection.status) {
+		case "authored":
+		case "source":
+			if (inspection.status === "source" && !isParagraphPropertySourceToken(inspection.binding.token)) invalidTableCellParagraphSourcePayload("malformed_source_token", `${path}.${TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR}.token`);
+			context.paragraphs.push({
+				binding: inspection.binding,
+				paragraph,
+				path
+			});
+			break;
+		case "absent":
+		case "invalid": return invalidTableCellParagraphSourcePayload("invalid_binding", `${path}.${TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR}`);
+		default: return inspection;
+	}
+	const content = tableCellParagraphSourceArray(paragraph.content, `${path}.content`);
+	for (const [index, item] of content.entries()) visitDecodedTableCellInlineContent(item, `${path}.content[${index}]`, context);
+};
+const visitDecodedTableCell = (value, path, context) => {
+	const cell = tableCellParagraphSourceRecord(value, path, "expected_cell");
+	if (cell["type"] !== "tableCell") return invalidTableCellParagraphSourcePayload("invalid_cell_type", path);
+	const content = tableCellParagraphSourceArray(cell["content"], `${path}.content`);
+	for (const [index, block] of content.entries()) visitDecodedTableCellBlock(block, `${path}.content[${index}]`, context);
+	if (!isDecodedTableCell(cell)) return invalidTableCellParagraphSourcePayload("expected_cell", path);
+	return cell;
+};
+const visitDecodedTableCellRow = (value, path, context) => {
+	const row = tableCellParagraphSourceRecord(value, path, "expected_row");
+	if (row["type"] !== "tableRow") return invalidTableCellParagraphSourcePayload("invalid_row_type", path);
+	const cells = tableCellParagraphSourceArray(row["cells"], `${path}.cells`);
+	for (const [index, cell] of cells.entries()) visitDecodedTableCell(cell, `${path}.cells[${index}]`, context);
+};
+function visitDecodedTableCellBlock(value, path, context) {
+	const block = tableCellParagraphSourceRecord(value, path, "expected_block");
+	const blockType = block["type"];
+	if (!isTableCellBlockContentType(blockType)) return invalidTableCellParagraphSourcePayload("invalid_block_type", path);
+	const traversal = tableCellBlockTraversalByType[blockType];
+	switch (traversal) {
+		case "paragraph":
+			visitDecodedTableCellParagraph(block, path, context);
+			return;
+		case "table": {
+			const rows = tableCellParagraphSourceArray(block["rows"], `${path}.rows`);
+			for (const [index, row] of rows.entries()) visitDecodedTableCellRow(row, `${path}.rows[${index}]`, context);
+			return;
+		}
+		case "blockSdt": {
+			const content = tableCellParagraphSourceArray(block["content"], `${path}.content`);
+			for (const [index, child] of content.entries()) visitDecodedTableCellBlock(child, `${path}.content[${index}]`, context);
+			return;
+		}
+		default: return traversal;
+	}
+}
+const decodedTableCellParagraphSourcePayloadBrand = Symbol("decodedTableCellParagraphSourcePayload");
+const decodedTableCellParagraphSourcePayloadStates = /* @__PURE__ */ new WeakMap();
+const decodedTableCellParagraphSourcePayloads = /* @__PURE__ */ new WeakMap();
+const decodedTableCellParagraphSourcePayloadState = (payload) => {
+	const state = decodedTableCellParagraphSourcePayloadStates.get(payload);
+	if (!state) panic("A collapsed-cell paragraph source payload bypassed its decoder.");
+	return state;
+};
+const decodeTableCellParagraphSourcePayloadUnchecked = (value) => {
+	const graphContext = {
+		objects: [],
+		seen: /* @__PURE__ */ new WeakSet(),
+		values: 0
+	};
+	inspectTableCellParagraphSourceGraph(value, "continuationCells", 0, graphContext);
+	const context = { paragraphs: [] };
+	const rawCells = tableCellParagraphSourceArray(value, "continuationCells");
+	const cells = [];
+	for (const [index, rawCell] of rawCells.entries()) cells.push(visitDecodedTableCell(rawCell, `continuationCells[${index}]`, context));
+	let object = graphContext.objects.pop();
+	while (object) {
+		Object.freeze(object);
+		object = graphContext.objects.pop();
+	}
+	const payload = Object.freeze({
+		[decodedTableCellParagraphSourcePayloadBrand]: true,
+		cells: Object.freeze(cells)
+	});
+	decodedTableCellParagraphSourcePayloadStates.set(payload, Object.freeze({ paragraphs: Object.freeze(context.paragraphs.map((entry) => Object.freeze(entry))) }));
+	decodedTableCellParagraphSourcePayloads.set(payload.cells, payload);
+	return payload;
+};
+/** Decode and freeze the opaque collapsed-cell wire payload before typed use. */
+const decodeTableCellParagraphSourcePayload = (value) => {
+	if (typeof value === "object" && value !== null) {
+		const decoded = decodedTableCellParagraphSourcePayloads.get(value);
+		if (decoded) return decoded;
+	}
+	try {
+		const decoded = decodeTableCellParagraphSourcePayloadUnchecked(value);
+		if (typeof value === "object" && value !== null) decodedTableCellParagraphSourcePayloads.set(value, decoded);
+		return decoded;
+	} catch (error) {
+		if (error instanceof ParagraphPropertySourceValidationError && tableCellParagraphSourceValidationErrors.has(error)) throw error;
+		return invalidTableCellParagraphSourcePayload("invalid_graph_value", "continuationCells");
+	}
+};
+const setTableCellParagraphPropertySourceBinding = (paragraph, binding) => {
+	if (!Reflect.set(paragraph, "_docxParagraphSourceBinding", Object.freeze(binding))) panic("Cannot attach paragraph-property transport identity to a table cell.");
+};
+const tableCellParagraphPropertySourceBindingForTransport = (paragraph, inspection) => {
+	const directToken = paragraphPropertySourceTokens.get(paragraph);
+	if (directToken !== void 0) {
+		if (!isParagraphPropertySourceToken(directToken)) panic("Cannot transport a malformed private paragraph-property source token.");
+		switch (inspection.status) {
+			case "absent": return {
+				token: directToken,
+				type: "source"
+			};
+			case "authored": panic("A hidden paragraph-property source binding conflicts with its private owner.");
+			case "source":
+				if (inspection.binding.token !== directToken) panic("A hidden paragraph-property source binding conflicts with its private owner.");
+				return inspection.binding;
+			case "invalid": panic("Cannot transport a malformed hidden paragraph-property source binding.");
+			default: return inspection;
+		}
+	}
+	switch (inspection.status) {
+		case "absent": return { type: "authored" };
+		case "authored": return inspection.binding;
+		case "source":
+			if (!isParagraphPropertySourceToken(inspection.binding.token)) panic("Cannot transport a malformed hidden paragraph-property source token.");
+			return inspection.binding;
+		case "invalid": panic("Cannot transport a malformed hidden paragraph-property source binding.");
+		default: return inspection;
+	}
+};
+/** Prepare opaque continuation cells for ProseMirror and Yjs transport. */
+const transportTableCellsWithParagraphPropertySources = (cells) => {
+	const cloned = structuredClone(cells);
+	const sources = paragraphsInTableCells(cells);
+	const targets = paragraphsInTableCells(cloned);
+	if (sources.length !== targets.length) panic("The cloned table cells changed paragraph graph ownership.");
+	for (const [index, source] of sources.entries()) {
+		const target = targets.at(index);
+		if (!target) panic("The cloned table cells lost a paragraph owner.");
+		copyParagraphPropertyCapture(target, source);
+		const inspection = inspectTableCellParagraphPropertySourceBinding(source);
+		setTableCellParagraphPropertySourceBinding(target, tableCellParagraphPropertySourceBindingForTransport(source, inspection));
+	}
+	return cloned;
+};
+/** Restore decoded identities privately and remove them from the document model. */
+const restoreTableCellsWithParagraphPropertySources = (payload) => {
+	const sourceEntries = decodedTableCellParagraphSourcePayloadState(payload).paragraphs;
+	const cloned = structuredClone([...payload.cells]);
+	const targets = paragraphsInTableCells(cloned);
+	if (sourceEntries.length !== targets.length) panic("The cloned table cells changed paragraph graph ownership.");
+	for (const [index, sourceEntry] of sourceEntries.entries()) {
+		const target = targets.at(index);
+		if (!target) panic("The cloned table cells lost a paragraph owner.");
+		const { paragraph: source } = sourceEntry;
+		copyParagraphPropertyCapture(target, source);
+		if (!Reflect.deleteProperty(target, "_docxParagraphSourceBinding")) panic("Cannot detach paragraph-property transport identity from a table cell.");
+		switch (sourceEntry.binding.type) {
+			case "authored": break;
+			case "source":
+				paragraphPropertySourceTokens.set(target, sourceEntry.binding.token);
+				break;
+			default: return sourceEntry.binding;
+		}
+	}
+	return cloned;
+};
+/** Visit every transported hidden paragraph in canonical cell-story order. */
+const visitTableCellParagraphPropertySourceBindings = (payload, visit) => {
+	for (const { binding, path } of decodedTableCellParagraphSourcePayloadState(payload).paragraphs) visit(binding, path);
+};
+/**
+* Clone package-crossing vertical-merge payloads with their captured `w:pPr`,
+* but without the durable paragraph tokens owned by the source package.
+*/
+const cloneTableCellsWithParagraphPropertyCaptures = (payload) => {
+	const sourceEntries = decodedTableCellParagraphSourcePayloadState(payload).paragraphs;
+	const cloned = structuredClone([...payload.cells]);
+	const targets = paragraphsInTableCells(cloned);
+	if (sourceEntries.length !== targets.length) panic("The cloned table cells changed paragraph graph ownership.");
+	for (const [index, sourceEntry] of sourceEntries.entries()) {
+		const target = targets.at(index);
+		if (!target) panic("The cloned table cells lost a paragraph owner.");
+		copyParagraphPropertyCapture(target, sourceEntry.paragraph);
+		setTableCellParagraphPropertySourceBinding(target, { type: "authored" });
+	}
 	return cloned;
 };
 const linkProseParagraphPropertySource = (proseParagraph, sourceParagraph) => {
 	if (paragraphPropertySources.has(sourceParagraph)) proseParagraphSourceOwners.set(proseParagraph, paragraphPropertySourceOwners.get(sourceParagraph) ?? sourceParagraph);
 };
+/** Create a parsed paragraph with both its same-process owner and durable body token. */
+const createProseParagraphWithPropertySource = (nodeType, sourceParagraph, options = {}) => {
+	if (!nodeType || nodeType.name !== "paragraph") panic("Paragraph-property provenance can only seed a paragraph node");
+	const paragraph = nodeType.create({
+		...options.attrs,
+		[PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR]: paragraphPropertySourceTokens.get(sourceParagraph) ?? null
+	}, options.content, options.marks);
+	linkProseParagraphPropertySource(paragraph, sourceParagraph);
+	return paragraph;
+};
+const paragraphPropertySourceTransfersKey = new PluginKey("paragraphPropertySourceTransfers");
+/** Join adjacent paragraphs when revision semantics deliberately select the right owner. */
+const joinProseParagraphsWithRightPropertySource = ({ attrs, pos, transaction }) => {
+	const $pos = transaction.doc.resolve(pos);
+	const left = $pos.nodeBefore;
+	const right = $pos.nodeAfter;
+	if (!left || !right || left.type.name !== "paragraph" || right.type.name !== "paragraph") panic("Paragraph-property ownership can only join adjacent paragraphs");
+	const leftToken = getProseParagraphPropertySourceToken(left);
+	const rightToken = getProseParagraphPropertySourceToken(right);
+	const leftPos = pos - left.nodeSize;
+	transaction.join(pos);
+	const joined = transaction.doc.nodeAt(leftPos);
+	if (!joined || joined.type.name !== "paragraph") panic("Joining paragraphs did not produce a paragraph");
+	transaction.setNodeMarkup(leftPos, void 0, {
+		...attrs,
+		[PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR]: rightToken ?? null
+	}, joined.marks);
+	const transfers = transaction.getMeta(paragraphPropertySourceTransfersKey) ?? [];
+	transaction.setMeta(paragraphPropertySourceTransfersKey, [...transfers, {
+		displacedToken: typeof leftToken === "string" ? leftToken : null,
+		selectedToken: typeof rightToken === "string" ? rightToken : null
+	}]);
+	return transaction;
+};
+const getExplicitParagraphPropertySourceTransfers = (transaction) => transaction.getMeta(paragraphPropertySourceTransfersKey) ?? [];
 /** Carry a parser-linked paragraph owner across an immutable PM node rebuild. */
 const copyProseParagraphPropertySource = (target, source) => {
 	if (target.type.name !== "paragraph" || source.type.name !== "paragraph") return;
@@ -79,6 +628,21 @@ const recreateProseNodeWithParagraphPropertySource = (source, options = {}) => {
 	copyProseParagraphPropertySource(target, source);
 	return target;
 };
+/**
+* Rebuild a PM node that is crossing from another package: retain its
+* same-process paragraph-property capture, but detach the durable token that
+* can only name a paragraph in the package it came from.
+*/
+const recreateProseNodeWithDetachedParagraphPropertySource = (source, options = {}) => {
+	const attrs = options.attrs ?? source.attrs;
+	return recreateProseNodeWithParagraphPropertySource(source, {
+		...options,
+		attrs: source.type.name === "paragraph" ? {
+			...attrs,
+			[PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR]: null
+		} : attrs
+	});
+};
 /** Replace paragraph markup without losing its private parser-owner link. */
 const setProseParagraphMarkupWithPropertySource = ({ attrs, ownership, pos, transaction }) => {
 	const source = transaction.doc.nodeAt(pos);
@@ -104,10 +668,12 @@ const transferProseParagraphPropertySource = (target, source, paraId) => {
 	paragraphPropertySourceTransferIds.set(sourceOwner, paraId);
 };
 const linkParagraphPropertySourceCandidate = (target, source) => {
+	const token = source.attrs[PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR];
+	if (typeof token === "string") paragraphPropertySourceTokens.set(target, token);
 	const sourceOwner = proseParagraphSourceOwners.get(source);
 	if (sourceOwner) paragraphPropertySourceCandidates.set(target, sourceOwner);
 };
 const getParagraphPropertySourceCandidate = (paragraph) => paragraphPropertySourceCandidates.get(paragraph);
 const getParagraphPropertySourceTransferId = (paragraph) => paragraphPropertySourceTransferIds.get(paragraph);
 //#endregion
-export { assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, copyParagraphPropertySource, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceTransferId, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource };
+export { PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES, PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, ParagraphPropertySourceValidationError, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR, TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS, assignDocumentParagraphPropertySourceContract, assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, cloneTableCellsWithParagraphPropertyCaptures, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, createProseParagraphWithPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getExplicitParagraphPropertySourceTransfers, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, joinProseParagraphsWithRightPropertySource, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithDetachedParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource, transportTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings };

package/dist/docx/parser.js

@@ -18,6 +18,7 @@ import { renderEmfSvg } from "./metafileSvg.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
 import { normalizeNumberingReferences } from "./numberingReferenceNormalization.js";
+import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRenderedPageBreakHints } from "./renderedPageBreakNormalization.js";
 import { parseSettings } from "./settingsParser.js";
@@ -50,6 +51,12 @@ import { TaggedError } from "better-result";
 const EMF_MIME_TYPE = "image/x-emf";
 const SVG_MIME_TYPE = "image/svg+xml";
 const MAX_PACKAGE_EMF_PREVIEW_BYTES = 8 * 1024 * 1024;
+const sha256Hex = async (buffer) => {
+	const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", buffer));
+	let digest = "";
+	for (const byte of bytes) digest += byte.toString(16).padStart(2, "0");
+	return digest;
+};
 /**
 * Parse a DOCX file into a complete Document model
 *
@@ -65,6 +72,7 @@ async function parseDocx(input, options = {}) {
 	try {
 		const timeStage = (_name, fn) => fn();
 		const timeStageAsync = async (_name, fn) => await fn();
+		const paragraphPropertySourceDigest = sha256Hex(buffer);
 		onProgress("Extracting DOCX...", 0);
 		const raw = await timeStageAsync("unzip", () => unzipDocx(buffer, {
 			...unzipLimits,
@@ -216,6 +224,7 @@ async function parseDocx(input, options = {}) {
 			...templateVariables !== void 0 ? { templateVariables } : {},
 			...requiredFonts.length > 0 ? { requiredFonts } : {}
 		};
+		assignDocumentParagraphPropertySourceContract(document, await paragraphPropertySourceDigest);
 		enforcePackageVmlPreviewBudget(document.package);
 		const validation = validateFolioDocumentModel(document);
 		const parsedCompleteModel = parseHeadersFooters && parseNotes;