@stll/folio-core 0.28.0 → 0.28.1

package/dist/docx/styleParser.js

@@ -1,23 +1,24 @@
 import { isValidHexColor } from "../utils/colorResolver.js";
 import { mergeParagraphFormatting } from "../utils/paragraphFormattingMerge.js";
-import { mergeTextFormatting } from "../utils/textFormattingMerge.js";
+import { mergeStyleTextFormatting } from "../utils/textFormattingMerge.js";
 import { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { resolveThemeFontRef } from "./themeParser.js";
 import { findChild, findChildren, getAttribute, getLocalName, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/styleParser.ts
+const findLastRunToggle = (rPr, localName) => findChildren(rPr, "w", localName).at(-1) ?? null;
 /**
 * Parse text formatting properties (w:rPr)
 */
 function parseRunProperties(rPr, theme) {
 	if (!rPr) return;
 	const formatting = {};
-	const b = findChild(rPr, "w", "b");
+	const b = findLastRunToggle(rPr, "b");
 	if (b) formatting.bold = parseBooleanElement(b);
-	const bCs = findChild(rPr, "w", "bCs");
+	const bCs = findLastRunToggle(rPr, "bCs");
 	if (bCs) formatting.boldCs = parseBooleanElement(bCs);
-	const i = findChild(rPr, "w", "i");
+	const i = findLastRunToggle(rPr, "i");
 	if (i) formatting.italic = parseBooleanElement(i);
-	const iCs = findChild(rPr, "w", "iCs");
+	const iCs = findLastRunToggle(rPr, "iCs");
 	if (iCs) formatting.italicCs = parseBooleanElement(iCs);
 	const u = findChild(rPr, "w", "u");
 	if (u) {
@@ -29,7 +30,7 @@ function parseRunProperties(rPr, theme) {
 			if (colorVal || themeColor) formatting.underline.color = parseColorValue(colorVal, themeColor, getAttribute(u, "w", "themeTint"), getAttribute(u, "w", "themeShade"));
 		}
 	}
-	const strike = findChild(rPr, "w", "strike");
+	const strike = findLastRunToggle(rPr, "strike");
 	if (strike) formatting.strike = parseBooleanElement(strike);
 	const dstrike = findChild(rPr, "w", "dstrike");
 	if (dstrike) formatting.doubleStrike = parseBooleanElement(dstrike);
@@ -38,11 +39,11 @@ function parseRunProperties(rPr, theme) {
 		const val = getAttribute(vertAlign, "w", "val");
 		if (val === "superscript" || val === "subscript" || val === "baseline") formatting.vertAlign = val;
 	}
-	const smallCaps = findChild(rPr, "w", "smallCaps");
+	const smallCaps = findLastRunToggle(rPr, "smallCaps");
 	if (smallCaps) formatting.smallCaps = parseBooleanElement(smallCaps);
-	const caps = findChild(rPr, "w", "caps");
+	const caps = findLastRunToggle(rPr, "caps");
 	if (caps) formatting.allCaps = parseBooleanElement(caps);
-	const vanish = findChild(rPr, "w", "vanish");
+	const vanish = findLastRunToggle(rPr, "vanish");
 	if (vanish) formatting.hidden = parseBooleanElement(vanish);
 	const color = findChild(rPr, "w", "color");
 	if (color) formatting.color = parseColorValue(getAttribute(color, "w", "val"), getAttribute(color, "w", "themeColor"), getAttribute(color, "w", "themeTint"), getAttribute(color, "w", "themeShade"));
@@ -154,13 +155,13 @@ function parseRunProperties(rPr, theme) {
 		const val = narrowEnum(getAttribute(em, "w", "val"), EmphasisMarkSchema);
 		if (val) formatting.emphasisMark = val;
 	}
-	const emboss = findChild(rPr, "w", "emboss");
+	const emboss = findLastRunToggle(rPr, "emboss");
 	if (emboss) formatting.emboss = parseBooleanElement(emboss);
-	const imprint = findChild(rPr, "w", "imprint");
+	const imprint = findLastRunToggle(rPr, "imprint");
 	if (imprint) formatting.imprint = parseBooleanElement(imprint);
-	const outline = findChild(rPr, "w", "outline");
+	const outline = findLastRunToggle(rPr, "outline");
 	if (outline) formatting.outline = parseBooleanElement(outline);
-	const shadow = findChild(rPr, "w", "shadow");
+	const shadow = findLastRunToggle(rPr, "shadow");
 	if (shadow) formatting.shadow = parseBooleanElement(shadow);
 	const rtl = findChild(rPr, "w", "rtl");
 	if (rtl) formatting.rtl = parseBooleanElement(rtl);
@@ -807,7 +808,7 @@ function resolveStyleInheritance(style, styleMap, visited = /* @__PURE__ */ new
 	const resolved = { ...style };
 	const mergedPPr = mergeParagraphFormatting(resolvedParent.pPr, style.pPr);
 	if (mergedPPr) resolved.pPr = mergedPPr;
-	const mergedRPr = mergeTextFormatting(resolvedParent.rPr, style.rPr);
+	const mergedRPr = mergeStyleTextFormatting(resolvedParent.rPr, style.rPr);
 	if (mergedRPr) resolved.rPr = mergedRPr;
 	if (style.type === "table") {
 		if (resolvedParent.tblPr || style.tblPr) resolved.tblPr = {

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

@@ -6,10 +6,11 @@ import { setParagraphFrame } from "../../layout-engine/paragraphFrame.js";
 import { setTextBoxGroupId } from "../../layout-engine/textBoxGroup.js";
 import { DEFAULT_TEXTBOX_MARGINS } from "../../layout-engine/types.js";
 import { getPageNumbering } from "../../paged-layout/sectionGeometry.js";
-import { expectBlockSdtAttrs, expectCharacterSpacingMarkAttrs, expectCommentMarkAttrs, expectEmphasisMarkAttrs, expectFieldAttrs, expectFontFamilyMarkAttrs, expectFontSizeMarkAttrs, expectFootnoteRefMarkAttrs, expectHardBreakAttrs, expectHighlightMarkAttrs, expectHyperlinkMarkAttrs, expectImageAttrs, expectLanguageMarkAttrs, expectMathAttrs, expectParagraphAttrs, expectRunFormattingOverrideMarkAttrs, expectRunShadingMarkAttrs, expectSymbolAttrs, expectTableAttrs, expectTableCellAttrs, expectTableRowAttrs, expectTextBoxAttrs, expectTextColorMarkAttrs, expectTextEffectMarkAttrs, expectTrackedChangeMarkAttrs, expectUnderlineMarkAttrs } from "../../prosemirror/attrs/index.js";
+import { expectBlockSdtAttrs, expectCharacterSpacingMarkAttrs, expectCharacterStyleMarkAttrs, expectCommentMarkAttrs, expectEmphasisMarkAttrs, expectFieldAttrs, expectFontFamilyMarkAttrs, expectFontSizeMarkAttrs, expectFootnoteRefMarkAttrs, expectHardBreakAttrs, expectHighlightMarkAttrs, expectHyperlinkMarkAttrs, expectImageAttrs, expectLanguageMarkAttrs, expectMathAttrs, expectParagraphAttrs, expectRunFormattingOverrideMarkAttrs, expectRunShadingMarkAttrs, expectSymbolAttrs, expectTableAttrs, expectTableCellAttrs, expectTableRowAttrs, expectTextBoxAttrs, expectTextColorMarkAttrs, expectTextEffectMarkAttrs, expectTrackedChangeMarkAttrs, expectUnderlineMarkAttrs } from "../../prosemirror/attrs/index.js";
 import { autospacingMatchesBase } from "../../prosemirror/autospacingBase.js";
 import { runShadingAttrsToShading } from "../../prosemirror/conversion/runShadingMark.js";
 import { directionToBidi } from "../../prosemirror/paragraphDirection.js";
+import { cascadeStyleTextFormatting } from "../../prosemirror/styles/styleToggleCascade.js";
 import { assertValidProseMirrorDocument } from "../../prosemirror/validation.js";
 import { resolveColor, resolveHighlightToCss } from "../../utils/colorResolver.js";
 import { resolveThemeFont } from "../../utils/fontResolver.js";
@@ -348,17 +349,49 @@ function mergeRunFormatting(paraDefaults, formatting) {
 	if (merged.letterSpacing === 0) delete merged.letterSpacing;
 	return merged;
 }
+/** Restore character-style toggle values that plain visual marks cannot represent. */
+function applyCharacterStyleToggleFormatting({ formatting, marks, paraDefaults }) {
+	const characterStyleMark = marks.find((mark) => mark.type.name === "characterStyle");
+	if (!characterStyleMark) return;
+	const styleRPr = expectCharacterStyleMarkAttrs(characterStyleMark)._styleRPr;
+	if (!styleRPr) return;
+	const effectiveStyleFormatting = cascadeStyleTextFormatting([{
+		formatting: {
+			bold: paraDefaults.bold ?? false,
+			boldCs: paraDefaults.complexScriptBold ?? false,
+			italic: paraDefaults.italic ?? false,
+			italicCs: paraDefaults.complexScriptItalic ?? false
+		},
+		type: "direct"
+	}, {
+		formatting: styleRPr,
+		type: "style"
+	}]).formatting;
+	if (styleRPr.bold !== void 0 && formatting.bold === void 0) formatting.bold = effectiveStyleFormatting?.bold ?? false;
+	if (styleRPr.boldCs !== void 0 && formatting.complexScriptBold === void 0) formatting.complexScriptBold = effectiveStyleFormatting?.boldCs ?? false;
+	if (styleRPr.italic !== void 0 && formatting.italic === void 0) formatting.italic = effectiveStyleFormatting?.italic ?? false;
+	if (styleRPr.italicCs !== void 0 && formatting.complexScriptItalic === void 0) formatting.complexScriptItalic = effectiveStyleFormatting?.italicCs ?? false;
+	if (styleRPr.allCaps === true && formatting.allCaps === void 0) formatting.allCaps = false;
+	if (styleRPr.emboss === true && formatting.emboss === void 0) formatting.emboss = false;
+	if (styleRPr.imprint === true && formatting.imprint === void 0) formatting.imprint = false;
+	if (styleRPr.outline === true && formatting.textOutline === void 0) formatting.textOutline = false;
+	if (styleRPr.shadow === true && formatting.textShadow === void 0) formatting.textShadow = false;
+	if (styleRPr.smallCaps === true && formatting.smallCaps === void 0) formatting.smallCaps = false;
+	if (styleRPr.strike === true && formatting.strike === void 0) formatting.strike = false;
+	if (styleRPr.hidden === true && formatting.hidden === void 0) formatting.hidden = false;
+}
 function applyRunFormattingOverrides(formatting, attrs) {
-	if (attrs.bold === false) formatting.bold = false;
-	if (attrs.italic === false) formatting.italic = false;
+	if (attrs.bold !== void 0) formatting.bold = attrs.bold;
+	if (attrs.italic !== void 0) formatting.italic = attrs.italic;
 	if (attrs.underline === "none") formatting.underline = false;
-	if (attrs.strike === false) formatting.strike = false;
-	if (attrs.allCaps === false) formatting.allCaps = false;
-	if (attrs.smallCaps === false) formatting.smallCaps = false;
-	if (attrs.emboss === false) formatting.emboss = false;
-	if (attrs.imprint === false) formatting.imprint = false;
-	if (attrs.shadow === false) formatting.textShadow = false;
-	if (attrs.outline === false) formatting.textOutline = false;
+	if (attrs.strike !== void 0) formatting.strike = attrs.strike;
+	if (attrs.allCaps !== void 0) formatting.allCaps = attrs.allCaps;
+	if (attrs.smallCaps !== void 0) formatting.smallCaps = attrs.smallCaps;
+	if (attrs.hidden !== void 0) formatting.hidden = attrs.hidden;
+	if (attrs.emboss !== void 0) formatting.emboss = attrs.emboss;
+	if (attrs.imprint !== void 0) formatting.imprint = attrs.imprint;
+	if (attrs.shadow !== void 0) formatting.textShadow = attrs.shadow;
+	if (attrs.outline !== void 0) formatting.textOutline = attrs.outline;
 	if (attrs.rtl === false) formatting.rtl = false;
 	if (attrs.boldCs !== void 0) formatting.complexScriptBold = attrs.boldCs;
 	if (attrs.italicCs !== void 0) formatting.complexScriptItalic = attrs.italicCs;
@@ -497,6 +530,11 @@ function paragraphToRuns(node, startPos, _options) {
 		if (child.type.name !== "sdt") leadingRenderedPageBreakPending = false;
 		if (child.isText && child.text) {
 			const formatting = extractRunFormatting(child.marks, theme);
+			applyCharacterStyleToggleFormatting({
+				formatting,
+				marks: child.marks,
+				paraDefaults
+			});
 			if (inTocParagraph) stripTocHyperlinkStyle(formatting);
 			const run = {
 				kind: "text",
@@ -513,6 +551,11 @@ function paragraphToRuns(node, startPos, _options) {
 			const text = decodeOoxmlSymbolCharacter(attrs.char);
 			if (text === null) return;
 			const formatting = extractRunFormatting(child.marks, theme);
+			applyCharacterStyleToggleFormatting({
+				formatting,
+				marks: child.marks,
+				paraDefaults
+			});
 			if (inTocParagraph) stripTocHyperlinkStyle(formatting);
 			runs.push({
 				kind: "text",
@@ -534,6 +577,11 @@ function paragraphToRuns(node, startPos, _options) {
 		}
 		if (child.type.name === "tab") {
 			const formatting = extractRunFormatting(child.marks, theme);
+			applyCharacterStyleToggleFormatting({
+				formatting,
+				marks: child.marks,
+				paraDefaults
+			});
 			const run = {
 				kind: "tab",
 				...mergeRunFormatting(paraDefaults, formatting),
@@ -561,6 +609,11 @@ function paragraphToRuns(node, startPos, _options) {
 			else if (ft === "DATE") mappedType = "DATE";
 			else if (ft === "TIME") mappedType = "TIME";
 			const extractedFieldFormatting = extractRunFormatting(child.marks, theme);
+			applyCharacterStyleToggleFormatting({
+				formatting: extractedFieldFormatting,
+				marks: child.marks,
+				paraDefaults
+			});
 			if (inTocParagraph) stripTocHyperlinkStyle(extractedFieldFormatting);
 			const fieldFormatting = markDefaultBlackTextColorSource(extractedFieldFormatting, paraDefaults);
 			const run = {
@@ -902,27 +955,25 @@ function convertParagraph(node, startPos, options) {
 	return block;
 }
 /**
-* Word keeps terminal empty body paragraphs after a final table as editable
-* anchors, but they do not create a page of their own. Preserve every block
-* and PM range while collapsing only the contiguous, run-free suffix; empty
-* paragraphs elsewhere still retain their normal line height.
+* Word keeps a final empty body paragraph after a table as an editable anchor,
+* but that final anchor does not create a page of its own. Earlier authored
+* empty paragraphs retain their height and may carry the document onto a blank
+* page. Preserve every block and PM range while collapsing only the final one.
 */
 function isPaintlessTerminalParagraph(block) {
 	if (block?.kind !== "paragraph" || block.runs.length !== 0) return false;
 	const attrs = block.attrs;
 	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 suppressTerminalEmptyParagraphsAfterTable(blocks) {
+function suppressFinalEmptyParagraphAfterTable(blocks) {
 	let suffixStart = blocks.length;
 	while (suffixStart > 0 && isPaintlessTerminalParagraph(blocks[suffixStart - 1])) suffixStart -= 1;
 	if (suffixStart === blocks.length || suffixStart === 0 || blocks[suffixStart - 1]?.kind !== "table") return;
-	for (let index = suffixStart; index < blocks.length; index += 1) {
-		const block = blocks[index];
-		if (isPaintlessTerminalParagraph(block)) block.attrs = {
-			...block.attrs,
-			suppressEmptyParagraphHeight: true
-		};
-	}
+	const finalBlock = blocks.at(-1);
+	if (isPaintlessTerminalParagraph(finalBlock)) finalBlock.attrs = {
+		...finalBlock.attrs,
+		suppressEmptyParagraphHeight: true
+	};
 }
 function suppressFinalParagraphInRepeatedEmptySuffix(blocks) {
 	let suffixStart = blocks.length;
@@ -1477,7 +1528,7 @@ function toFlowBlocks(doc, options = {}) {
 		visit(node, offset + nodeOffset);
 	});
 	reserveLeadingEmptyOutlineHeight(blocks);
-	suppressTerminalEmptyParagraphsAfterTable(blocks);
+	suppressFinalEmptyParagraphAfterTable(blocks);
 	suppressFinalParagraphInRepeatedEmptySuffix(blocks);
 	return groupParagraphFrames(applySectionDocumentGrid(mergeRunInParagraphs(blocks), opts.finalSectionDocumentGridLinePitchTwips), nextBlockId);
 }

package/dist/layout-engine/footnoteColumnReflow.d.ts

@@ -0,0 +1,15 @@
+import { Layout } from "./types.js";
+//#region src/layout-engine/footnoteColumnReflow.d.ts
+type ReflowFootnoteColumnsOptions = {
+  initialLayout: Layout;
+  initialReserveFloors?: ReadonlyMap<number, number>;
+  runLayout: (reserveFloors: Map<number, number>) => Layout;
+};
+/**
+ * Re-run a multi-column layout until its body flow clears the shared footnote band.
+ * Reserve floors follow the current page-to-footnote assignment. Repeated floor states
+ * and persistent overlap use a stable fallback layout instead of throwing.
+ */
+declare function reflowFootnoteColumns({ initialLayout, initialReserveFloors, runLayout }: ReflowFootnoteColumnsOptions): Layout;
+//#endregion
+export { reflowFootnoteColumns };

package/dist/layout-engine/footnoteColumnReflow.js

@@ -0,0 +1,74 @@
+//#region src/layout-engine/footnoteColumnReflow.ts
+function isFlowFragment(fragment) {
+	switch (fragment.kind) {
+		case "paragraph": return true;
+		case "table": return !fragment.isFloating;
+		case "image": return !fragment.isAnchored;
+		case "textBox": return !fragment.isPositioned;
+		default: return fragment;
+	}
+}
+function hasFootnoteColumnOverlap(layout) {
+	for (const page of layout.pages) {
+		if ((page.columns?.count ?? 1) < 2 || !page.footnoteReservedHeight) continue;
+		const bodyBottom = page.size.h - page.margins.bottom - page.footnoteReservedHeight;
+		if (page.fragments.some((fragment) => isFlowFragment(fragment) && fragment.y + fragment.height > bodyBottom)) return true;
+	}
+	return false;
+}
+function growFootnoteReserveFloors(layout, initialReserveFloors) {
+	const next = /* @__PURE__ */ new Map();
+	for (const page of layout.pages) {
+		if ((page.footnoteIds?.length ?? 0) === 0) continue;
+		const observed = page.footnoteReservedHeight ?? 0;
+		const callerFloor = initialReserveFloors?.get(page.number) ?? 0;
+		const floor = Math.max(callerFloor, observed);
+		if (floor > 0) next.set(page.number, floor);
+	}
+	return next;
+}
+function reserveFloorFingerprint(floors) {
+	return JSON.stringify([...floors.entries()].sort(([leftPage], [rightPage]) => leftPage - rightPage));
+}
+function clearOrphanedFootnoteReservations(layout) {
+	let pagesChanged = false;
+	const pages = layout.pages.map((page) => {
+		if ((page.footnoteIds?.length ?? 0) > 0 || page.footnoteReservedHeight === void 0) return page;
+		pagesChanged = true;
+		const cleanedPage = { ...page };
+		delete cleanedPage.footnoteReservedHeight;
+		return cleanedPage;
+	});
+	if (!pagesChanged) return layout;
+	return {
+		...layout,
+		pages
+	};
+}
+function getPassBudget(layout) {
+	const fragmentCount = layout.pages.reduce((count, page) => count + page.fragments.length, 0);
+	const footnoteCount = new Set(layout.pages.flatMap((page) => page.footnoteIds ?? [])).size;
+	return layout.pages.length + fragmentCount + footnoteCount + 1;
+}
+/**
+* Re-run a multi-column layout until its body flow clears the shared footnote band.
+* Reserve floors follow the current page-to-footnote assignment. Repeated floor states
+* and persistent overlap use a stable fallback layout instead of throwing.
+*/
+function reflowFootnoteColumns({ initialLayout, initialReserveFloors, runLayout }) {
+	let layout = initialLayout;
+	if (!hasFootnoteColumnOverlap(layout)) return clearOrphanedFootnoteReservations(layout);
+	const seenReserveStates = /* @__PURE__ */ new Set();
+	const passBudget = getPassBudget(layout);
+	for (let pass = 0; pass < passBudget; pass += 1) {
+		const reserveFloors = growFootnoteReserveFloors(layout, initialReserveFloors);
+		const reserveState = reserveFloorFingerprint(reserveFloors);
+		if (seenReserveStates.has(reserveState)) return clearOrphanedFootnoteReservations(layout);
+		seenReserveStates.add(reserveState);
+		layout = runLayout(reserveFloors);
+		if (!hasFootnoteColumnOverlap(layout)) return clearOrphanedFootnoteReservations(layout);
+	}
+	return clearOrphanedFootnoteReservations(layout);
+}
+//#endregion
+export { reflowFootnoteColumns };

package/dist/layout-engine/index.d.ts

@@ -32,11 +32,9 @@ declare function applyContextualSpacing(blocks: FlowBlock[]): void;
 /**
  * Layout a document: convert blocks + measures into pages with positioned fragments.
  *
- * Algorithm:
- * 1. Walk blocks in order with their corresponding measures
- * 2. For each block, create appropriate fragment(s)
- * 3. Use paginator to manage page/column state
- * 4. Handle page breaks, section breaks, and keepNext chains
+ * A reference discovered after the first column has already been placed can shrink the
+ * shared body band below earlier-column fragments. Retry those documents with the observed
+ * reservations as page floors so every column participates in the same footnote geometry.
  */
 declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], options: LayoutOptions): Layout;
 /**

package/dist/layout-engine/index.js

@@ -1,4 +1,5 @@
 import { emuToPixels } from "../utils/units.js";
+import { reflowFootnoteColumns } from "./footnoteColumnReflow.js";
 import { resolveSectionHeaderFooterRefs } from "./headerFooterRefs.js";
 import { calculateChainHeight, computeKeepNextChains, getMidChainIndices, hasKeepLines, hasPageBreakBefore } from "./keep-together.js";
 import { measuredLineAdvance } from "./lineFlow.js";
@@ -140,13 +141,23 @@ function applyContextualSpacing(blocks) {
 /**
 * Layout a document: convert blocks + measures into pages with positioned fragments.
 *
-* Algorithm:
-* 1. Walk blocks in order with their corresponding measures
-* 2. For each block, create appropriate fragment(s)
-* 3. Use paginator to manage page/column state
-* 4. Handle page breaks, section breaks, and keepNext chains
+* A reference discovered after the first column has already been placed can shrink the
+* shared body band below earlier-column fragments. Retry those documents with the observed
+* reservations as page floors so every column participates in the same footnote geometry.
 */
 function layoutDocument(blocks, measures, options) {
+	const layout = layoutDocumentPass(blocks, measures, options);
+	if (!options.footnoteHeightById) return layout;
+	return reflowFootnoteColumns({
+		initialLayout: layout,
+		...options.footnoteReservedHeights ? { initialReserveFloors: options.footnoteReservedHeights } : {},
+		runLayout: (reserveFloors) => layoutDocumentPass(blocks, measures, {
+			...options,
+			footnoteReservedHeights: reserveFloors
+		})
+	});
+}
+function layoutDocumentPass(blocks, measures, options) {
 	if (blocks.length !== measures.length) panic(`layoutDocument: expected one measure per block (blocks=${blocks.length}, measures=${measures.length})`);
 	const pageSize = options.pageSize;
 	const baseMargins = {
@@ -333,6 +344,10 @@ function getLineFootnoteRefs(block, fromRun, toRun, fnHeights) {
 		height
 	};
 }
+function projectedFootnoteReserveGrowth(state, additionalDemandHeight) {
+	const projectedDemand = state.footnoteDemandHeight + additionalDemandHeight;
+	return Math.max(state.footnoteHeightFloor, projectedDemand) - state.footnoteHeight;
+}
 function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeightById, suppressSpaceBefore }) {
 	const lines = measure.lines;
 	if (lines.length === 0) {
@@ -370,7 +385,7 @@ function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeig
 		if (currentLineIndex === 0 && state.trailingSpacing > 0 && state.cursorY !== state.topMargin) {
 			const firstLine = lines[0];
 			const firstLineRefs = getLineFootnoteRefs(block, firstLine.fromRun, firstLine.toRun, footnoteHeightById);
-			const firstLineHeight = measuredLineAdvance(firstLine) + firstLineRefs.height;
+			const firstLineHeight = measuredLineAdvance(firstLine) + projectedFootnoteReserveGrowth(state, firstLineRefs.height);
 			const collapsedLead = collapseParagraphSpacing({
 				before: spaceBefore,
 				after: state.trailingSpacing
@@ -399,7 +414,8 @@ function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeig
 			}
 			const lineRefs = getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById);
 			const totalWithLine = linesHeight + lineAdvance;
-			if (totalWithLine + firstFragmentSpaceBefore + linesFnHeight + lineRefs.height <= availableHeight || fittingLines === 0) {
+			const footnoteGrowth = projectedFootnoteReserveGrowth(state, linesFnHeight + lineRefs.height);
+			if (totalWithLine + firstFragmentSpaceBefore + footnoteGrowth <= availableHeight || fittingLines === 0) {
 				linesHeight = totalWithLine;
 				linesFnHeight += lineRefs.height;
 				for (const id of lineRefs.ids) linesFnIds.push(id);
@@ -449,8 +465,10 @@ function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeig
 			...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
 		};
 		if (linesFnHeight > 0) {
-			paginator.ensureFits(effectiveSpaceBefore + linesHeight + linesFnHeight);
-			if (paginator.getCurrentState().footnoteHeight === 0) paginator.ensureFits(effectiveSpaceBefore + linesHeight + linesFnHeight + 12);
+			const stateBefore = paginator.getCurrentState();
+			paginator.ensureFits(effectiveSpaceBefore + linesHeight + projectedFootnoteReserveGrowth(stateBefore, linesFnHeight));
+			const stateAfter = paginator.getCurrentState();
+			if (stateAfter.footnoteDemandHeight === 0) paginator.ensureFits(effectiveSpaceBefore + linesHeight + projectedFootnoteReserveGrowth(stateAfter, linesFnHeight + 12));
 		}
 		fragment.y = paginator.addFragment(fragment, linesHeight, effectiveSpaceBefore, effectiveSpaceAfter).y;
 		if (linesFnHeight > 0) paginator.addFootnoteHeight(linesFnHeight, linesFnIds);
@@ -650,8 +668,9 @@ function layoutTable(block, measure, paginator, footnoteHeightById) {
 				fragmentFootnoteIds.push(id);
 				rowFootnoteHeight += footnoteHeightById?.get(id) ?? 0;
 			}
-			const separatorHeight = pageFootnoteIds.size === 0 && fragmentFootnoteHeight + rowFootnoteHeight > 0 ? 12 : 0;
-			if (rowsHeight + rowHeight + normalHeaderOverhead + fragmentFootnoteHeight + rowFootnoteHeight + separatorHeight <= availableHeight) {
+			const candidateFootnoteHeight = fragmentFootnoteHeight + rowFootnoteHeight;
+			const footnoteGrowth = projectedFootnoteReserveGrowth(state, candidateFootnoteHeight + (state.footnoteDemandHeight === 0 && candidateFootnoteHeight > 0 ? 12 : 0));
+			if (rowsHeight + rowHeight + normalHeaderOverhead + footnoteGrowth <= availableHeight) {
 				rowsHeight += rowHeight;
 				fragmentFootnoteHeight += rowFootnoteHeight;
 				fittingRows++;
@@ -780,7 +799,7 @@ function layoutFloatingTable(block, measure, paginator, contentWidth) {
 		isFloating: true,
 		...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
 	};
-	state.page.fragments.push(fragment);
+	paginator.addUnflowedFragment(fragment);
 }
 /**
 * Layout an image block onto pages.
@@ -825,7 +844,7 @@ function layoutAnchoredImage(block, measure, paginator) {
 		isAnchored: true,
 		zIndex: anchor.behindDoc ? -1 : 1
 	};
-	state.page.fragments.push(fragment);
+	paginator.addUnflowedFragment(fragment);
 }
 /**
 * Layout a text box block onto pages.
@@ -853,10 +872,11 @@ function layoutTextBox(block, measure, { paginator, sectionMarginTop, sectionPag
 			y: state.topMargin + bandTop,
 			width: measure.width,
 			height: measure.height,
+			isPositioned: true,
 			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
 			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
 		};
-		state.page.fragments.push(fragment);
+		paginator.addUnflowedFragment(fragment);
 		return;
 	}
 	if (block.position !== void 0) {
@@ -882,10 +902,11 @@ function layoutTextBox(block, measure, { paginator, sectionMarginTop, sectionPag
 			y,
 			width: measure.width,
 			height: measure.height,
+			isPositioned: true,
 			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
 			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
 		};
-		state.page.fragments.push(fragment);
+		paginator.addUnflowedFragment(fragment);
 		return;
 	}
 	const state = paginator.ensureFits(measure.height);

package/dist/layout-engine/measure/cache.d.ts

@@ -54,7 +54,7 @@ declare function setFontCacheSize(size: number): void;
  * Get current font metrics cache size
  */
 declare function getFontCacheSize(): number;
-/** Serialize the complete paragraph measurement contract into a cache key. */
+/** Serialize the complete, semantically normalized paragraph measurement contract into a cache key. */
 declare function hashParagraphBlock(block: ParagraphBlock): string;
 /**
  * Get cached paragraph measurement or return undefined

package/dist/layout-engine/measure/cache.js

@@ -188,11 +188,20 @@ const runMeasureCacheInput = (run) => {
 		default: return run;
 	}
 };
-/** Serialize the complete paragraph measurement contract into a cache key. */
+const paragraphAttrsMeasureCacheInput = (attrs) => {
+	if (attrs === void 0) return void 0;
+	const { snapToGrid, ...measurementAttrs } = attrs;
+	if (measurementAttrs.documentGridLinePitch === void 0) return measurementAttrs;
+	return {
+		...measurementAttrs,
+		snapToGrid: snapToGrid !== false
+	};
+};
+/** Serialize the complete, semantically normalized paragraph measurement contract into a cache key. */
 function hashParagraphBlock(block) {
 	return JSON.stringify({
 		lineBreakProviderGeneration: getLineBreakProviderGeneration(),
-		attrs: block.attrs,
+		attrs: paragraphAttrsMeasureCacheInput(block.attrs),
 		runs: block.runs.map(runMeasureCacheInput)
 	});
 }

package/dist/layout-engine/measure/listMarkerWidth.d.ts

@@ -27,7 +27,9 @@ declare function resolveListMarkerFont(block: ParagraphBlock): {
  *  - hanging indent — body wraps at `indentLeft`, marker sits at
  *    `indentLeft - hanging`. Width is `hanging` so the marker fills the slot.
  *  - `w:suff` (§17.9.25): `nothing` → natural width, `space` → natural +
- *    one space glyph, `tab` (default) → grow to the next tab stop.
+ *    one space glyph, `tab` (default) → grow to the next tab stop. A hanging
+ *    indent remains the minimum footprint so body text cannot enter the
+ *    marker slot.
  *  - `w:tabs` on the paragraph: non-`clear`/non-`bar` stops past the marker.
  *    `bar` (§17.3.1.37) is a vertical line and doesn't advance the cursor.
  *  - default tab grid: stops at multiples of `DEFAULT_TAB_STOP_TWIPS`,

package/dist/layout-engine/measure/listMarkerWidth.js

@@ -50,7 +50,9 @@ function resolveListMarkerFont(block) {
 *  - hanging indent — body wraps at `indentLeft`, marker sits at
 *    `indentLeft - hanging`. Width is `hanging` so the marker fills the slot.
 *  - `w:suff` (§17.9.25): `nothing` → natural width, `space` → natural +
-*    one space glyph, `tab` (default) → grow to the next tab stop.
+*    one space glyph, `tab` (default) → grow to the next tab stop. A hanging
+*    indent remains the minimum footprint so body text cannot enter the
+*    marker slot.
 *  - `w:tabs` on the paragraph: non-`clear`/non-`bar` stops past the marker.
 *    `bar` (§17.3.1.37) is a vertical line and doesn't advance the cursor.
 *  - default tab grid: stops at multiples of `DEFAULT_TAB_STOP_TWIPS`,
@@ -67,12 +69,12 @@ function getListMarkerInlineWidth(block) {
 	const naturalWidth = measureTextWidth(attrs.listMarker, style);
 	const markerEndOffset = getMarkerEndOffset(naturalWidth, attrs.listMarkerAlignment);
 	const suffix = attrs.listMarkerSuffix ?? "tab";
-	if (suffix === "nothing") return markerEndOffset;
-	if (suffix === "space") return markerEndOffset + measureTextWidth(" ", style);
+	const hanging = attrs.indent?.hanging ?? 0;
+	if (suffix === "nothing") return Math.max(hanging, markerEndOffset);
+	if (suffix === "space") return Math.max(hanging, markerEndOffset + measureTextWidth(" ", style));
 	const indent = attrs.indent;
 	const indentLeft = indent?.left ?? 0;
 	const firstLine = indent?.firstLine ?? 0;
-	const hanging = indent?.hanging ?? 0;
 	const markerStartPx = hanging > 0 ? indentLeft - hanging : indentLeft + firstLine;
 	const minBodyStart = markerStartPx + markerEndOffset;
 	const customTabs = (attrs.tabs ?? []).filter((t) => t.val !== "clear" && t.val !== "bar").map((t) => t.pos * TWIPS_TO_PX);

package/dist/layout-engine/paginator.d.ts

@@ -22,6 +22,10 @@ type PageState = {
   rawContentBottom: number;
   /** Total height reserved for footnotes on this page (grows as refs are placed). */
   footnoteHeight: number;
+  /** Static reservation supplied by a layout retry. */
+  footnoteHeightFloor: number;
+  /** Footnote demand discovered while placing reference-bearing content. */
+  footnoteDemandHeight: number;
   /** Accumulated trailing spacing (space after previous block). */
   trailingSpacing: number;
 };
@@ -98,6 +102,8 @@ declare function createPaginator(options: PaginatorOptions): {
     x: number;
     y: number;
   };
+  /** Add an already-positioned fragment without advancing normal flow. */
+  addUnflowedFragment: (fragment: Fragment) => PageState;
   /** Reserve additional footnote area on the current page. */
   addFootnoteHeight: (additionalHeight: number, footnoteIds?: number[]) => void;
   /** Force a page break. */