@stll/folio-core 0.15.1 → 0.15.2

package/dist/docx/commentParser.js

@@ -1,6 +1,26 @@
-import { findChild, getAttribute, getChildElements, parseXml } from "./xmlParser.js";
+import { findChild, getAttribute, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+import { parseRunProperties } from "./runParser.js";
 import { parseParagraph } from "./paragraphParser.js";
 //#region src/docx/commentParser.ts
+const DEFAULT_ANNOTATION_REFERENCE_STYLE_ID = "CommentReference";
+const normalizeAnnotationReferenceFormatting = (formatting) => {
+	if (formatting?.styleId === DEFAULT_ANNOTATION_REFERENCE_STYLE_ID && Object.keys(formatting).length === 1) return;
+	return formatting;
+};
+const normalizeFirstCommentParagraph = (paragraphElement, paragraph, theme) => {
+	const firstContentElement = getChildElements(paragraphElement).find((element) => getLocalName(element.name) !== "pPr");
+	if (!firstContentElement || getLocalName(firstContentElement.name) !== "r" || !findChild(firstContentElement, "w", "annotationRef")) return { paragraph };
+	const runProperties = findChild(firstContentElement, "w", "rPr");
+	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme) : void 0);
+	const firstParsedContent = paragraph.content.at(0);
+	return {
+		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.length === 0 ? {
+			...paragraph,
+			content: paragraph.content.slice(1)
+		} : paragraph,
+		...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {}
+	};
+};
 /**
 * Build a lookup from paraId → dateUtc from commentsExtensible.xml
 *
@@ -91,9 +111,16 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const date = (paraId ? dateUtcByParaId.get(paraId) : void 0) ?? localDate;
 		const done = (paraId ? extendedByParaId.get(paraId) : void 0)?.done;
 		const paragraphs = [];
+		let annotationReferenceFormatting;
 		for (const contentChild of getChildElements(child)) if ((contentChild.name?.replace(/^.*:/u, "") ?? "") === "p") {
 			const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
-			paragraphs.push(paragraph);
+			if (paragraphs.length > 0) {
+				paragraphs.push(paragraph);
+				continue;
+			}
+			const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
+			annotationReferenceFormatting = normalized.annotationReferenceFormatting;
+			paragraphs.push(normalized.paragraph);
 		}
 		const commentIndex = comments.length;
 		if (paraId) {
@@ -106,6 +133,7 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 			...initials !== void 0 ? { initials } : {},
 			...date !== void 0 ? { date } : {},
 			...done !== void 0 ? { done } : {},
+			...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {},
 			content: paragraphs
 		});
 	}

package/dist/docx/drawingIdNormalization.d.ts

@@ -0,0 +1,5 @@
+import { DocxParagraphSurfaces } from "./paragraphTraversal.js";
+//#region src/docx/drawingIdNormalization.d.ts
+declare const normalizeDrawingIds: (surfaces: DocxParagraphSurfaces) => void;
+//#endregion
+export { normalizeDrawingIds };

package/dist/docx/drawingIdNormalization.js

@@ -0,0 +1,35 @@
+import { visitDocxParagraphs, visitParagraphRuns } from "./paragraphTraversal.js";
+//#region src/docx/drawingIdNormalization.ts
+const GENERATED_DRAWING_ID_START = 1e5;
+const needsGeneratedId = ({ id }) => id === void 0 || id === "" || id === "0";
+const normalizeDrawingIds = (surfaces) => {
+	const entries = [];
+	visitDocxParagraphs(surfaces, (paragraph) => {
+		visitParagraphRuns(paragraph, (run) => {
+			for (const content of run.content) {
+				if (content.type === "shape") {
+					entries.push({
+						drawing: content.shape,
+						generateWhenMissing: true
+					});
+					continue;
+				}
+				if (content.type === "drawing") entries.push({
+					drawing: content.image,
+					generateWhenMissing: content.rawXml === void 0
+				});
+			}
+		});
+	});
+	const usedIds = new Set(entries.flatMap(({ drawing }) => needsGeneratedId(drawing) ? [] : [drawing.id]));
+	let nextId = GENERATED_DRAWING_ID_START;
+	for (const { drawing, generateWhenMissing } of entries) {
+		if (!generateWhenMissing || !needsGeneratedId(drawing)) continue;
+		while (usedIds.has(String(nextId))) nextId += 1;
+		drawing.id = String(nextId);
+		usedIds.add(drawing.id);
+		nextId += 1;
+	}
+};
+//#endregion
+export { normalizeDrawingIds };

package/dist/docx/drawingUtils.d.ts

@@ -48,7 +48,7 @@ declare function parsePositionV(posV: XmlElement | null): document_d_exports.Ima
 /**
  * Parse position for anchored drawings (combines positionH + positionV).
  */
-declare function parseAnchorPosition(anchor: XmlElement): document_d_exports.ImagePosition | undefined;
+declare function parseAnchorPosition(anchor: XmlElement): document_d_exports.ImagePosition;
 /** Known wrap element names */
 declare const WRAP_ELEMENT_NAMES: string[];
 /**

package/dist/docx/drawingUtils.js

@@ -1,5 +1,5 @@
 import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, ShapeOutlineStyleSchema, narrowEnum } from "./parserEnums.js";
-import { findByFullName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { elementToXml, findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
 //#region src/docx/drawingUtils.ts
 /**
 * Map OOXML scheme names to standard theme color slots.
@@ -119,9 +119,8 @@ function parseColorElement(element) {
 */
 function parseFill(spPr) {
 	if (!spPr) return;
-	const children = getChildElements(spPr);
-	if (children.some((el) => el.name === "a:noFill")) return { type: "none" };
-	const solidFill = children.find((el) => el.name === "a:solidFill");
+	if (findChildByLocalName(spPr, "noFill")) return { type: "none" };
+	const solidFill = findChildByLocalName(spPr, "solidFill");
 	if (solidFill) {
 		const color = parseColorElement(solidFill);
 		return color !== void 0 ? {
@@ -129,31 +128,105 @@ function parseFill(spPr) {
 			color
 		} : { type: "solid" };
 	}
-	if (children.some((el) => el.name === "a:gradFill")) return { type: "gradient" };
+	const gradientFill = findChildByLocalName(spPr, "gradFill");
+	if (gradientFill) return parseGradientFill(gradientFill);
+}
+function parseGradientFill(gradientFill) {
+	let type = "linear";
+	let angle;
+	const linear = findChildByLocalName(gradientFill, "lin");
+	if (linear) {
+		const authoredAngle = getAttribute(linear, null, "ang");
+		if (authoredAngle) {
+			const parsedAngle = Number.parseInt(authoredAngle, 10);
+			angle = Number.isNaN(parsedAngle) ? void 0 : parsedAngle / 6e4;
+		}
+	}
+	const path = findChildByLocalName(gradientFill, "path");
+	if (path) {
+		const pathType = getAttribute(path, null, "path");
+		if (pathType === "circle") type = "radial";
+		else if (pathType === "rect") type = "rectangular";
+		else type = "path";
+	}
+	const stops = [];
+	const stopList = findChildByLocalName(gradientFill, "gsLst");
+	if (stopList) for (const stop of findChildrenByLocalName(stopList, "gs")) {
+		const authoredPosition = getAttribute(stop, null, "pos");
+		const parsedPosition = authoredPosition ? Number.parseInt(authoredPosition, 10) : 0;
+		const color = parseColorElement(stop);
+		if (color) stops.push({
+			position: Number.isNaN(parsedPosition) ? 0 : parsedPosition,
+			color
+		});
+	}
+	return {
+		type: "gradient",
+		rawXml: elementToXml(gradientFill),
+		gradient: {
+			type,
+			...angle !== void 0 ? { angle } : {},
+			stops
+		}
+	};
 }
 /**
 * Parse outline from shape properties (a:ln).
 */
 function parseOutline(spPr) {
-	const ln = spPr ? findByFullName(spPr, "a:ln") : null;
+	const ln = spPr ? findChildByLocalName(spPr, "ln") : null;
 	if (!ln) return;
-	const children = getChildElements(ln);
-	if (children.some((el) => el.name === "a:noFill")) return;
-	const outline = {};
+	if (findChildByLocalName(ln, "noFill")) return;
+	const outline = { rawXml: elementToXml(ln) };
 	const w = getAttribute(ln, null, "w");
-	if (w) outline.width = Number.parseInt(w, 10);
-	const solidFill = children.find((el) => el.name === "a:solidFill");
+	if (w) {
+		const parsed = Number.parseInt(w, 10);
+		if (!Number.isNaN(parsed)) outline.width = parsed;
+	}
+	const cap = getAttribute(ln, null, "cap");
+	if (cap === "flat") outline.cap = "flat";
+	else if (cap === "rnd") outline.cap = "round";
+	else if (cap === "sq") outline.cap = "square";
+	if (findChildByLocalName(ln, "bevel")) outline.join = "bevel";
+	else if (findChildByLocalName(ln, "round")) outline.join = "round";
+	else if (findChildByLocalName(ln, "miter")) outline.join = "miter";
+	const solidFill = findChildByLocalName(ln, "solidFill");
 	if (solidFill) {
 		const color = parseColorElement(solidFill);
 		if (color !== void 0) outline.color = color;
 	}
-	const prstDash = children.find((el) => el.name === "a:prstDash");
+	const prstDash = findChildByLocalName(ln, "prstDash");
 	if (prstDash) {
 		const val = narrowEnum(getAttribute(prstDash, null, "val"), ShapeOutlineStyleSchema);
 		if (val) outline.style = val;
 	}
+	const headEnd = findChildByLocalName(ln, "headEnd");
+	if (headEnd) outline.headEnd = parseLineEnd(headEnd);
+	const tailEnd = findChildByLocalName(ln, "tailEnd");
+	if (tailEnd) outline.tailEnd = parseLineEnd(tailEnd);
 	return outline;
 }
+const LINE_END_TYPES = [
+	"none",
+	"triangle",
+	"stealth",
+	"diamond",
+	"oval",
+	"arrow"
+];
+function parseLineEnd(element) {
+	const authoredType = getAttribute(element, null, "type");
+	const type = LINE_END_TYPES.find((allowed) => allowed === authoredType) ?? "none";
+	const authoredWidth = getAttribute(element, null, "w");
+	const authoredLength = getAttribute(element, null, "len");
+	const width = authoredWidth === "sm" || authoredWidth === "med" || authoredWidth === "lg" ? authoredWidth : void 0;
+	const length = authoredLength === "sm" || authoredLength === "med" || authoredLength === "lg" ? authoredLength : void 0;
+	return {
+		type,
+		...width !== void 0 ? { width } : {},
+		...length !== void 0 ? { length } : {}
+	};
+}
 /**
 * Parse horizontal position from wp:positionH element.
 */
@@ -162,11 +235,11 @@ function parsePositionH(posH) {
 	const relativeTo = narrowEnum(getAttribute(posH, null, "relativeFrom"), ImageHorizontalRelativeToSchema) ?? "column";
 	const alignEl = findByFullName(posH, "wp:align");
 	if (alignEl) {
-		const text = getTextContent(alignEl);
-		const result = { relativeTo };
-		const alignment = narrowEnum(text, ImageHorizontalAlignmentSchema);
-		if (alignment) result.alignment = alignment;
-		return result;
+		const alignment = narrowEnum(getTextContent(alignEl), ImageHorizontalAlignmentSchema);
+		if (alignment) return {
+			relativeTo,
+			alignment
+		};
 	}
 	const posOffsetEl = findByFullName(posH, "wp:posOffset");
 	if (posOffsetEl) {
@@ -177,7 +250,10 @@ function parsePositionH(posH) {
 			posOffset: Number.isNaN(posOffset) ? 0 : posOffset
 		};
 	}
-	return { relativeTo };
+	return {
+		relativeTo,
+		posOffset: 0
+	};
 }
 /**
 * Parse vertical position from wp:positionV element.
@@ -187,11 +263,11 @@ function parsePositionV(posV) {
 	const relativeTo = narrowEnum(getAttribute(posV, null, "relativeFrom"), ImageVerticalRelativeToSchema) ?? "paragraph";
 	const alignEl = findByFullName(posV, "wp:align");
 	if (alignEl) {
-		const text = getTextContent(alignEl);
-		const result = { relativeTo };
-		const alignment = narrowEnum(text, ImageVerticalAlignmentSchema);
-		if (alignment) result.alignment = alignment;
-		return result;
+		const alignment = narrowEnum(getTextContent(alignEl), ImageVerticalAlignmentSchema);
+		if (alignment) return {
+			relativeTo,
+			alignment
+		};
 	}
 	const posOffsetEl = findByFullName(posV, "wp:posOffset");
 	if (posOffsetEl) {
@@ -202,7 +278,10 @@ function parsePositionV(posV) {
 			posOffset: Number.isNaN(posOffset) ? 0 : posOffset
 		};
 	}
-	return { relativeTo };
+	return {
+		relativeTo,
+		posOffset: 0
+	};
 }
 /**
 * Parse position for anchored drawings (combines positionH + positionV).
@@ -210,10 +289,15 @@ function parsePositionV(posV) {
 function parseAnchorPosition(anchor) {
 	const positionH = findByFullName(anchor, "wp:positionH");
 	const positionV = findByFullName(anchor, "wp:positionV");
-	if (!positionH && !positionV) return;
 	return {
-		horizontal: parsePositionH(positionH) ?? { relativeTo: "column" },
-		vertical: parsePositionV(positionV) ?? { relativeTo: "paragraph" }
+		horizontal: parsePositionH(positionH) ?? {
+			relativeTo: "column",
+			posOffset: 0
+		},
+		vertical: parsePositionV(positionV) ?? {
+			relativeTo: "paragraph",
+			posOffset: 0
+		}
 	};
 }
 /** Known wrap element names */

package/dist/docx/headerFooterVerbatim.d.ts

@@ -14,6 +14,7 @@ type HeaderFooterWithVerbatim = document_d_exports.HeaderFooter & {
 declare const getHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => string | undefined;
 declare const canReplayHeaderFooterVerbatim: (hf: document_d_exports.HeaderFooter) => boolean;
 declare const assignHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter, xml: string) => void;
+declare const refreshHeaderFooterVerbatimFingerprint: (hf: document_d_exports.HeaderFooter) => void;
 declare const clearHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => void;
 //#endregion
-export { HeaderFooterWithVerbatim, assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml };
+export { HeaderFooterWithVerbatim, assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };

package/dist/docx/headerFooterVerbatim.js

@@ -16,10 +16,15 @@ const assignHeaderFooterVerbatimXml = (hf, xml) => {
 	ext.verbatimXml = xml;
 	ext.verbatimFingerprint = headerFooterSerializationFingerprint(hf);
 };
+const refreshHeaderFooterVerbatimFingerprint = (hf) => {
+	const ext = hf;
+	if (!ext.verbatimXml) return;
+	ext.verbatimFingerprint = headerFooterSerializationFingerprint(hf);
+};
 const clearHeaderFooterVerbatimXml = (hf) => {
 	const ext = hf;
 	delete ext.verbatimXml;
 	delete ext.verbatimFingerprint;
 };
 //#endregion
-export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml };
+export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };

package/dist/docx/paragraphParser.js

@@ -1,5 +1,5 @@
 import { BorderStyleSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, TabLeaderSchema, TabStopAlignmentSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
-import { elementToXml, findChild, findChildren, getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute } from "./xmlParser.js";
+import { elementToXml, findChild, findChildren, getAttribute, getChildElements, getLocalName, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute } from "./xmlParser.js";
 import { parseRun, parseRunProperties } from "./runParser.js";
 import { parseFieldType } from "./fieldParser.js";
 import { isValidHexId } from "../utils/hexId.js";
@@ -684,6 +684,9 @@ function parseSimpleField(node, styles, theme, rels, media, rootXmlns = {}) {
 	}
 	return field;
 }
+function hasRunPayloadElement(runElement) {
+	return getChildElements(runElement).some((child) => !matchesName(child, "w", "rPr"));
+}
 /**
 * Parse all content within a paragraph
 *
@@ -789,7 +792,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 						type: "commentReference",
 						id: commentReferenceId
 					});
-				} else contents.push(run);
+				} else if (run.content.length > 0 || hasRunPayloadElement(runElement)) contents.push(run);
 				break;
 			}
 			case "hyperlink":

package/dist/docx/paragraphTraversal.d.ts

@@ -1,12 +1,14 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/paragraphTraversal.d.ts
-type VisitDocxParagraphsInput = {
+type DocxParagraphSurfaces = {
   documentBody: document_d_exports.DocumentBody;
   headers?: Map<string, document_d_exports.HeaderFooter> | undefined;
   footers?: Map<string, document_d_exports.HeaderFooter> | undefined;
   footnotes?: readonly document_d_exports.Footnote[] | undefined;
   endnotes?: readonly document_d_exports.Endnote[] | undefined;
 };
-declare const visitDocxParagraphs: ({ documentBody, headers, footers, footnotes, endnotes }: VisitDocxParagraphsInput, visit: (paragraph: document_d_exports.Paragraph) => void) => void;
+/** Visit every run directly owned by a paragraph's inline-content tree. */
+declare const visitParagraphRuns: (paragraph: document_d_exports.Paragraph, visit: (run: document_d_exports.Run) => void) => void;
+declare const visitDocxParagraphs: ({ documentBody, headers, footers, footnotes, endnotes }: DocxParagraphSurfaces, visit: (paragraph: document_d_exports.Paragraph) => void) => void;
 //#endregion
-export { visitDocxParagraphs };
+export { DocxParagraphSurfaces, visitDocxParagraphs, visitParagraphRuns };

package/dist/docx/paragraphTraversal.js

@@ -1,17 +1,8 @@
 //#region src/docx/paragraphTraversal.ts
-const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnotes }, visit) => {
-	const seenParagraphs = /* @__PURE__ */ new WeakSet();
-	const visitParagraph = (paragraph) => {
-		if (seenParagraphs.has(paragraph)) return;
-		seenParagraphs.add(paragraph);
-		visit(paragraph);
-		for (const content of paragraph.content) visitParagraphContent(content);
-	};
+/** Visit every run directly owned by a paragraph's inline-content tree. */
+const visitParagraphRuns = (paragraph, visit) => {
 	const visitRun = (run) => {
-		for (const content of run.content) {
-			if (content.type !== "shape" || !content.shape.textBody) continue;
-			for (const block of content.shape.textBody.content) visitBlock(block);
-		}
+		visit(run);
 	};
 	const visitHyperlink = (hyperlink) => {
 		for (const child of hyperlink.children) if (child.type === "run") visitRun(child);
@@ -47,6 +38,22 @@ const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnot
 			for (const run of content.fieldResult) visitRun(run);
 		}
 	};
+	for (const content of paragraph.content) visitParagraphContent(content);
+};
+const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnotes }, visit) => {
+	const seenParagraphs = /* @__PURE__ */ new WeakSet();
+	const visitParagraph = (paragraph) => {
+		if (seenParagraphs.has(paragraph)) return;
+		seenParagraphs.add(paragraph);
+		visit(paragraph);
+		visitParagraphRuns(paragraph, visitRun);
+	};
+	const visitRun = (run) => {
+		for (const content of run.content) {
+			if (content.type !== "shape" || !content.shape.textBody) continue;
+			for (const block of content.shape.textBody.content) visitBlock(block);
+		}
+	};
 	const visitTable = (table) => {
 		for (const row of table.rows) for (const cell of row.cells) visitBlocks(cell.content);
 	};
@@ -73,4 +80,4 @@ const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnot
 	for (const comment of documentBody.comments ?? []) for (const paragraph of comment.content) visitParagraph(paragraph);
 };
 //#endregion
-export { visitDocxParagraphs };
+export { visitDocxParagraphs, visitParagraphRuns };

package/dist/docx/parser.js

@@ -9,8 +9,9 @@ import { normalizeCommentReferences } from "./commentReferenceNormalization.js";
 import { detectDocxConformanceClass } from "./conformance.js";
 import { parseCoreProperties } from "./corePropertiesParser.js";
 import { extractAllTemplateVariables, parseDocumentBody } from "./documentParser.js";
+import { normalizeDrawingIds } from "./drawingIdNormalization.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
-import { assignHeaderFooterVerbatimXml } from "./headerFooterVerbatim.js";
+import { assignHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint } from "./headerFooterVerbatim.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
 import { normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
@@ -123,6 +124,15 @@ async function parseDocx(input, options = {}) {
 		onProgress("Parsing comments...", 75);
 		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml));
 		if (comments.length > 0) documentBody.comments = comments;
+		normalizeDrawingIds({
+			documentBody,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {},
+			...footnotes !== void 0 ? { footnotes } : {},
+			...endnotes !== void 0 ? { endnotes } : {}
+		});
+		for (const header of headers?.values() ?? []) refreshHeaderFooterVerbatimFingerprint(header);
+		for (const footer of footers?.values() ?? []) refreshHeaderFooterVerbatimFingerprint(footer);
 		normalizeRenderedPageBreakHints({
 			documentBody,
 			...headers !== void 0 ? { headers } : {},

package/dist/docx/parserEnums.d.ts

@@ -19,6 +19,9 @@ declare const ParagraphAlignmentSchema: v.PicklistSchema<readonly ["left", "cent
 declare const LineSpacingRuleSchema: v.PicklistSchema<readonly ["auto", "exact", "atLeast"], undefined>;
 declare const TabStopAlignmentSchema: v.PicklistSchema<readonly ["left", "center", "right", "decimal", "bar", "clear", "num"], undefined>;
 declare const TabLeaderSchema: v.PicklistSchema<readonly ["none", "dot", "hyphen", "underscore", "heavy", "middleDot"], undefined>;
+declare const PositionalTabRelativeToSchema: v.PicklistSchema<readonly ["margin", "indent"], undefined>;
+declare const PositionalTabAlignmentSchema: v.PicklistSchema<readonly ["left", "center", "right"], undefined>;
+declare const PositionalTabLeaderSchema: v.PicklistSchema<readonly ["none", "dot", "hyphen", "underscore", "middleDot"], undefined>;
 declare const FrameXAlignSchema: v.PicklistSchema<readonly ["left", "center", "right", "inside", "outside"], undefined>;
 declare const FrameYAlignSchema: v.PicklistSchema<readonly ["top", "center", "bottom", "inside", "outside", "inline"], undefined>;
 declare const FrameWrapSchema: v.PicklistSchema<readonly ["around", "auto", "none", "notBeside", "through", "tight"], undefined>;
@@ -42,4 +45,4 @@ declare const ShapeTypeSchema: v.PicklistSchema<readonly ["rect", "roundRect", "
 declare const NumberFormatSchema: v.PicklistSchema<readonly ["decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter", "ordinal", "cardinalText", "ordinalText", "hex", "chicago", "ideographDigital", "japaneseCounting", "aiueo", "iroha", "decimalFullWidth", "decimalHalfWidth", "japaneseLegal", "japaneseDigitalTenThousand", "decimalEnclosedCircle", "decimalFullWidth2", "aiueoFullWidth", "irohaFullWidth", "decimalZero", "decimalZero3", "decimalZero4", "decimalZero5", "bullet", "ganada", "chosung", "decimalEnclosedFullstop", "decimalEnclosedParen", "decimalEnclosedCircleChinese", "ideographEnclosedCircle", "ideographTraditional", "ideographZodiac", "ideographZodiacTraditional", "taiwaneseCounting", "ideographLegalTraditional", "taiwaneseCountingThousand", "taiwaneseDigital", "chineseCounting", "chineseLegalSimplified", "chineseCountingThousand", "koreanDigital", "koreanCounting", "koreanLegal", "koreanDigital2", "vietnameseCounting", "russianLower", "russianUpper", "none", "numberInDash", "hebrew1", "hebrew2", "arabicAlpha", "arabicAbjad", "hindiVowels", "hindiConsonants", "hindiNumbers", "hindiCounting", "thaiLetters", "thaiNumbers", "thaiCounting"], undefined>;
 declare const LevelSuffixSchema: v.PicklistSchema<readonly ["tab", "space", "nothing"], undefined>;
 //#endregion
-export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontHintSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };
+export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontHintSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };

package/dist/docx/parserEnums.js

@@ -1,4 +1,4 @@
-import { BORDER_STYLE_VALUES, CONDITIONAL_STYLE_TYPE_VALUES, EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FLOATING_TABLE_X_SPEC_VALUES, FLOATING_TABLE_Y_SPEC_VALUES, FONT_HINT_VALUES, FONT_THEME_VALUES, FRAME_WRAP_VALUES, FRAME_X_ALIGN_VALUES, FRAME_Y_ALIGN_VALUES, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, LEVEL_SUFFIX_VALUES, LINE_SPACING_RULE_VALUES, NUMBER_FORMAT_VALUES, PARAGRAPH_ALIGNMENT_VALUES, SDT_LOCK_VALUES, SHADING_PATTERN_VALUES, SHAPE_OUTLINE_STYLE_VALUES, SHAPE_TYPE_VALUES, STYLE_TYPE_VALUES, TABLE_CELL_TEXT_DIRECTION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_EFFECT_VALUES, THEME_COLOR_SLOT_VALUES, UNDERLINE_STYLE_VALUES } from "../types/documentEnumValues.js";
+import { BORDER_STYLE_VALUES, CONDITIONAL_STYLE_TYPE_VALUES, EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FLOATING_TABLE_X_SPEC_VALUES, FLOATING_TABLE_Y_SPEC_VALUES, FONT_HINT_VALUES, FONT_THEME_VALUES, FRAME_WRAP_VALUES, FRAME_X_ALIGN_VALUES, FRAME_Y_ALIGN_VALUES, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, LEVEL_SUFFIX_VALUES, LINE_SPACING_RULE_VALUES, NUMBER_FORMAT_VALUES, PARAGRAPH_ALIGNMENT_VALUES, POSITIONAL_TAB_ALIGNMENT_VALUES, POSITIONAL_TAB_LEADER_VALUES, POSITIONAL_TAB_RELATIVE_TO_VALUES, SDT_LOCK_VALUES, SHADING_PATTERN_VALUES, SHAPE_OUTLINE_STYLE_VALUES, SHAPE_TYPE_VALUES, STYLE_TYPE_VALUES, TABLE_CELL_TEXT_DIRECTION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_EFFECT_VALUES, THEME_COLOR_SLOT_VALUES, UNDERLINE_STYLE_VALUES } from "../types/documentEnumValues.js";
 import * as v from "valibot";
 //#region src/docx/parserEnums.ts
 /**
@@ -45,6 +45,9 @@ const ParagraphAlignmentSchema = v.picklist(PARAGRAPH_ALIGNMENT_VALUES);
 const LineSpacingRuleSchema = v.picklist(LINE_SPACING_RULE_VALUES);
 const TabStopAlignmentSchema = v.picklist(TAB_STOP_ALIGNMENT_VALUES);
 const TabLeaderSchema = v.picklist(TAB_LEADER_VALUES);
+const PositionalTabRelativeToSchema = v.picklist(POSITIONAL_TAB_RELATIVE_TO_VALUES);
+const PositionalTabAlignmentSchema = v.picklist(POSITIONAL_TAB_ALIGNMENT_VALUES);
+const PositionalTabLeaderSchema = v.picklist(POSITIONAL_TAB_LEADER_VALUES);
 const FrameXAlignSchema = v.picklist(FRAME_X_ALIGN_VALUES);
 const FrameYAlignSchema = v.picklist(FRAME_Y_ALIGN_VALUES);
 const FrameWrapSchema = v.picklist(FRAME_WRAP_VALUES);
@@ -68,4 +71,4 @@ const ShapeTypeSchema = v.picklist(SHAPE_TYPE_VALUES);
 const NumberFormatSchema = v.picklist(NUMBER_FORMAT_VALUES);
 const LevelSuffixSchema = v.picklist(LEVEL_SUFFIX_VALUES);
 //#endregion
-export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontHintSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };
+export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontHintSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };

package/dist/docx/runConsolidator.js

@@ -161,7 +161,6 @@ function consolidateRuns(runs) {
 	return result;
 }
 function consolidateParagraphContent(content) {
-	if (content.length <= 1) return content;
 	const result = [];
 	const pendingRuns = [];
 	function flushRuns() {

package/dist/docx/runParser.js

@@ -1,4 +1,4 @@
-import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, ShadingPatternSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, ShadingPatternSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { cloneWithXmlnsDeclarations, elementToXml, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
 import { parseImage } from "./imageParser.js";
@@ -386,6 +386,19 @@ function parseTextContent(element) {
 function parseTabContent() {
 	return { type: "tab" };
 }
+function parsePositionalTabContent(element) {
+	const positional = {};
+	const relativeTo = narrowEnum(getAttribute(element, "w", "relativeTo"), PositionalTabRelativeToSchema);
+	const alignment = narrowEnum(getAttribute(element, "w", "alignment"), PositionalTabAlignmentSchema);
+	const leader = narrowEnum(getAttribute(element, "w", "leader"), PositionalTabLeaderSchema);
+	if (relativeTo !== void 0) positional.relativeTo = relativeTo;
+	if (alignment !== void 0) positional.alignment = alignment;
+	if (leader !== void 0) positional.leader = leader;
+	return {
+		type: "tab",
+		positional
+	};
+}
 /**
 * Parse break element (w:br)
 */
@@ -516,6 +529,9 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 		case "tab":
 			contents.push(parseTabContent());
 			break;
+		case "ptab":
+			contents.push(parsePositionalTabContent(child));
+			break;
 		case "br":
 			contents.push(parseBreakContent(child));
 			break;

package/dist/docx/serializer/commentSerializer.js

@@ -1,5 +1,6 @@
 import { deterministicHexId } from "../../utils/hexId.js";
 import { escapeXml } from "./xmlUtils.js";
+import { serializeTextFormatting } from "./runSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 //#region src/docx/serializer/commentSerializer.ts
 /**
@@ -7,27 +8,31 @@ import { serializeParagraph } from "./paragraphSerializer.js";
 *
 * Serializes Comment[] to OOXML comments.xml format.
 */
-const ANNOTATION_REFERENCE_XML = "<w:r><w:rPr><w:rStyle w:val=\"CommentReference\"/></w:rPr><w:annotationRef/></w:r>";
+const DEFAULT_ANNOTATION_REFERENCE_PROPERTIES = "<w:rPr><w:rStyle w:val=\"CommentReference\"/></w:rPr>";
 const PARAGRAPH_PROPERTIES_END = "</w:pPr>";
+const serializeAnnotationReference = (formatting) => {
+	return `<w:r>${formatting ? serializeTextFormatting(formatting) : DEFAULT_ANNOTATION_REFERENCE_PROPERTIES}<w:annotationRef/></w:r>`;
+};
 /** Serialize a paragraph, prepending an annotationRef run (required by Word in first paragraph of a comment) */
-function serializeParagraphWithAnnotationRef(paragraph) {
+function serializeParagraphWithAnnotationRef(paragraph, formatting) {
 	const xml = serializeParagraph(paragraph);
+	const annotationReference = serializeAnnotationReference(formatting);
 	const propertiesEnd = xml.indexOf(PARAGRAPH_PROPERTIES_END);
 	if (propertiesEnd !== -1) {
 		const contentStart = propertiesEnd + 8;
-		return `${xml.slice(0, contentStart)}${ANNOTATION_REFERENCE_XML}${xml.slice(contentStart)}`;
+		return `${xml.slice(0, contentStart)}${annotationReference}${xml.slice(contentStart)}`;
 	}
-	return xml.replace(/^<w:p(?=[\s>])[^>]*>/u, (openingTag) => `${openingTag}${ANNOTATION_REFERENCE_XML}`);
+	return xml.replace(/^<w:p(?=[\s>])[^>]*>/u, (openingTag) => `${openingTag}${annotationReference}`);
 }
 function serializeComment(comment) {
 	const attrs = [`w:id="${comment.id}"`, `w:author="${escapeXml(comment.author)}"`];
-	if (comment.initials) attrs.push(`w:initials="${escapeXml(comment.initials)}"`);
+	if (comment.initials !== void 0) attrs.push(`w:initials="${escapeXml(comment.initials)}"`);
 	if (comment.date) attrs.push(`w:date="${escapeXml(comment.date)}"`);
 	let xml = `<w:comment ${attrs.join(" ")}>`;
 	if (comment.content.length > 0) {
-		xml += serializeParagraphWithAnnotationRef(comment.content[0]);
+		xml += serializeParagraphWithAnnotationRef(comment.content[0], comment.annotationReferenceFormatting);
 		for (let i = 1; i < comment.content.length; i++) xml += serializeParagraph(comment.content[i]);
-	} else xml += "<w:p><w:r><w:rPr><w:rStyle w:val=\"CommentReference\"/></w:rPr><w:annotationRef/></w:r></w:p>";
+	} else xml += `<w:p>${serializeAnnotationReference(comment.annotationReferenceFormatting)}</w:p>`;
 	xml += "</w:comment>";
 	return xml;
 }