@stll/folio-core 0.45.0 → 0.46.0

package/dist/docx/hyperlinkParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
+import { ChildHandlers } from "./containerChildren.js";
 //#region src/docx/hyperlinkParser.d.ts
 /**
  * Parse a hyperlink element (w:hyperlink)
@@ -16,14 +17,32 @@ import { XmlElement } from "./xmlParser.js";
  * @returns Parsed Hyperlink object
  */
 declare function parseHyperlink(node: XmlElement, rels: document_d_exports.RelationshipMap | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Hyperlink;
+/** What {@link hyperlinkChildHandlers} needs to read one child of a link. */
+type HyperlinkChildContext = {
+  /** Where a parsed or captured child lands, in source order. */
+  push: (child: document_d_exports.Hyperlink["children"][number]) => void;
+  styles: StyleMap | null;
+  theme: document_d_exports.Theme | null;
+  rels: document_d_exports.RelationshipMap | null;
+  media: Map<string, document_d_exports.MediaFile> | null;
+  inScopeXmlns: Record<string, string>;
+};
 /**
- * One `w:hyperlink` child, or `null` for markup the model does not carry.
- *
- * Exposed so a caller that has to segment a hyperlink — one holding revision
- * wrappers, which the model nests the other way round — parses its plain
- * children exactly as {@link parseHyperlink} does.
+ * What a `w:hyperlink` does with every child its content model declares.
+ *
+ * `CT_Hyperlink` is `EG_PContent`, so a link may hold a permission range, a
+ * proofing error, a nested field or one of the eight custom-XML revision
+ * ranges between its runs; folio models three of the thirty-two names and
+ * used to drop the other twenty-nine off the end of a `switch`.
+ *
+ * Two callers read this one map: {@link parseHyperlink}, and the paragraph
+ * parser's revision-segmenting walk, which overrides the four
+ * `CT_RunTrackChange` wrappers because OOXML nests a revision inside a link
+ * and the model nests the link inside the revision. Everything else is
+ * decided here once, so a child one caller starts recognising is recognised
+ * by both rather than by whichever list somebody remembered to update.
  */
-declare function parseHyperlinkChild(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, inScopeXmlns: Record<string, string>): document_d_exports.Hyperlink["children"][number] | null;
+declare const hyperlinkChildHandlers: ({ push, styles, theme, rels, media, inScopeXmlns }: HyperlinkChildContext) => ChildHandlers<"w:hyperlink">;
 /**
  * Get the display text of a hyperlink
  *
@@ -112,4 +131,4 @@ declare function createExternalHyperlink(url: string, children: document_d_expor
   target?: string;
 }): document_d_exports.Hyperlink;
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };
+export { HyperlinkChildContext, createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, hyperlinkChildHandlers, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/hyperlinkParser.js

@@ -1,7 +1,9 @@
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
+import { CAPTURE, dispatchChildren, withPreservedChildren } from "./containerChildren.js";
+import { preserveInlineChild, preservedInlineCapture } from "./preservedRunContent.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { parseRun } from "./runParser.js";
-import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { getAttribute, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/hyperlinkParser.ts
 /**
 * Parse bookmark start (w:bookmarkStart)
@@ -68,27 +70,83 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
-	for (const child of getChildElements(node)) {
-		const parsed = parseHyperlinkChild(child, styles, theme, rels, media, inScopeXmlns);
-		if (parsed) hyperlink.children.push(parsed);
-	}
+	const children = [];
+	hyperlink.children = withPreservedChildren(children, dispatchChildren({
+		element: node,
+		container: "w:hyperlink",
+		modelledCount: () => children.length,
+		handlers: hyperlinkChildHandlers({
+			push: (child) => {
+				children.push(child);
+			},
+			styles,
+			theme,
+			rels,
+			media,
+			inScopeXmlns
+		})
+	}), preservedInlineCapture);
 	return hyperlink;
 }
 /**
-* One `w:hyperlink` child, or `null` for markup the model does not carry.
+* What a `w:hyperlink` does with every child its content model declares.
+*
+* `CT_Hyperlink` is `EG_PContent`, so a link may hold a permission range, a
+* proofing error, a nested field or one of the eight custom-XML revision
+* ranges between its runs; folio models three of the thirty-two names and
+* used to drop the other twenty-nine off the end of a `switch`.
 *
-* Exposed so a caller that has to segment a hyperlink — one holding revision
-* wrappers, which the model nests the other way round — parses its plain
-* children exactly as {@link parseHyperlink} does.
+* Two callers read this one map: {@link parseHyperlink}, and the paragraph
+* parser's revision-segmenting walk, which overrides the four
+* `CT_RunTrackChange` wrappers because OOXML nests a revision inside a link
+* and the model nests the link inside the revision. Everything else is
+* decided here once, so a child one caller starts recognising is recognised
+* by both rather than by whichever list somebody remembered to update.
 */
-function parseHyperlinkChild(node, styles, theme, rels, media, inScopeXmlns) {
-	switch (getLocalName(node.name)) {
-		case "r": return parseRun(node, styles, theme, rels, media, inScopeXmlns);
-		case "bookmarkStart": return parseBookmarkStart(node);
-		case "bookmarkEnd": return parseBookmarkEnd(node);
-		default: return null;
-	}
-}
+const hyperlinkChildHandlers = ({ push, styles, theme, rels, media, inScopeXmlns }) => ({
+	r: (child) => {
+		push(parseRun(child, styles, theme, rels, media, inScopeXmlns));
+	},
+	bookmarkStart: (child) => {
+		push(parseBookmarkStart(child));
+	},
+	bookmarkEnd: (child) => {
+		push(parseBookmarkEnd(child));
+	},
+	customXml: (child) => {
+		push(preserveInlineChild(child));
+	},
+	smartTag: (child) => {
+		push(preserveInlineChild(child));
+	},
+	del: CAPTURE,
+	ins: CAPTURE,
+	moveFrom: CAPTURE,
+	moveTo: CAPTURE,
+	bdo: CAPTURE,
+	commentRangeEnd: CAPTURE,
+	commentRangeStart: CAPTURE,
+	customXmlDelRangeEnd: CAPTURE,
+	customXmlDelRangeStart: CAPTURE,
+	customXmlInsRangeEnd: CAPTURE,
+	customXmlInsRangeStart: CAPTURE,
+	customXmlMoveFromRangeEnd: CAPTURE,
+	customXmlMoveFromRangeStart: CAPTURE,
+	customXmlMoveToRangeEnd: CAPTURE,
+	customXmlMoveToRangeStart: CAPTURE,
+	dir: CAPTURE,
+	fldSimple: CAPTURE,
+	hyperlink: CAPTURE,
+	moveFromRangeEnd: CAPTURE,
+	moveFromRangeStart: CAPTURE,
+	moveToRangeEnd: CAPTURE,
+	moveToRangeStart: CAPTURE,
+	permEnd: CAPTURE,
+	permStart: CAPTURE,
+	proofErr: CAPTURE,
+	sdt: CAPTURE,
+	subDoc: CAPTURE
+});
 /**
 * Get the display text of a hyperlink
 *
@@ -219,4 +277,4 @@ function createExternalHyperlink(url, children, options) {
 	};
 }
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, hyperlinkChildHandlers, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/imageParser.js

@@ -1,3 +1,4 @@
+import { normalizeImageLuminancePercent } from "../utils/imageLuminance.js";
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
@@ -6,9 +7,12 @@ import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
 import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
+import { percentageSpelling } from "./transitionalSpelling.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { findByFullName, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getChildElements, getLocalName, getNamespaceUri, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/imageParser.ts
+const DRAWINGML_MAIN_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
+const FIXED_PERCENTAGE = /^-?\d+$/u;
 /**
 * Convert rotation value (1/60000 of a degree) to degrees
 *
@@ -16,7 +20,7 @@ import { findByFullName, findChild, findChildByNamespaceUri, findChildrenByNames
 * @returns Rotation in degrees
 */
 function rotToDegrees(rot) {
-	if (!rot) return;
+	if (rot === null || rot === void 0) return;
 	const val = Number.parseInt(rot, 10);
 	if (Number.isNaN(val)) return;
 	return val / 6e4;
@@ -134,15 +138,14 @@ function parseDocProps(docPr) {
 */
 function parseTransform(xfrm) {
 	if (!xfrm) return;
-	const rot = getAttribute(xfrm, null, "rot");
-	const flipH = parseOnOffValue(getAttribute(xfrm, null, "flipH")) === true;
-	const flipV = parseOnOffValue(getAttribute(xfrm, null, "flipV")) === true;
-	const rotation = rotToDegrees(rot);
-	if (rotation === void 0 && !flipH && !flipV) return;
+	const flipH = parseOnOffValue(getAttribute(xfrm, null, "flipH"));
+	const flipV = parseOnOffValue(getAttribute(xfrm, null, "flipV"));
+	const rotation = rotToDegrees(getAttribute(xfrm, null, "rot"));
+	if (rotation === void 0 && flipH === void 0 && flipV === void 0) return;
 	const transform = {};
 	if (rotation !== void 0) transform.rotation = rotation;
-	if (flipH) transform.flipH = true;
-	if (flipV) transform.flipV = true;
+	if (flipH !== void 0) transform.flipH = flipH;
+	if (flipV !== void 0) transform.flipV = flipV;
 	return transform;
 }
 /**
@@ -219,6 +222,24 @@ function parseImageOpacity(blip) {
 	if (amt === void 0 || amt >= 1e5) return;
 	return Math.max(0, amt / 1e5);
 }
+const parseLuminancePercent = (luminance, attribute) => {
+	const raw = getAttribute(luminance, null, attribute);
+	if (raw === null) return;
+	const percent = percentageSpelling(raw) ?? (FIXED_PERCENTAGE.test(raw.trim()) ? Number(raw) / 1e3 : void 0);
+	return percent === void 0 || !Number.isFinite(percent) ? void 0 : normalizeImageLuminancePercent(percent);
+};
+/** Parse DrawingML `a:lum` into signed percentage values, preserving explicit zeroes. */
+function parseImageLuminance(blip) {
+	const luminance = findChildByNamespaceUri(blip, DRAWINGML_MAIN_NAMESPACE_URIS, "lum");
+	if (!luminance) return;
+	const brightness = parseLuminancePercent(luminance, "bright");
+	const contrast = parseLuminancePercent(luminance, "contrast");
+	if (brightness === void 0 && contrast === void 0) return;
+	return {
+		...brightness === void 0 ? {} : { brightness },
+		...contrast === void 0 ? {} : { contrast }
+	};
+}
 /**
 * Extract rId from a:blip element.
 *
@@ -350,6 +371,7 @@ function parseInline(inlineEl, rels, media) {
 	const rId = extractBlipRId(blip);
 	const crop = parseImageCrop(blipFill);
 	const opacity = parseImageOpacity(blip);
+	const effects = parseImageLuminance(blip);
 	const imageData = resolveImageData(rId, rels, media);
 	const transform = parseTransform(findPictureTransform(inlineEl));
 	const distT = parseNumericAttribute(inlineEl, null, "distT") ?? void 0;
@@ -382,6 +404,7 @@ function parseInline(inlineEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (effects !== void 0) image.effects = effects;
 	if (frameLocks) image.frameLocks = frameLocks;
 	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
 	if (hlink.status === "resolved") {
@@ -434,6 +457,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const rId = extractBlipRId(blip);
 	const crop = parseImageCrop(blipFill);
 	const opacity = parseImageOpacity(blip);
+	const effects = parseImageLuminance(blip);
 	const imageData = resolveImageData(rId, rels, media);
 	const transform = parseTransform(findPictureTransform(anchorEl));
 	const image = {
@@ -458,6 +482,7 @@ function parseAnchor(anchorEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (effects !== void 0) image.effects = effects;
 	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;

package/dist/docx/inlineWrapperContent.d.ts

@@ -0,0 +1,85 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/inlineWrapperContent.d.ts
+/**
+ * What a run-level tracked-change wrapper keeps inside itself (CT_RunTrackChange).
+ *
+ * Runs, links, fields, bookmark boundaries, equations, nested revisions and
+ * markup folio does not model.
+ *
+ * The transparent wrappers are admitted too: `w:bdo` / `w:dir` state how their
+ * content is laid out, and `w:sdt` states what the content is bound to.
+ * Neither says anything about the revision, so lifting one out of a revision
+ * takes its text out of the revision with it.
+ *
+ * The range markers are not: a `w:commentRangeStart` or `w:moveFromRangeStart`
+ * inside a revision is a marker the revision does not own, and the pairing
+ * passes read it as a paragraph-level sibling.
+ */
+declare const TRACKED_CHANGE_WRAPPER_CONTENT: {
+  readonly inlineWrapper: true;
+  readonly bookmarkEnd: true;
+  readonly bookmarkStart: true;
+  readonly complexField: true;
+  readonly deletion: true;
+  readonly hyperlink: true;
+  readonly inlineSdt: true;
+  readonly insertion: true;
+  readonly mathEquation: true;
+  readonly moveFrom: true;
+  readonly moveTo: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly simpleField: true;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+};
+/**
+ * What an inline content control keeps inside `<w:sdtContent>`.
+ *
+ * Mirror of upstream eigenpal/docx-editor PR #482 (commit 29f95751d), plus
+ * the bidirectional wrapper: OOXML allows runs, hyperlinks, simple/complex
+ * fields, nested SDTs, tracked insertions/deletions/moves, math, markup folio
+ * does not model, and the bidirectional controls directly inside
+ * `<w:sdtContent>`. Bookmarks and range markers are lifted out as siblings of
+ * the SDT so the control itself stays valid.
+ */
+declare const INLINE_SDT_CONTENT: {
+  readonly inlineWrapper: true;
+  readonly complexField: true;
+  readonly deletion: true;
+  readonly hyperlink: true;
+  readonly inlineSdt: true;
+  readonly insertion: true;
+  readonly mathEquation: true;
+  readonly moveFrom: true;
+  readonly moveTo: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly simpleField: true;
+  readonly bookmarkEnd: false;
+  readonly bookmarkStart: false;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+};
+/**
+ * Whether a revision wrapper keeps this content inside itself.
+ *
+ * Generic in the input so a caller that has already narrowed its content
+ * keeps that narrowing: filtering a list the bidirectional wrappers are
+ * already flattened out of must not put one back into the result type.
+ */
+declare const isTrackedChangeWrapperChild: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.TrackedRunContent>;
+/** Whether an inline content control keeps this content inside `<w:sdtContent>`. */
+declare const isInlineSdtContent: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.InlineSdt["content"][number]>;
+//#endregion
+export { INLINE_SDT_CONTENT, TRACKED_CHANGE_WRAPPER_CONTENT, isInlineSdtContent, isTrackedChangeWrapperChild };

package/dist/docx/inlineWrapperContent.js

@@ -0,0 +1,84 @@
+//#region src/docx/inlineWrapperContent.ts
+/**
+* What a run-level tracked-change wrapper keeps inside itself (CT_RunTrackChange).
+*
+* Runs, links, fields, bookmark boundaries, equations, nested revisions and
+* markup folio does not model.
+*
+* The transparent wrappers are admitted too: `w:bdo` / `w:dir` state how their
+* content is laid out, and `w:sdt` states what the content is bound to.
+* Neither says anything about the revision, so lifting one out of a revision
+* takes its text out of the revision with it.
+*
+* The range markers are not: a `w:commentRangeStart` or `w:moveFromRangeStart`
+* inside a revision is a marker the revision does not own, and the pairing
+* passes read it as a paragraph-level sibling.
+*/
+const TRACKED_CHANGE_WRAPPER_CONTENT = {
+	inlineWrapper: true,
+	bookmarkEnd: true,
+	bookmarkStart: true,
+	complexField: true,
+	deletion: true,
+	hyperlink: true,
+	inlineSdt: true,
+	insertion: true,
+	mathEquation: true,
+	moveFrom: true,
+	moveTo: true,
+	preservedInline: true,
+	run: true,
+	simpleField: true,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false
+};
+/**
+* What an inline content control keeps inside `<w:sdtContent>`.
+*
+* Mirror of upstream eigenpal/docx-editor PR #482 (commit 29f95751d), plus
+* the bidirectional wrapper: OOXML allows runs, hyperlinks, simple/complex
+* fields, nested SDTs, tracked insertions/deletions/moves, math, markup folio
+* does not model, and the bidirectional controls directly inside
+* `<w:sdtContent>`. Bookmarks and range markers are lifted out as siblings of
+* the SDT so the control itself stays valid.
+*/
+const INLINE_SDT_CONTENT = {
+	inlineWrapper: true,
+	complexField: true,
+	deletion: true,
+	hyperlink: true,
+	inlineSdt: true,
+	insertion: true,
+	mathEquation: true,
+	moveFrom: true,
+	moveTo: true,
+	preservedInline: true,
+	run: true,
+	simpleField: true,
+	bookmarkEnd: false,
+	bookmarkStart: false,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false
+};
+/**
+* Whether a revision wrapper keeps this content inside itself.
+*
+* Generic in the input so a caller that has already narrowed its content
+* keeps that narrowing: filtering a list the bidirectional wrappers are
+* already flattened out of must not put one back into the result type.
+*/
+const isTrackedChangeWrapperChild = (content) => TRACKED_CHANGE_WRAPPER_CONTENT[content.type];
+/** Whether an inline content control keeps this content inside `<w:sdtContent>`. */
+const isInlineSdtContent = (content) => INLINE_SDT_CONTENT[content.type];
+//#endregion
+export { INLINE_SDT_CONTENT, TRACKED_CHANGE_WRAPPER_CONTENT, isInlineSdtContent, isTrackedChangeWrapperChild };

package/dist/docx/normalizeBaseDirection.js

@@ -44,13 +44,22 @@ const normalizeTable = (table, styles) => ({
 		...row,
 		cells: row.cells.map((cell) => ({
 			...cell,
-			content: cell.content.map((block) => block.type === "paragraph" ? normalizeParagraph(block, styles) : normalizeTable(block, styles))
+			content: cell.content.map((block) => normalizeCellBlock(block, styles))
 		}))
 	}))
 });
+const normalizeCellBlock = (block, styles) => {
+	switch (block.type) {
+		case "paragraph": return normalizeParagraph(block, styles);
+		case "table": return normalizeTable(block, styles);
+		case "preservedBlock": return block;
+		default: return block;
+	}
+};
 const normalizeBlocks = (blocks, styles) => blocks.map((block) => {
 	if (block.type === "paragraph") return normalizeParagraph(block, styles);
 	if (block.type === "table") return normalizeTable(block, styles);
+	if (block.type === "preservedBlock") return block;
 	return {
 		...block,
 		content: normalizeBlocks(block.content, styles)

package/dist/docx/paraIdAttribute.d.ts

@@ -0,0 +1,21 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/paraIdAttribute.d.ts
+/**
+ * The namespaces a paraId-valued attribute may be written in: the Word 2010,
+ * 2012 and 2018 wordml extensions.
+ *
+ * The 2018 URI is read from the serializer's table rather than retyped, so the
+ * spelling folio writes and the spelling it accepts cannot drift.
+ */
+declare const PARA_ID_NAMESPACE_URIS: ReadonlySet<string>;
+/** The paraId this element carries, or `undefined` when it carries none. */
+declare const paraIdAttribute: (element: XmlElement) => string | undefined;
+/** The paraId of the parent this element names, by the same rule. */
+declare const paraIdParentAttribute: (element: XmlElement) => string | undefined;
+/**
+ * The textId this element carries: a paragraph identity written beside
+ * `paraId`, in the same namespaces and by the same rule.
+ */
+declare const textIdAttribute: (element: XmlElement) => string | undefined;
+//#endregion
+export { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute, textIdAttribute };

package/dist/docx/paraIdAttribute.js

@@ -0,0 +1,64 @@
+import { OOXML_NAMESPACES } from "./serializer/partNamespaces.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, getAttributeByNamespaceUri } from "./xmlParser.js";
+//#region src/docx/paraIdAttribute.ts
+/**
+* The one reader for "the paraId written on this element".
+*
+* A `paraId` is a join key: `w15:commentEx/@w15:paraId`,
+* `w16cex:comment/@w16cex:paraId` and `w15:paraIdParent` all name a paragraph
+* through the `w14:paraId` it carries. Three Word generations write the same
+* key under three prefixes, and a producer is free to bind any of those
+* namespaces to a prefix of its own choosing, so the key must be resolved by
+* namespace URI. Resolving it by local name alone is worse than missing it: an
+* unrelated `vendor:paraId` would key a comment into another thread and carry
+* that thread's date, parent and resolved state.
+*
+* Every reader of the key calls this, so no call site can come to disagree
+* with another about which attribute is a paraId.
+*/
+/**
+* The namespaces a paraId-valued attribute may be written in: the Word 2010,
+* 2012 and 2018 wordml extensions.
+*
+* The 2018 URI is read from the serializer's table rather than retyped, so the
+* spelling folio writes and the spelling it accepts cannot drift.
+*/
+const PARA_ID_NAMESPACE_URIS = /* @__PURE__ */ new Set([
+	NAMESPACES.w14,
+	NAMESPACES.w15,
+	OOXML_NAMESPACES.w16cex.uri
+]);
+/**
+* The conventional prefixes, read literally as a last resort.
+*
+* A part that writes `w14:paraId` without declaring `xmlns:w14` is malformed,
+* and no URI lookup can resolve it; Word reads those files, so folio does too.
+*/
+const CONVENTIONAL_PARA_ID_PREFIXES = [
+	"w14",
+	"w15",
+	"w16cex"
+];
+const paraIdValuedAttribute = (element, localName) => {
+	const byUri = getAttributeByNamespaceUri(element, PARA_ID_NAMESPACE_URIS, localName);
+	if (byUri !== null) return byUri;
+	for (const prefix of CONVENTIONAL_PARA_ID_PREFIXES) {
+		const literal = element.attributes?.[`${prefix}:${localName}`];
+		if (literal !== void 0) return String(literal);
+	}
+	const inWordprocessingml = getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, localName);
+	if (inWordprocessingml !== null) return inWordprocessingml;
+	const literalW = element.attributes?.[`w:${localName}`];
+	return literalW === void 0 ? void 0 : String(literalW);
+};
+/** The paraId this element carries, or `undefined` when it carries none. */
+const paraIdAttribute = (element) => paraIdValuedAttribute(element, "paraId");
+/** The paraId of the parent this element names, by the same rule. */
+const paraIdParentAttribute = (element) => paraIdValuedAttribute(element, "paraIdParent");
+/**
+* The textId this element carries: a paragraph identity written beside
+* `paraId`, in the same namespaces and by the same rule.
+*/
+const textIdAttribute = (element) => paraIdValuedAttribute(element, "textId");
+//#endregion
+export { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute, textIdAttribute };

package/dist/docx/paragraphParser.d.ts

@@ -1,7 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/paragraphParser.d.ts
 /**
  * Parse paragraph formatting properties (w:pPr)