@stll/folio-core 0.33.2 → 0.34.0

package/dist/docx/paragraphParser.js

@@ -763,6 +763,47 @@ function parseSimpleField(node, styles, theme, rels, media, rootXmlns = {}) {
 function hasRunPayloadElement(runElement) {
 	return getChildElements(runElement).some((child) => !matchesName(child, "w", "rPr"));
 }
+const LEGACY_FORM_CHECKBOX_GLYPHS = {
+	checked: "☒",
+	unchecked: "☐"
+};
+const LEGACY_FORM_CHECKBOX_INSTRUCTION = "FORMCHECKBOX";
+function getLegacyFormCheckboxDisplay(runElement) {
+	const fieldChar = findChild(runElement, "w", "fldChar");
+	const fieldData = fieldChar ? findChild(fieldChar, "w", "ffData") : null;
+	const checkBox = fieldData ? findChild(fieldData, "w", "checkBox") : null;
+	if (!checkBox) return;
+	const checked = findChild(checkBox, "w", "checked");
+	const defaultChecked = findChild(checkBox, "w", "default");
+	let isChecked = defaultChecked ? parseBooleanElement(defaultChecked) : false;
+	if (checked) isChecked = parseBooleanElement(checked);
+	const explicitSize = parseNumericAttribute(findChild(checkBox, "w", "size"), "w", "val");
+	const text = isChecked ? LEGACY_FORM_CHECKBOX_GLYPHS.checked : LEGACY_FORM_CHECKBOX_GLYPHS.unchecked;
+	if (explicitSize === void 0) return { text };
+	return {
+		text,
+		fontSize: explicitSize
+	};
+}
+function createLegacyFormCheckboxResultRun(display, inheritedFormatting) {
+	const run = {
+		type: "run",
+		content: [{
+			type: "text",
+			text: display.text
+		}]
+	};
+	const hasInheritedFormatting = inheritedFormatting !== void 0 && Object.keys(inheritedFormatting).length > 0;
+	if (display.fontSize !== void 0) run.formatting = hasInheritedFormatting ? {
+		...inheritedFormatting,
+		fontSize: display.fontSize
+	} : { fontSize: display.fontSize };
+	else if (hasInheritedFormatting) run.formatting = inheritedFormatting;
+	return run;
+}
+function isLegacyFormCheckboxInstruction(instruction) {
+	return instruction.trim().split(/\s+/u).at(0)?.toUpperCase() === LEGACY_FORM_CHECKBOX_INSTRUCTION;
+}
 /**
 * Parse all content within a paragraph
 *
@@ -779,6 +820,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 	let afterSeparator = false;
 	let complexFieldLock = false;
 	let complexFieldDirty = false;
+	let complexFieldFallbackDisplay;
 	let complexFieldFormatting;
 	for (const child of children) {
 		const localName = getLocalName(child.name);
@@ -790,6 +832,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				let hasFieldBegin = false;
 				let beginFldLock = false;
 				let beginDirty = false;
+				const beginFallbackDisplay = getLegacyFormCheckboxDisplay(runElement);
 				let hasFieldSeparate = false;
 				let hasFieldEnd = false;
 				let endOriginalValue;
@@ -816,6 +859,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 					complexFieldResultRuns = [];
 					complexFieldLock = beginFldLock;
 					complexFieldDirty = beginDirty;
+					complexFieldFallbackDisplay = beginFallbackDisplay;
 					complexFieldFormatting = run.formatting;
 				}
 				if (inComplexField) {
@@ -840,6 +884,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 					}
 					if (hasFieldEnd) {
 						let resultRuns = complexFieldResultRuns;
+						if (resultRuns.length === 0 && complexFieldFallbackDisplay !== void 0 && isLegacyFormCheckboxInstruction(complexFieldInstr)) resultRuns = [createLegacyFormCheckboxResultRun(complexFieldFallbackDisplay, complexFieldFormatting)];
 						if (resultRuns.length === 0 && !afterSeparator && endOriginalValue !== void 0) resultRuns = [{
 							type: "run",
 							content: [{

package/dist/docx/serializer/headerFooterSerializer.js

@@ -1,4 +1,7 @@
 import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
+import { isEmptyParagraph } from "../paragraphParser.js";
+import { captureVerbatimXml } from "../verbatimCapture.js";
+import { getLocalName, parseXmlDocument } from "../xmlParser.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
@@ -53,8 +56,16 @@ function serializeHeaderFooter(hf, source) {
 	const watermarkInsertIndex = hf.watermarkBlockIndex !== void 0 ? Math.max(0, Math.min(hf.watermarkBlockIndex, hf.content.length)) : 0;
 	const blocksXml = hf.content.map((block) => serializeBlock(block));
 	let contentXml;
-	if (watermarkXml) contentXml = blocksXml.slice(0, watermarkInsertIndex).join("") + watermarkXml + blocksXml.slice(watermarkInsertIndex).join("");
-	else contentXml = blocksXml.join("");
+	if (watermarkXml) {
+		const watermarkHost = hf.content.at(watermarkInsertIndex);
+		const rawWatermarkXml = hf.rawWatermarkXml;
+		const mergesIntoRetainedHost = rawWatermarkXml !== void 0 && watermarkHost?.type === "paragraph" && isEmptyParagraph(watermarkHost);
+		if (mergesIntoRetainedHost) blocksXml[watermarkInsertIndex] = serializeRawWatermarkIntoHost({
+			hostXml: blocksXml[watermarkInsertIndex] ?? serializeParagraph(watermarkHost),
+			rawWatermarkXml
+		});
+		contentXml = blocksXml.slice(0, watermarkInsertIndex).join("") + (mergesIntoRetainedHost ? "" : watermarkXml) + blocksXml.slice(watermarkInsertIndex).join("");
+	} else contentXml = blocksXml.join("");
 	if (!contentXml) contentXml = "<w:p><w:pPr/></w:p>";
 	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
 		partPath: source?.path ?? `word/${hf.type}.xml`,
@@ -64,6 +75,14 @@ function serializeHeaderFooter(hf, source) {
 		body: contentXml
 	});
 }
+function serializeRawWatermarkIntoHost({ hostXml, rawWatermarkXml }) {
+	const rawHost = parseXmlDocument(rawWatermarkXml);
+	if (!rawHost || getLocalName(rawHost.name ?? "") !== "p") return rawWatermarkXml;
+	const watermarkContent = (rawHost.elements ?? []).filter((child) => child.type === "element" && getLocalName(child.name ?? "") !== "pPr").map((child) => captureVerbatimXml(child)).join("");
+	if (!watermarkContent) return rawWatermarkXml;
+	const namespaceAttributes = Object.entries(rawHost.attributes ?? {}).filter(([name, value]) => value !== void 0 && (name === "xmlns" || name.startsWith("xmlns:"))).map(([name, value]) => ` ${name}="${escapeXml(String(value))}"`).join("");
+	return hostXml.replace(/^<w:p(?=[\s>])/u, `<w:p${namespaceAttributes}`).replace("</w:p>", `${watermarkContent}</w:p>`);
+}
 function serializeWatermarkParagraph(hf) {
 	if (hf.rawWatermarkXml) return hf.rawWatermarkXml;
 	if (hf.watermark) return synthesizeWatermarkParagraph(hf.watermark);

package/dist/docx/serializer/paragraphSerializer.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../../types/document.js";
 //#region src/docx/serializer/paragraphSerializer.d.ts
-declare function serializeParagraphFormatting(formatting: document_d_exports.ParagraphFormatting | undefined, propertyChanges?: document_d_exports.ParagraphPropertyChange[], pPrMark?: document_d_exports.ParagraphMarkChange): string;
+declare function serializeParagraphFormatting(formatting: document_d_exports.ParagraphFormatting | undefined, propertyChanges?: document_d_exports.ParagraphPropertyChange[], paragraphMarkChange?: document_d_exports.ParagraphMarkChange): string;
 /**
  * Serialize a paragraph to OOXML XML (w:p)
  *

package/dist/docx/serializer/paragraphSerializer.js

@@ -140,7 +140,7 @@ function serializeParagraphMarkChange(mark) {
 	const attrs = serializeTrackedChangeAttrs(mark.info);
 	return `<w:${mark.kind} ${attrs}/>`;
 }
-function serializeParagraphFormatting(formatting, propertyChanges, pPrMark) {
+const serializeParagraphFormattingWithOptions = (formatting, { propertyChanges, paragraphMarkChange, sectionProperties } = {}) => {
 	const parts = [];
 	const pushToggle = (name, value) => {
 		if (value === true) parts.push(`<w:${name}/>`);
@@ -175,14 +175,22 @@ function serializeParagraphFormatting(formatting, propertyChanges, pPrMark) {
 		pushToggle("contextualSpacing", formatting.contextualSpacing);
 		if (formatting.alignment) parts.push(`<w:jc w:val="${formatting.alignment}"/>`);
 		if (formatting.outlineLevel !== void 0) parts.push(`<w:outlineLvl w:val="${formatting.outlineLevel}"/>`);
-		if (pPrMark || formatting.runProperties || formatting.runInWithNext) {
-			const fullInner = `${pPrMark ? serializeParagraphMarkChange(pPrMark) : ""}${formatting.runProperties ? extractRPrInner(serializeTextFormatting(formatting.runProperties)) : ""}${formatting.runInWithNext ? "<w:specVanish/>" : ""}`;
+		if (paragraphMarkChange || formatting.runProperties || formatting.runInWithNext) {
+			const fullInner = `${paragraphMarkChange ? serializeParagraphMarkChange(paragraphMarkChange) : ""}${formatting.runProperties ? extractRPrInner(serializeTextFormatting(formatting.runProperties)) : ""}${formatting.runInWithNext ? "<w:specVanish/>" : ""}`;
 			if (fullInner.length > 0) parts.push(`<w:rPr>${fullInner}</w:rPr>`);
 		}
-	} else if (pPrMark) parts.push(`<w:rPr>${serializeParagraphMarkChange(pPrMark)}</w:rPr>`);
+	} else if (paragraphMarkChange) parts.push(`<w:rPr>${serializeParagraphMarkChange(paragraphMarkChange)}</w:rPr>`);
+	parts.push(serializeSectionProperties(sectionProperties));
 	if (propertyChanges && propertyChanges.length > 0) parts.push(...propertyChanges.map((change) => serializeParagraphPropertyChange(change)));
-	if (parts.length === 0) return "";
-	return `<w:pPr>${parts.join("")}</w:pPr>`;
+	const inner = parts.join("");
+	if (inner.length === 0) return "";
+	return `<w:pPr>${inner}</w:pPr>`;
+};
+function serializeParagraphFormatting(formatting, propertyChanges, paragraphMarkChange) {
+	return serializeParagraphFormattingWithOptions(formatting, {
+		propertyChanges,
+		paragraphMarkChange
+	});
 }
 function extractPPrInner(pPrXml) {
 	if (!pPrXml.startsWith("<w:pPr>") || !pPrXml.endsWith("</w:pPr>")) return "";
@@ -486,9 +494,11 @@ function serializeParagraph(paragraph) {
 	if (paragraph.paraId) attrs.push(`w14:paraId="${escapeXml(paragraph.paraId)}"`);
 	if (paragraph.textId) attrs.push(`w14:textId="${escapeXml(paragraph.textId)}"`);
 	const attrsStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
-	const pPrXml = serializeParagraphFormatting(paragraph.formatting, paragraph.propertyChanges, paragraph.pPrMark);
-	const sectionPropertiesXml = serializeSectionProperties(paragraph.sectionProperties);
-	if (pPrXml || sectionPropertiesXml) parts.push(`<w:pPr>${extractPPrInner(pPrXml)}${sectionPropertiesXml}</w:pPr>`);
+	parts.push(serializeParagraphFormattingWithOptions(paragraph.formatting, {
+		propertyChanges: paragraph.propertyChanges,
+		paragraphMarkChange: paragraph.pPrMark,
+		sectionProperties: paragraph.sectionProperties
+	}));
 	const explicitCommentReferenceIds = /* @__PURE__ */ new Set();
 	for (const content of paragraph.content) if (content.type === "commentReference") explicitCommentReferenceIds.add(content.id);
 	let pendingRenderedPageBreak = paragraph.renderedPageBreakBefore === true;

package/dist/docx/settingsParser.js

@@ -55,6 +55,9 @@ function parseSettings(xml) {
 	if (compatibilityMode !== void 0) settings.compatibilityMode = compatibilityMode;
 	const splitPageBreakAndParagraphMark = compat ? findChild(compat, "w", "splitPgBreakAndParaMark") : null;
 	if (splitPageBreakAndParagraphMark && parseBooleanElement(splitPageBreakAndParagraphMark)) settings.splitPageBreakAndParagraphMark = true;
+	const wordprocessingCompat = root ? findChildByNamespaceUri(root, WORDPROCESSINGML_NAMESPACE_URIS, "compat") : null;
+	const adjustLineHeightInTable = wordprocessingCompat ? findChildByNamespaceUri(wordprocessingCompat, WORDPROCESSINGML_NAMESPACE_URIS, "adjustLineHeightInTable") : null;
+	if (adjustLineHeightInTable && parseBooleanElement(adjustLineHeightInTable)) settings.adjustLineHeightInTable = true;
 	const applyBreakingRules = compat ? findChild(compat, "w", "applyBreakingRules") : null;
 	const useLegacyEthiopicAmharicRules = applyBreakingRules !== null && parseBooleanElement(applyBreakingRules);
 	if (noLineBreaksBefore || noLineBreaksAfter || useLegacyEthiopicAmharicRules) settings.lineBreakRules = {

package/dist/docx/watermarkParser.d.ts

@@ -14,10 +14,8 @@ type ParsedWatermark = {
   hostingParagraph: XmlElement;
   /**
    * Index where the watermark paragraph sat among block-level siblings
-   * (`w:p` / `w:tbl`) in the source header. After the host paragraph is
-   * filtered out of `content`, the serializer inserts the watermark
-   * back at this index so a header that originally placed the
-   * watermark after visible text rounds-trips with the same flow.
+   * (`w:p` / `w:tbl` / `w:sdt`) in the source header. The serializer uses
+   * this index to replace the retained host paragraph with watermark XML.
    */
   blockIndex: number;
 };

package/dist/docx/watermarkParser.js

@@ -59,11 +59,9 @@ function parseWatermark(header) {
 	}
 }
 /**
-* Index of `target` among block-level children of `header` (only
-* `w:p` and `w:tbl` count as blocks). Since the hosting paragraph
-* is filtered out of `content` after parse, this is the index the
-* serializer needs to splice the watermark XML back into so the
-* header rounds-trips with the same flow as the source.
+* Index of `target` among block-level children of `header`. Keep this list
+* aligned with `parseBlockContent`, which emits paragraphs, tables, and
+* block-level content controls as one content item each.
 */
 function blockIndexOf(header, target) {
 	let blockIdx = 0;
@@ -71,7 +69,7 @@ function blockIndexOf(header, target) {
 		if (child === target) return blockIdx;
 		if (child.type !== "element") continue;
 		const local = getLocalName(child.name ?? "");
-		if (local === "p" || local === "tbl") blockIdx++;
+		if (local === "p" || local === "tbl" || local === "sdt") blockIdx++;
 	}
 	return 0;
 }

package/dist/headless-layout.js

@@ -1,3 +1,5 @@
+import { resolveDocumentGridLinePitch } from "./docx/documentGrid.js";
+import { formatOoxmlCounter } from "./docx/ooxmlCounterFormatter.js";
 import { parseDocx } from "./docx/parser.js";
 import { buildHeaderFooterFieldValues } from "./fields/resolveFieldValues.js";
 import { extractEmbeddedFonts } from "./fonts/embeddedFonts.js";
@@ -50,6 +52,11 @@ import { createHash } from "node:crypto";
 * backend in a browser); this module refuses to guess, because a silently
 * wrong provider produces a plausible layout that is wrong everywhere.
 */
+const formatEndnoteTexts = (numbers, formatNumber) => {
+	const texts = /* @__PURE__ */ new Map();
+	for (const [id, displayNumber] of numbers) texts.set(id, formatNumber(displayNumber));
+	return texts;
+};
 var HeadlessLayoutError = class extends TaggedError("HeadlessLayoutError") {};
 /**
 * Stories this entry still does not lay out, keyed by story so the map is total
@@ -93,6 +100,8 @@ const buildFlowOptions = (document, pageContentHeight) => {
 		...settings.consecutiveHyphenLimit === void 0 ? {} : { consecutiveLineLimit: settings.consecutiveHyphenLimit },
 		...settings.hyphenationZoneTwips === void 0 ? {} : { hyphenationZoneTwips: settings.hyphenationZoneTwips }
 	};
+	const finalSectionDocumentGridLinePitchTwips = resolveDocumentGridLinePitch(document.package.document.sections?.at(-1)?.properties.docGrid);
+	if (finalSectionDocumentGridLinePitchTwips !== void 0) options.finalSectionDocumentGridLinePitchTwips = finalSectionDocumentGridLinePitchTwips;
 	return options;
 };
 /**
@@ -237,9 +246,12 @@ const layoutDocxHeadless = async (input, options = {}) => {
 		const footnotes = document.package.footnotes ?? [];
 		const endnotes = document.package.endnotes ?? [];
 		const footnoteRefs = collectFootnoteRefs(authored);
+		const footnoteNumbers = computeNoteDisplayNumbers(footnotes, footnoteRefs.map((ref) => ref.footnoteId));
+		const endnoteNumbers = computeNoteDisplayNumbers(endnotes, collectEndnoteRefs(authored).map((ref) => ref.endnoteId));
+		const endnoteNumberFormat = finalSection?.endnotePr?.numFmt ?? "lowerRoman";
 		const blocks = remapNoteMarkerText(authored, {
-			footnoteNumbers: computeNoteDisplayNumbers(footnotes, footnoteRefs.map((ref) => ref.footnoteId)),
-			endnoteNumbers: computeNoteDisplayNumbers(endnotes, collectEndnoteRefs(authored).map((ref) => ref.endnoteId))
+			footnoteNumbers,
+			endnoteTexts: formatEndnoteTexts(endnoteNumbers, (displayNumber) => formatOoxmlCounter(displayNumber, endnoteNumberFormat))
 		});
 		const measures = measureBlocks(blocks, contentWidth);
 		const footnoteContentById = footnoteRefs.length === 0 ? void 0 : buildFootnoteContentMap(footnotes, footnoteRefs, contentWidth, {

package/dist/layout-bridge/convert/footnoteLayout.d.ts

@@ -52,8 +52,8 @@ declare function computeNoteDisplayNumbers(notes: readonly NumberableNote[], ref
 type NoteDisplayNumberMaps = {
   /** footnote `w:id` → sequential display number */
   footnoteNumbers?: ReadonlyMap<number, number>;
-  /** endnote `w:id` → sequential display number */
-  endnoteNumbers?: ReadonlyMap<number, number>;
+  /** endnote `w:id` → formatted display text */
+  endnoteTexts?: ReadonlyMap<number, string>;
 };
 /**
  * Rewrite body reference-marker run text from the raw `w:id` (which the PM

package/dist/layout-bridge/convert/footnoteLayout.js

@@ -80,7 +80,7 @@ function computeNoteDisplayNumbers(notes, refNoteIds) {
 * template preview substitution).
 */
 function remapNoteMarkerText(blocks, maps) {
-	if ((maps.footnoteNumbers?.size ?? 0) === 0 && (maps.endnoteNumbers?.size ?? 0) === 0) return blocks;
+	if ((maps.footnoteNumbers?.size ?? 0) === 0 && (maps.endnoteTexts?.size ?? 0) === 0) return blocks;
 	let changed = false;
 	const next = blocks.map((block) => {
 		const remapped = remapNoteMarkerBlock(block, maps);
@@ -147,17 +147,19 @@ function remapNoteMarkerParagraph(block, maps) {
 }
 function remapNoteMarkerRun(run, maps) {
 	if (run.kind !== "text") return run;
-	const displayNumber = getRunDisplayNumber(run, maps);
-	if (displayNumber === void 0) return run;
-	const text = String(displayNumber);
-	return run.text === text ? run : {
+	const displayText = getRunDisplayText(run, maps);
+	if (displayText === void 0) return run;
+	return run.text === displayText ? run : {
 		...run,
-		text
+		text: displayText
 	};
 }
-function getRunDisplayNumber(run, maps) {
-	if (run.footnoteRefId !== void 0) return maps.footnoteNumbers?.get(run.footnoteRefId);
-	if (run.endnoteRefId !== void 0) return maps.endnoteNumbers?.get(run.endnoteRefId);
+function getRunDisplayText(run, maps) {
+	if (run.footnoteRefId !== void 0) {
+		const displayNumber = maps.footnoteNumbers?.get(run.footnoteRefId);
+		return displayNumber === void 0 ? void 0 : String(displayNumber);
+	}
+	if (run.endnoteRefId !== void 0) return maps.endnoteTexts?.get(run.endnoteRefId);
 }
 /**
 * After layout, determine which footnotes appear on which pages.
@@ -202,7 +204,7 @@ function convertFootnoteToContent(footnote, displayNumber, contentWidth, options
 	if (options.justificationCompatibility) flowOptions.justificationCompatibility = options.justificationCompatibility;
 	if (options.tableIndentCompatibility) flowOptions.tableIndentCompatibility = options.tableIndentCompatibility;
 	if (options.automaticHyphenation) flowOptions.automaticHyphenation = options.automaticHyphenation;
-	const blocks = applyFootnotePresentation(toFlowBlocks(pmDoc, flowOptions), displayNumber);
+	const blocks = applyFootnotePresentation(preserveAuthoredFootnoteTerminalParagraph(toFlowBlocks(pmDoc, flowOptions)), displayNumber);
 	const measures = options.measureBlocks ? options.measureBlocks(blocks, contentWidth) : measureFootnoteBlocks(blocks, contentWidth);
 	let totalHeight = 0;
 	for (const measure of measures) if (measure.kind === "paragraph") totalHeight += measure.totalHeight;
@@ -216,6 +218,17 @@ function convertFootnoteToContent(footnote, displayNumber, contentWidth, options
 		height: totalHeight
 	};
 }
+/** Restore an authored footnote line that the body-only terminal-table policy collapsed. */
+function preserveAuthoredFootnoteTerminalParagraph(blocks) {
+	const finalBlock = blocks.at(-1);
+	if (blocks.at(-2)?.kind !== "table" || finalBlock?.kind !== "paragraph" || finalBlock.attrs?.suppressEmptyParagraphHeight !== true) return blocks;
+	const attrs = { ...finalBlock.attrs };
+	delete attrs.suppressEmptyParagraphHeight;
+	return [...blocks.slice(0, -1), {
+		...finalBlock,
+		attrs
+	}];
+}
 function measureFootnoteBlocks(blocks, contentWidth) {
 	return blocks.map((block) => measureFootnoteBlock(block, contentWidth));
 }

package/dist/layout-bridge/convert/headerFooterLayout.js

@@ -3,6 +3,16 @@ import { headerFooterToProseDoc } from "../../prosemirror/conversion/toProseDoc.
 import { emuToPixels } from "../../utils/units.js";
 import { toFlowBlocks } from "./toFlowBlocks.js";
 //#region src/layout-bridge/convert/headerFooterLayout.ts
+const DETACHED_WATERMARK_HOST = Symbol.for("stll.detachedWatermarkHost");
+const headerFooterToProseDocWithDetachedWatermarkHost = (headerFooter, options) => {
+	return headerFooterToProseDoc(headerFooter.content.map((block, blockIndex) => {
+		if (blockIndex !== headerFooter.watermarkBlockIndex || block.type !== "paragraph") return block;
+		return {
+			...block,
+			[DETACHED_WATERMARK_HOST]: true
+		};
+	}), options);
+};
 function isAnchoredImageRun(run) {
 	if (run.kind !== "image") return false;
 	if (run.position) return true;
@@ -241,7 +251,7 @@ function calculateHeaderFooterVisualBounds(blocks, measures, flowHeight, metrics
 * these bounds separately describe the in-flow portion for API consumers.
 */
 function calculateHeaderFooterMarginPushBounds(blocks, measures, flowHeight, metrics) {
-	if (blocks.length > 0 && blocks.every((block) => isPaintlessParagraph(block) && !hasAuthoredVisualContent(block))) return {
+	if (blocks.length > 0 && blocks.every((block) => block.kind === "paragraph" && isPaintlessParagraph(block) && !hasAuthoredVisualContent(block) && block.attrs?.suppressEmptyParagraphHeight !== false && !preservesInheritedSpacing(block))) return {
 		top: 0,
 		bottom: 0
 	};
@@ -330,7 +340,7 @@ function convertHeaderFooterToContent(headerFooter, contentWidth, metrics, optio
 	const proseDocOptions = {};
 	if (options.styles) proseDocOptions.styles = options.styles;
 	if (options.theme !== void 0) proseDocOptions.theme = options.theme;
-	const pmDoc = headerFooterToProseDoc(headerFooter.content, proseDocOptions);
+	const pmDoc = headerFooter.watermarkBlockIndex === void 0 ? headerFooterToProseDoc(headerFooter.content, proseDocOptions) : headerFooterToProseDocWithDetachedWatermarkHost(headerFooter, proseDocOptions);
 	const flowOptions = {};
 	if (options.theme !== void 0) flowOptions.theme = options.theme;
 	if (options.fontAlternates !== void 0) flowOptions.fontAlternates = options.fontAlternates;
@@ -458,6 +468,7 @@ function serializeParagraphAttrs(attrs) {
 	const keys = [
 		"alignment",
 		"bidi",
+		"suppressEmptyParagraphHeight",
 		"indent",
 		"spacing",
 		"styleId",

package/dist/layout-bridge/convert/toFlowBlocks.js

@@ -13,6 +13,7 @@ import { advanceListMarker, advanceVisibleListMarker, cloneListCounterState, for
 import { resolveNumberedRefFields } from "../../prosemirror/numberedRefFields.js";
 import { directionToBidi } from "../../prosemirror/paragraphDirection.js";
 import { cascadeStyleTextFormatting } from "../../prosemirror/styles/styleToggleCascade.js";
+import { expectTextBoxAnchorAttrs } from "../../prosemirror/textBoxAnchorAttrs.js";
 import { assertValidProseMirrorDocument } from "../../prosemirror/validation.js";
 import { normalizeShapeTextAnchor } from "../../types/documentEnumValues.js";
 import { resolveColor, resolveHighlightToCss } from "../../utils/colorResolver.js";
@@ -20,12 +21,22 @@ import { resolveThemeFont } from "../../utils/fontResolver.js";
 import { resolveShadingFill } from "../../utils/formatToStyle.js";
 import { normalizeHorizontalScalePercent } from "../../utils/horizontalScale.js";
 import { decodeOoxmlSymbolCharacter } from "../../utils/ooxmlSymbol.js";
+import { sanitizeImageSrc } from "../../utils/sanitizeImageSrc.js";
 import { tableOfContentsStyleLevel } from "../../utils/tableOfContentsStyle.js";
 import { AUTO_PARAGRAPH_SPACING_PX, halfPointsToPixels, halfPointsToPoints, pointsToPixels } from "../../utils/units.js";
 import { getColumns } from "../sectionColumns.js";
 import { groupParagraphFrames } from "./paragraphFrames.js";
+import { panic } from "better-result";
 //#region src/layout-bridge/convert/toFlowBlocks.ts
+const DETACHED_WATERMARK_HOST_ATTR = "_detachedWatermarkHost";
+const expectDetachedWatermarkHostAttr = (attrs) => {
+	const value = Reflect.get(attrs, DETACHED_WATERMARK_HOST_ATTR);
+	if (value === null || value === void 0) return false;
+	if (typeof value !== "boolean") panic("Invalid ProseMirror detached watermark host attrs:\nparagraph.attrs._detachedWatermarkHost: Expected a boolean.");
+	return value;
+};
 const DEFAULT_FONT = "Calibri";
+const TEXT_BOX_ANCHOR_BLOCK_ID = Symbol.for("stll.textBoxAnchorBlockId");
 const DEFAULT_TABLE_CELL_MARGIN_TWIPS = {
 	top: 0,
 	right: 108,
@@ -454,6 +465,9 @@ function buildImageRun(attrs, constrained, pmStart, pmEnd, trackedChange) {
 	if (trackedChange?.changeRevisionId !== void 0) run.changeRevisionId = trackedChange.changeRevisionId;
 	return run;
 }
+/** A package image whose bytes cannot paint still owns its authored line box. */
+const hasRelationshipBackedImageBox = (attrs) => typeof attrs.rId === "string" && attrs.rId.trim().length > 0 && typeof attrs.width === "number" && Number.isFinite(attrs.width) && attrs.width >= 0 && typeof attrs.height === "number" && Number.isFinite(attrs.height) && attrs.height >= 0;
+const hasPaintableImageSource = (src) => sanitizeImageSrc(src) !== void 0;
 /**
 * In TOC paragraphs, strip the resolved Hyperlink character-style colour and
 * underline so the painter's link fallback doesn't fire. The PM doc keeps the
@@ -564,7 +578,7 @@ function paragraphToRuns(node, startPos, _options) {
 		}
 		if (child.type.name === "image") {
 			const attrs = expectImageAttrs(child);
-			if (!attrs.src) return;
+			if (!hasPaintableImageSource(attrs.src) && !hasRelationshipBackedImageBox(attrs)) return;
 			const constrained = constrainImageToPage(attrs.width ?? 100, attrs.height ?? 100, _options.pageContentHeight);
 			const trackedFmt = extractRunFormatting(child.marks, theme, fontAlternates);
 			const run = buildImageRun(attrs, constrained, childPos, childPos + child.nodeSize, trackedFmt);
@@ -878,6 +892,9 @@ function mapTabAlignment(align) {
 function hasOnlyVisuallyEmptyTextRuns(runs) {
 	return runs.length > 0 && runs.every((run) => run.kind === "text" && run.text.replace(/\u00a0/gu, " ").trim().length === 0);
 }
+function hasOnlyHiddenTextRuns(runs) {
+	return runs.length > 0 && runs.every((run) => run.kind === "text" && run.hidden === true);
+}
 function convertParagraph(node, startPos, options) {
 	const pmAttrs = expectParagraphAttrs(node);
 	const runs = paragraphToRuns(node, startPos, options);
@@ -903,10 +920,10 @@ function convertParagraph(node, startPos, options) {
 			if (alternate) attrs.defaultAlternateFontFamily = alternate;
 		}
 	}
-	if (runs.length === 0 && defaultTextFormatting?.hidden === true) {
-		attrs.suppressEmptyParagraphHeight = true;
-		if (attrs.listMarker !== void 0) attrs.listMarkerHidden = true;
-	}
+	const isFullyHiddenParagraph = defaultTextFormatting?.hidden === true && (runs.length === 0 || hasOnlyHiddenTextRuns(runs));
+	if (isFullyHiddenParagraph && attrs.listMarker !== void 0) attrs.listMarkerHidden = true;
+	if (isFullyHiddenParagraph) attrs.suppressEmptyParagraphHeight = true;
+	if (runs.length === 0 && expectDetachedWatermarkHostAttr(node.attrs)) attrs.suppressEmptyParagraphHeight = false;
 	const hasVisibleParagraphPayload = attrs.listMarker !== void 0 && !attrs.listMarkerHidden || attrs.borders?.top !== void 0 || attrs.borders?.bottom !== void 0 || attrs.borders?.left !== void 0 || attrs.borders?.right !== void 0 || attrs.borders?.between !== void 0 || attrs.borders?.bar !== void 0 || attrs.shading !== void 0;
 	if (runs.length === 0 && pmAttrs._pageBreakCarrier === true && !hasVisibleParagraphPayload) attrs.suppressEmptyParagraphHeight = true;
 	const bookmarkNames = pmAttrs.bookmarks?.map((b) => b.name);
@@ -934,6 +951,11 @@ function convertParagraph(node, startPos, options) {
 		...frame.yAlign !== void 0 ? { yAlign: frame.yAlign } : {},
 		...frame.wrap !== void 0 ? { wrap: frame.wrap } : {}
 	});
+	node.descendants((child) => {
+		if (child.type.name !== "textBoxAnchor") return true;
+		options.textBoxAnchorBlockIds.set(expectTextBoxAnchorAttrs(child).anchorId, block.id);
+		return false;
+	});
 	return block;
 }
 /**
@@ -945,6 +967,7 @@ function convertParagraph(node, startPos, options) {
 function isPaintlessTerminalParagraph(block) {
 	if (block?.kind !== "paragraph" || block.runs.length !== 0) return false;
 	const attrs = block.attrs;
+	if (attrs?.suppressEmptyParagraphHeight === false) return false;
 	return !(attrs?.listMarker !== void 0 && !attrs.listMarkerHidden || attrs?.borders?.top || attrs?.borders?.bottom || attrs?.borders?.left || attrs?.borders?.right || attrs?.borders?.between || attrs?.borders?.bar || attrs?.shading || attrs?.spacingExplicit?.before || attrs?.spacingExplicit?.after || attrs?.pageBreakBefore || attrs?.renderedPageBreakBefore);
 }
 function suppressFinalEmptyParagraphAfterTable(blocks) {
@@ -1188,6 +1211,7 @@ function convertTable(node, startPos, options) {
 */
 function convertImage(node, startPos, pageContentHeight) {
 	const attrs = expectImageAttrs(node);
+	if (!hasPaintableImageSource(attrs.src) && !hasRelationshipBackedImageBox(attrs)) return;
 	const wrapType = attrs.wrapType;
 	const shouldAnchor = wrapType === "behind" || wrapType === "inFront";
 	const constrained = constrainImageToPage(attrs.width ?? 100, attrs.height ?? 100, pageContentHeight);
@@ -1269,6 +1293,8 @@ function convertTextBoxNode(node, startPos, opts) {
 	if (attrs.distRight !== void 0) textBox.distRight = attrs.distRight;
 	if (attrs.position !== void 0) textBox.position = attrs.position;
 	if (attrs._docxGroupId !== void 0) setTextBoxGroupId(textBox, attrs._docxGroupId);
+	const anchorBlockId = attrs._docxAnchorId ? opts.textBoxAnchorBlockIds.get(attrs._docxAnchorId) : void 0;
+	if (anchorBlockId !== void 0) Reflect.set(textBox, TEXT_BOX_ANCHOR_BLOCK_ID, anchorBlockId);
 	return textBox;
 }
 function getLastMapKey(map) {
@@ -1277,6 +1303,41 @@ function getLastMapKey(map) {
 	return lastKey;
 }
 /**
+* Translate section-owned start modes into the boundary-owned values consumed
+* by the paginator. Each flow section break carries the properties for the
+* section it ends, so its start mode belongs on the preceding boundary.
+*/
+function applySectionStartsToBoundaries(blocks, finalSectionStart) {
+	const breakIndexes = [];
+	for (let index = 0; index < blocks.length; index += 1) if (blocks[index]?.kind === "sectionBreak") breakIndexes.push(index);
+	if (breakIndexes.length === 0) return [...blocks];
+	const result = [...blocks];
+	for (let index = 0; index < breakIndexes.length; index += 1) {
+		const boundaryIndex = breakIndexes[index];
+		if (boundaryIndex === void 0) continue;
+		const boundary = blocks[boundaryIndex];
+		if (boundary?.kind !== "sectionBreak") continue;
+		const nextBoundaryIndex = breakIndexes[index + 1];
+		const nextBoundary = nextBoundaryIndex === void 0 ? void 0 : blocks[nextBoundaryIndex];
+		const nextStart = nextBoundary?.kind === "sectionBreak" ? nextBoundary.type : finalSectionStart;
+		const translated = { ...boundary };
+		if (nextStart === void 0) delete translated.type;
+		else translated.type = nextStart;
+		result[boundaryIndex] = translated;
+	}
+	return result;
+}
+function readFinalSectionStart(doc) {
+	const sectionStart = doc.attrs["_finalSectionStart"];
+	switch (sectionStart) {
+		case "continuous":
+		case "nextPage":
+		case "oddPage":
+		case "evenPage": return sectionStart;
+		default: return;
+	}
+}
+/**
 * Convert a ProseMirror document to FlowBlock array.
 *
 * Walks the document tree, converting each node to the appropriate block type.
@@ -1315,6 +1376,7 @@ function toFlowBlocks(doc, options = {}) {
 			final: listCounterState,
 			original: originalListCounterState
 		},
+		textBoxAnchorBlockIds: /* @__PURE__ */ new Map(),
 		numberedRefResults: resolveNumberedRefFields(doc, {
 			listCounterState: cloneListCounterState(listCounterState),
 			originalListCounterState: cloneListCounterState(originalListCounterState)
@@ -1521,9 +1583,11 @@ function toFlowBlocks(doc, options = {}) {
 			case "table":
 				trackedPush(convertTable(node, pos, opts));
 				break;
-			case "image":
-				trackedPush(convertImage(node, pos, opts.pageContentHeight));
+			case "image": {
+				const image = convertImage(node, pos, opts.pageContentHeight);
+				if (image !== void 0) trackedPush(image);
 				break;
+			}
 			case "textBox":
 				trackedPush(convertTextBoxNode(node, pos, opts));
 				break;
@@ -1548,24 +1612,43 @@ function toFlowBlocks(doc, options = {}) {
 	reserveLeadingEmptyOutlineHeight(blocks);
 	suppressFinalEmptyParagraphAfterTable(blocks);
 	suppressFinalParagraphInRepeatedEmptySuffix(blocks);
-	return groupParagraphFrames(applySectionDocumentGrid(mergeRunInParagraphs(blocks), opts.finalSectionDocumentGridLinePitchTwips), nextBlockId);
+	const mergedBlocks = mergeRunInParagraphs(blocks);
+	const tableCellLinePitch = doc.attrs["_adjustLineHeightInTable"] === true ? "sectionGrid" : void 0;
+	return groupParagraphFrames(applySectionStartsToBoundaries(applySectionDocumentGrid(mergedBlocks, {
+		finalLinePitchTwips: opts.finalSectionDocumentGridLinePitchTwips,
+		tableCellLinePitch
+	}), readFinalSectionStart(doc)), nextBlockId);
 }
-function applySectionDocumentGrid(blocks, finalLinePitchTwips) {
+function applySectionDocumentGrid(blocks, { finalLinePitchTwips, tableCellLinePitch }) {
 	const result = [...blocks];
 	let sectionStart = 0;
 	const stampSection = (end, linePitchTwips) => {
 		if (linePitchTwips === void 0 || linePitchTwips <= 0) return;
 		const linePitch = twipsToPixels(linePitchTwips);
-		for (let index = sectionStart; index < end; index += 1) {
-			const block = result[index];
-			if (block?.kind !== "paragraph") continue;
-			result[index] = {
+		const stampBlock = (block) => {
+			if (block.kind === "paragraph") return {
 				...block,
 				attrs: {
 					...block.attrs,
 					documentGridLinePitch: linePitch
 				}
 			};
+			if (block.kind !== "table" || tableCellLinePitch !== "sectionGrid") return block;
+			return {
+				...block,
+				rows: block.rows.map((row) => ({
+					...row,
+					cells: row.cells.map((cell) => ({
+						...cell,
+						blocks: cell.blocks.map(stampBlock)
+					}))
+				}))
+			};
+		};
+		for (let index = sectionStart; index < end; index += 1) {
+			const block = result[index];
+			if (!block) continue;
+			result[index] = stampBlock(block);
 		}
 	};
 	for (let index = 0; index < blocks.length; index += 1) {