documents.js 1.34.2 → 1.35.0

package/README.md

@@ -153,6 +153,7 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **Table cell `colSpan`/`rowSpan` and pptx shape rotation are read from a `ContentDocument` but not yet written back** by `buildDocxPackage`/`buildPptxPackage` — a merged cell round-trips as an ordinary unmerged one, and a rotated shape round-trips unrotated. Both are bounded, tracked gaps (the cell's own text content and the shape's own position are still correct), not silent ones.
 - **docx headers/footers, live `PAGE`/`NUMPAGES` field substitution, and inline images are not read** by `readDocxContent` — a deliberate, tracked scope narrowing from the original design, not an oversight.
 - **pptx speaker notes survive `pptxToPdf`/`pdfToPptx`, but not through any real PDF feature.** PDF has no native concept of hidden presenter notes, so `convertPresentationToLayout` carries `ContentSlide.notes` as a hidden `/Subtype /Text` annotation on the page (the same construct Acrobat's own sticky-note tool uses, marked with the `Hidden` annotation flag so it never renders or prints), and `reconstructPresentation` reads it back via a `/T` marker that distinguishes this package's own notes annotation from a genuine third-party sticky note. This is a round-trip mechanism specific to this package's own writer/reader pair — a PDF produced by anything else will never carry it, and a PDF consumer other than this package's own `readPdf` will never see it as anything but an invisible, empty sticky note.
+- **`sourcePath` traces a `LayoutItem` back to the `ContentDocument` node it came from, but only within one read+layout pass.** `ooxml.js`'s `readDocx`/`readPptx` stamp every `ContentRun`/`ContentImageBlock`/`ContentTable`/`ContentShape` with a positional path (`sections[0].blocks[2].runs[1]`, `slides[1].shapes[3].blocks[0]`); `convertWordprocessingToLayout`/`convertPresentationToLayout` copy that same string onto whichever `LayoutText`/`LayoutImage`/`LayoutLink`/`LayoutRect` item(s) it produces, so a positioned PDF-side item can be traced back to its semantic origin. When line-wrapping splits one run's word across a run boundary, every resulting fragment gets its own run's path (not a shared or merged one); when a single run is emergency-split across several lines or pages, every resulting fragment keeps that same one run's path unchanged. A table cell's background `LayoutRect` is attributed to its containing table's own `sourcePath`, since `ContentTableCell` carries none of its own. This is **not** an edit-tracking or incremental-relayout mechanism — the path is only valid against the exact `ContentDocument`/`Package` it was assigned from in that one read; editing the document, re-reading it, or reordering its blocks invalidates every previously-captured path, and nothing here recomputes or diffs paths across two versions of a document.
 
 ## Fidelity
 

package/dist/index.cjs

@@ -6735,7 +6735,8 @@ function atomizeRuns(runs, measurer) {
 				sizePt: run.sizePt,
 				color: run.color,
 				underline: run.underline,
-				hyperlink: run.hyperlink
+				hyperlink: run.hyperlink,
+				sourcePath: run.sourcePath
 			});
 			wordWidth += measurer.widthOfTextAtSize(token, run.font, run.sizePt);
 		}
@@ -6923,7 +6924,8 @@ function toStyledRuns(runs, fontScale = 1) {
 		sizePt: (run.sizePt ?? 18) * fontScale,
 		color: run.color ?? document_content_model.COLOR_BLACK,
 		underline: run.underline,
-		hyperlink: run.hyperlink
+		hyperlink: run.hyperlink,
+		sourcePath: run.sourcePath
 	}));
 }
 function effectiveStyledRuns(runs, fontScale = 1) {
@@ -7038,7 +7040,8 @@ function layoutParagraphFlow(paragraph, section, pages, state, contentLeftXDown,
 				font: fragment.font,
 				sizePt: fragment.sizePt,
 				color: fragment.color,
-				underline: fragment.underline
+				underline: fragment.underline,
+				sourcePath: fragment.sourcePath
 			};
 			state.items.push(textItem);
 			if (fragment.hyperlink !== void 0) {
@@ -7049,7 +7052,8 @@ function layoutParagraphFlow(paragraph, section, pages, state, contentLeftXDown,
 					xPt,
 					yPt: section.pageSize.heightPt - baselineYDown + line.descentPt,
 					widthPt: fragmentWidthPt,
-					heightPt: line.ascentPt - line.descentPt
+					heightPt: line.ascentPt - line.descentPt,
+					sourcePath: fragment.sourcePath
 				};
 				state.items.push(link);
 			}
@@ -7077,7 +7081,8 @@ function layoutParagraphInCell(paragraph, cellLeftXDown, cellWidthPt, startYDown
 			font: fragment.font,
 			sizePt: fragment.sizePt,
 			color: fragment.color,
-			underline: fragment.underline
+			underline: fragment.underline,
+			sourcePath: fragment.sourcePath
 		});
 		cursorYDown += lineHeightPt;
 	});
@@ -7107,7 +7112,8 @@ function layoutTableFlow(table, section, pages, state, contentLeftXDown, content
 					yPt: cellFrame.yPt,
 					widthPt: cellFrame.widthPt,
 					heightPt: cellFrame.heightPt,
-					fill: cell.background
+					fill: cell.background,
+					sourcePath: table.sourcePath
 				});
 			}
 			let cellCursorYDown = state.cursorYDown;
@@ -7133,7 +7139,8 @@ function layoutImageFlow(block, section, pages, state, contentLeftXDown, content
 		xPt: flippedFrame.xPt,
 		yPt: flippedFrame.yPt,
 		widthPt: flippedFrame.widthPt,
-		heightPt: flippedFrame.heightPt
+		heightPt: flippedFrame.heightPt,
+		sourcePath: block.sourcePath
 	};
 	state.items.push(imageItem);
 	state.cursorYDown += block.heightPt;
@@ -7204,7 +7211,8 @@ function layoutParagraph(paragraph, contentLeftXDown, contentWidthPt, startYDown
 				sizePt: fragment.sizePt,
 				color: fragment.color,
 				underline: fragment.underline,
-				rotationDeg: placement.layoutRotationDeg
+				rotationDeg: placement.layoutRotationDeg,
+				sourcePath: fragment.sourcePath
 			};
 			out.push(textItem);
 			if (fragment.hyperlink !== void 0) {
@@ -7219,7 +7227,8 @@ function layoutParagraph(paragraph, contentLeftXDown, contentWidthPt, startYDown
 					xPt: linkBottomLeft.x,
 					yPt: linkBottomLeft.y,
 					widthPt: fragmentWidthPt,
-					heightPt: line.ascentPt - line.descentPt
+					heightPt: line.ascentPt - line.descentPt,
+					sourcePath: fragment.sourcePath
 				};
 				out.push(link);
 			}
@@ -7253,7 +7262,8 @@ function layoutTable(table, contentLeftXDown, contentWidthPt, startYDown, slideH
 					yPt: cellFrame.yPt,
 					widthPt: cellFrame.widthPt,
 					heightPt: cellFrame.heightPt,
-					fill: cell.background
+					fill: cell.background,
+					sourcePath: table.sourcePath
 				});
 			}
 			let cellCursorYDown = cursorYDown;
@@ -7287,7 +7297,8 @@ function convertShape(shape, slideHeightPt, measurer, images, out) {
 			yPt: placed.y,
 			widthPt: flippedFrame.widthPt,
 			heightPt: flippedFrame.heightPt,
-			rotationDeg: placement.layoutRotationDeg
+			rotationDeg: placement.layoutRotationDeg,
+			sourcePath: block.sourcePath
 		};
 		out.push(imageItem);
 	} else if (block.kind === "table") cursorYDown = layoutTable(block, contentLeftXDown, contentWidthPt, cursorYDown, slideHeightPt, placement, measurer, out);

package/dist/index.d.cts

@@ -62,6 +62,7 @@ declare const ContentDocumentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       insetBottomPt: z.ZodNumber;
       fontScale: z.ZodOptional<z.ZodNumber>;
       lineSpacingReduction: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
       blocks: z.ZodArray<z.ZodCustom<import("document-content-model").ContentBlock, import("document-content-model").ContentBlock>>;
     }, z.core.$strip>>;
     notes: z.ZodString;
@@ -375,6 +376,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       widthPt: z.ZodOptional<z.ZodNumber>;
       rotationDeg: z.ZodOptional<z.ZodNumber>;
       underline: z.ZodOptional<z.ZodBoolean>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"image">;
       imageId: z.ZodString;
@@ -383,6 +385,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       widthPt: z.ZodNumber;
       heightPt: z.ZodNumber;
       rotationDeg: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"rect">;
       xPt: z.ZodNumber;
@@ -402,6 +405,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         }, z.core.$strip>;
         widthPt: z.ZodNumber;
       }, z.core.$strip>>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"line">;
       x1Pt: z.ZodNumber;
@@ -414,6 +418,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         b: z.ZodNumber;
       }, z.core.$strip>;
       widthPt: z.ZodNumber;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"ellipse">;
       xPt: z.ZodNumber;
@@ -433,6 +438,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         }, z.core.$strip>;
         widthPt: z.ZodNumber;
       }, z.core.$strip>>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"link">;
       uri: z.ZodString;
@@ -440,6 +446,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       yPt: z.ZodNumber;
       widthPt: z.ZodNumber;
       heightPt: z.ZodNumber;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">>;
     notes: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>;

package/dist/index.d.ts

@@ -62,6 +62,7 @@ declare const ContentDocumentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       insetBottomPt: z.ZodNumber;
       fontScale: z.ZodOptional<z.ZodNumber>;
       lineSpacingReduction: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
       blocks: z.ZodArray<z.ZodCustom<import("document-content-model").ContentBlock, import("document-content-model").ContentBlock>>;
     }, z.core.$strip>>;
     notes: z.ZodString;
@@ -375,6 +376,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       widthPt: z.ZodOptional<z.ZodNumber>;
       rotationDeg: z.ZodOptional<z.ZodNumber>;
       underline: z.ZodOptional<z.ZodBoolean>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"image">;
       imageId: z.ZodString;
@@ -383,6 +385,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       widthPt: z.ZodNumber;
       heightPt: z.ZodNumber;
       rotationDeg: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"rect">;
       xPt: z.ZodNumber;
@@ -402,6 +405,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         }, z.core.$strip>;
         widthPt: z.ZodNumber;
       }, z.core.$strip>>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"line">;
       x1Pt: z.ZodNumber;
@@ -414,6 +418,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         b: z.ZodNumber;
       }, z.core.$strip>;
       widthPt: z.ZodNumber;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"ellipse">;
       xPt: z.ZodNumber;
@@ -433,6 +438,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
         }, z.core.$strip>;
         widthPt: z.ZodNumber;
       }, z.core.$strip>>;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
       kind: z.ZodLiteral<"link">;
       uri: z.ZodString;
@@ -440,6 +446,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
       yPt: z.ZodNumber;
       widthPt: z.ZodNumber;
       heightPt: z.ZodNumber;
+      sourcePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">>;
     notes: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>;

package/dist/index.js

@@ -6734,7 +6734,8 @@ function atomizeRuns(runs, measurer) {
 				sizePt: run.sizePt,
 				color: run.color,
 				underline: run.underline,
-				hyperlink: run.hyperlink
+				hyperlink: run.hyperlink,
+				sourcePath: run.sourcePath
 			});
 			wordWidth += measurer.widthOfTextAtSize(token, run.font, run.sizePt);
 		}
@@ -6922,7 +6923,8 @@ function toStyledRuns(runs, fontScale = 1) {
 		sizePt: (run.sizePt ?? 18) * fontScale,
 		color: run.color ?? COLOR_BLACK,
 		underline: run.underline,
-		hyperlink: run.hyperlink
+		hyperlink: run.hyperlink,
+		sourcePath: run.sourcePath
 	}));
 }
 function effectiveStyledRuns(runs, fontScale = 1) {
@@ -7037,7 +7039,8 @@ function layoutParagraphFlow(paragraph, section, pages, state, contentLeftXDown,
 				font: fragment.font,
 				sizePt: fragment.sizePt,
 				color: fragment.color,
-				underline: fragment.underline
+				underline: fragment.underline,
+				sourcePath: fragment.sourcePath
 			};
 			state.items.push(textItem);
 			if (fragment.hyperlink !== void 0) {
@@ -7048,7 +7051,8 @@ function layoutParagraphFlow(paragraph, section, pages, state, contentLeftXDown,
 					xPt,
 					yPt: section.pageSize.heightPt - baselineYDown + line.descentPt,
 					widthPt: fragmentWidthPt,
-					heightPt: line.ascentPt - line.descentPt
+					heightPt: line.ascentPt - line.descentPt,
+					sourcePath: fragment.sourcePath
 				};
 				state.items.push(link);
 			}
@@ -7076,7 +7080,8 @@ function layoutParagraphInCell(paragraph, cellLeftXDown, cellWidthPt, startYDown
 			font: fragment.font,
 			sizePt: fragment.sizePt,
 			color: fragment.color,
-			underline: fragment.underline
+			underline: fragment.underline,
+			sourcePath: fragment.sourcePath
 		});
 		cursorYDown += lineHeightPt;
 	});
@@ -7106,7 +7111,8 @@ function layoutTableFlow(table, section, pages, state, contentLeftXDown, content
 					yPt: cellFrame.yPt,
 					widthPt: cellFrame.widthPt,
 					heightPt: cellFrame.heightPt,
-					fill: cell.background
+					fill: cell.background,
+					sourcePath: table.sourcePath
 				});
 			}
 			let cellCursorYDown = state.cursorYDown;
@@ -7132,7 +7138,8 @@ function layoutImageFlow(block, section, pages, state, contentLeftXDown, content
 		xPt: flippedFrame.xPt,
 		yPt: flippedFrame.yPt,
 		widthPt: flippedFrame.widthPt,
-		heightPt: flippedFrame.heightPt
+		heightPt: flippedFrame.heightPt,
+		sourcePath: block.sourcePath
 	};
 	state.items.push(imageItem);
 	state.cursorYDown += block.heightPt;
@@ -7203,7 +7210,8 @@ function layoutParagraph(paragraph, contentLeftXDown, contentWidthPt, startYDown
 				sizePt: fragment.sizePt,
 				color: fragment.color,
 				underline: fragment.underline,
-				rotationDeg: placement.layoutRotationDeg
+				rotationDeg: placement.layoutRotationDeg,
+				sourcePath: fragment.sourcePath
 			};
 			out.push(textItem);
 			if (fragment.hyperlink !== void 0) {
@@ -7218,7 +7226,8 @@ function layoutParagraph(paragraph, contentLeftXDown, contentWidthPt, startYDown
 					xPt: linkBottomLeft.x,
 					yPt: linkBottomLeft.y,
 					widthPt: fragmentWidthPt,
-					heightPt: line.ascentPt - line.descentPt
+					heightPt: line.ascentPt - line.descentPt,
+					sourcePath: fragment.sourcePath
 				};
 				out.push(link);
 			}
@@ -7252,7 +7261,8 @@ function layoutTable(table, contentLeftXDown, contentWidthPt, startYDown, slideH
 					yPt: cellFrame.yPt,
 					widthPt: cellFrame.widthPt,
 					heightPt: cellFrame.heightPt,
-					fill: cell.background
+					fill: cell.background,
+					sourcePath: table.sourcePath
 				});
 			}
 			let cellCursorYDown = cursorYDown;
@@ -7286,7 +7296,8 @@ function convertShape(shape, slideHeightPt, measurer, images, out) {
 			yPt: placed.y,
 			widthPt: flippedFrame.widthPt,
 			heightPt: flippedFrame.heightPt,
-			rotationDeg: placement.layoutRotationDeg
+			rotationDeg: placement.layoutRotationDeg,
+			sourcePath: block.sourcePath
 		};
 		out.push(imageItem);
 	} else if (block.kind === "table") cursorYDown = layoutTable(block, contentLeftXDown, contentWidthPt, cursorYDown, slideHeightPt, placement, measurer, out);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "documents.js",
-  "version": "1.34.2",
+  "version": "1.35.0",
   "description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -64,9 +64,9 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "document-content-model": "^1.0.0",
+    "document-content-model": "^1.1.0",
     "fflate": "^0.8.3",
-    "ooxml.js": "^2.0.0",
+    "ooxml.js": "^2.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {