docxodus 9.7.0 → 9.9.0

package/dist/pagination.js

@@ -5,7 +5,20 @@
  * and flows it across fixed-size page containers based on document dimensions.
  */
 import { formatPageNumber } from "./page-number-format.js";
-import { DEFAULT_MARGIN, DEFAULT_PAGE_WIDTH, parseSectionDimensions, ptToPx, pxToPt, } from "./page-geometry.js";
+import { DEFAULT_MARGIN, DEFAULT_PAGE_WIDTH, parseSectionDimensions, ptToPx, pxToPt, resolvePageBands, } from "./page-geometry.js";
+/**
+ * Whether two sections describe the same physical page box. A continuous section
+ * break is only honorable when it does — a changed page size or margin set forces
+ * a real page break, which is Word's behavior too.
+ */
+function samePageBox(a, b) {
+    return (a.pageWidth === b.pageWidth &&
+        a.pageHeight === b.pageHeight &&
+        a.marginTop === b.marginTop &&
+        a.marginRight === b.marginRight &&
+        a.marginBottom === b.marginBottom &&
+        a.marginLeft === b.marginLeft);
+}
 // Default letter size in points (612 x 792 = 8.5" x 11")
 // Maximum percentage of content height that footnotes can occupy
 // This allows footnotes to expand upward into body content space when needed
@@ -63,20 +76,44 @@ export class PaginationEngine {
         this.pageNumbering = this.parsePageNumbering(sections);
         // If no sections found, treat the entire staging content as one section
         const sectionsToProcess = sections.length > 0 ? Array.from(sections) : [this.stagingElement];
+        const runs = [];
         for (const section of sectionsToProcess) {
-            const sectionIndex = parseInt(section.dataset.sectionIndex || "0", 10);
             const dims = parseSectionDimensions(section);
+            const previous = runs[runs.length - 1];
+            if (previous &&
+                section.dataset.sectionType === "continuous" &&
+                samePageBox(previous.dims, dims)) {
+                previous.sections.push(section);
+            }
+            else {
+                runs.push({
+                    sections: [section],
+                    sectionIndex: parseInt(section.dataset.sectionIndex || "0", 10),
+                    dims,
+                });
+            }
+        }
+        for (const run of runs) {
             // Make staging visible for measurement
             this.stagingElement.style.visibility = "hidden";
             this.stagingElement.style.position = "absolute";
             this.stagingElement.style.left = "-9999px";
             this.stagingElement.style.display = "block";
-            // Set width for accurate line wrapping
-            section.style.width = `${dims.contentWidth}pt`;
-            // Measure all blocks in this section
-            const blocks = this.measureBlocks(section, dims);
+            const blocks = [];
+            for (const section of run.sections) {
+                // Set width for accurate line wrapping
+                section.style.width = `${run.dims.contentWidth}pt`;
+                const columnCount = parseInt(section.dataset.cols || "1", 10);
+                if (columnCount > 1) {
+                    const gap = parseFloat(section.dataset.colGap || "");
+                    blocks.push(...this.buildColumnBlocks(section, run.dims, run.sectionIndex, columnCount, Number.isFinite(gap) ? gap : 36));
+                }
+                else {
+                    blocks.push(...this.measureBlocks(section, run.dims));
+                }
+            }
             // Flow blocks into pages
-            const sectionPages = this.flowToPages(blocks, dims, pageNumber, sectionIndex);
+            const sectionPages = this.flowToPages(blocks, run.dims, pageNumber, run.sectionIndex);
             pages.push(...sectionPages);
             pageNumber += sectionPages.length;
         }
@@ -176,7 +213,70 @@ export class PaginationEngine {
                 keepLines: child.dataset.keepLines === "true",
                 pageBreakBefore: child.dataset.pageBreakBefore === "true",
                 isPageBreak,
+                isWordParagraph: this.isWordParagraphElement(child),
+            });
+        }
+        return blocks;
+    }
+    /**
+     * Flows a multi-column (`w:cols`) section's children into CSS-multicol container
+     * blocks. Word lays such a section out as N columns inside the same body extent;
+     * a balanced `column-count` container reproduces that geometry, and the paginator
+     * then places each container as one ordinary measured block. A container grows
+     * greedily until its balanced height would exceed the smallest page body available
+     * to the section, so a long columned section still splits across pages at block
+     * boundaries. Each child lands in exactly one container, so anchors never
+     * duplicate. An explicit page break child passes through as its own block, which
+     * ends the current container and lets the normal flow logic turn the page.
+     */
+    buildColumnBlocks(section, dims, sectionIndex, columnCount, columnGapPt) {
+        const children = Array.from(section.children);
+        const blocks = [];
+        const maxFragmentHeight = this.smallestEffectiveContentHeight(dims, sectionIndex);
+        const isBreak = (child) => child.dataset.pageBreak === "true" ||
+            child.classList.contains(`${this.cssPrefix}break`);
+        const makeContainer = (slice) => {
+            const container = document.createElement("div");
+            container.style.columnCount = String(columnCount);
+            container.style.columnGap = `${columnGapPt}pt`;
+            for (const child of slice) {
+                container.appendChild(child.cloneNode(true));
+            }
+            return container;
+        };
+        let start = 0;
+        while (start < children.length) {
+            if (isBreak(children[start])) {
+                blocks.push(this.measureElement(children[start], dims));
+                start++;
+                continue;
+            }
+            // Grow the container one child at a time. Even a single oversized child is
+            // emitted alone, preserving the established oversized-block fallback.
+            let end = start + 1;
+            let container = makeContainer(children.slice(start, end));
+            let measured = this.measureElement(container, dims);
+            while (end < children.length && !isBreak(children[end])) {
+                const candidate = makeContainer(children.slice(start, end + 1));
+                const candidateMeasured = this.measureElement(candidate, dims);
+                if (candidateMeasured.heightPt > maxFragmentHeight)
+                    break;
+                container = candidate;
+                measured = candidateMeasured;
+                end++;
+            }
+            blocks.push({
+                element: container,
+                heightPt: measured.heightPt,
+                marginTopPt: measured.marginTopPt,
+                marginBottomPt: measured.marginBottomPt,
+                keepWithNext: false,
+                keepLines: false,
+                pageBreakBefore: false,
+                isPageBreak: false,
+                isWordParagraph: false,
             });
+            start = end;
         }
         return blocks;
     }
@@ -206,6 +306,7 @@ export class PaginationEngine {
             pageBreakBefore: element.dataset.pageBreakBefore === "true",
             isPageBreak: element.dataset.pageBreak === "true" ||
                 element.classList.contains(`${this.cssPrefix}break`),
+            isWordParagraph: this.isWordParagraphElement(element),
         };
         this.stagingElement.removeChild(measurementHost);
         return measured;
@@ -238,13 +339,11 @@ export class PaginationEngine {
      * collapsed-margin rules as normal block placement. The trailing margin is
      * intentionally excluded, matching the individual block fit check.
      */
-    measureKeepWithNextChainBodyHeight(chain, previousMarginBottomPt, isFirstOnPage) {
+    measureKeepWithNextChainBodyHeight(chain, previousMarginBottomPt, isFirstOnPage, pageInSection) {
         const firstBlock = chain[0];
         if (!firstBlock)
             return 0;
-        const firstMarginTop = isFirstOnPage
-            ? firstBlock.marginTopPt
-            : Math.max(firstBlock.marginTopPt, previousMarginBottomPt) - previousMarginBottomPt;
+        const firstMarginTop = this.effectiveBlockMarginTop(firstBlock, previousMarginBottomPt, isFirstOnPage, pageInSection);
         let bodyHeight = firstMarginTop + firstBlock.heightPt;
         for (let index = 1; index < chain.length; index++) {
             const previousBlock = chain[index - 1];
@@ -253,6 +352,37 @@ export class PaginationEngine {
         }
         return bodyHeight;
     }
+    /** Word paragraphs render as `p`, or as `h1`–`h6` when their style has an outline level. */
+    isWordParagraphElement(element) {
+        return element.tagName === "P" || /^H[1-6]$/.test(element.tagName);
+    }
+    shouldSuppressPageTopSpacing(block, isFirstOnPage, pageInSection) {
+        return isFirstOnPage && pageInSection > 1 && block.isWordParagraph === true;
+    }
+    /**
+     * Resolves the part of a block's top margin that consumes the current page.
+     *
+     * In Word's native DOCX layout, paragraph space-before is suppressed when a paragraph is the
+     * first body block on a later page of the SAME section. The first page of a document/section is
+     * the exception and keeps its spacing. Tables and other block margins are not paragraph spacing,
+     * so they continue to use the ordinary CSS collapsing rule.
+     */
+    effectiveBlockMarginTop(block, previousMarginBottomPt, isFirstOnPage, pageInSection) {
+        if (this.shouldSuppressPageTopSpacing(block, isFirstOnPage, pageInSection)) {
+            return 0;
+        }
+        return isFirstOnPage
+            ? block.marginTopPt
+            : Math.max(block.marginTopPt, previousMarginBottomPt) - previousMarginBottomPt;
+    }
+    /** Clone a source block with the same page-top spacing decision used by the height budget. */
+    cloneBlockForPage(block, isFirstOnPage, pageInSection) {
+        const clone = block.element.cloneNode(true);
+        if (this.shouldSuppressPageTopSpacing(block, isFirstOnPage, pageInSection)) {
+            clone.style.setProperty("margin-top", "0", "important");
+        }
+        return clone;
+    }
     /**
      * Finds footnote references introduced by a sequence of blocks, preserving
      * document order and excluding references already assigned to the page.
@@ -276,7 +406,7 @@ export class PaginationEngine {
      * send it through the oversized-block fallback again.
      */
     smallestEffectiveContentHeight(dims, sectionIndex) {
-        return Math.min(this.getEffectiveHeights(dims, sectionIndex, 1, 1).contentHeight, this.getEffectiveHeights(dims, sectionIndex, 2, 1).contentHeight, this.getEffectiveHeights(dims, sectionIndex, 2, 2).contentHeight);
+        return Math.min(this.getPageBands(dims, sectionIndex, 1, 1).bodyHeight, this.getPageBands(dims, sectionIndex, 2, 1).bodyHeight, this.getPageBands(dims, sectionIndex, 2, 2).bodyHeight);
     }
     /**
      * Builds a clone of a simple table wrapper containing a contiguous run of rows.
@@ -724,7 +854,7 @@ export class PaginationEngine {
             return 0;
         }
         // Measure in the SAME styling context the notes render in: `.page-footnotes` carries
-        // font-size 0.85em and line-height 1.4, so measuring without the class sizes the note
+        // its own font-size and line-height, so measuring without the class sizes the note
         // block against body type and the reserve can never match what is drawn.
         // Create a temporary measurement container
         const measureContainer = document.createElement("div");
@@ -884,7 +1014,7 @@ export class PaginationEngine {
     /**
      * Adds footnotes to a page container, including continuation content.
      */
-    addPageFootnotes(pageBox, footnoteIds, dims, footnoteHeight, continuation, partialFootnotes) {
+    addPageFootnotes(pageBox, footnoteIds, dims, bands, footnoteHeight, continuation, partialFootnotes) {
         const hasContinuation = continuation && continuation.remainingElements.length > 0;
         if (footnoteIds.length === 0 && !hasContinuation) {
             return;
@@ -895,11 +1025,13 @@ export class PaginationEngine {
         // Create a set of partial footnote IDs for quick lookup
         const partialFootnoteIds = new Set(partialFootnotes?.map(p => p.footnoteId) || []);
         // Calculate max height for footnotes area (content height minus margin for body content)
-        const maxFootnoteHeight = Math.min(footnoteHeight, dims.contentHeight * MAX_FOOTNOTE_AREA_RATIO);
+        const maxFootnoteHeight = Math.min(footnoteHeight, bands.bodyHeight * MAX_FOOTNOTE_AREA_RATIO);
         const footnotesDiv = document.createElement("div");
         footnotesDiv.className = `${this.cssPrefix}footnotes`;
         footnotesDiv.style.position = "absolute";
-        footnotesDiv.style.bottom = `${dims.marginBottom}pt`; // Above footer area
+        // Notes sit at the FOOT OF THE BODY BAND, not at the bottom margin: a footer taller than
+        // its margin raises that edge, and anchoring to the raw margin would draw notes over it.
+        footnotesDiv.style.bottom = `${dims.pageHeight - (bands.bodyTop + bands.bodyHeight)}pt`;
         footnotesDiv.style.left = `${dims.marginLeft}pt`;
         footnotesDiv.style.width = `${dims.contentWidth}pt`;
         footnotesDiv.style.boxSizing = "border-box";
@@ -991,63 +1123,37 @@ export class PaginationEngine {
         return sectionHf.footerDefault;
     }
     /**
-     * Computes effective header, footer, and content heights for a specific page position.
-     * Uses pre-measured header/footer heights from the registry.
-     * This method is deterministic - same inputs always produce same outputs.
-     * This enables lazy loading compatibility since available height can be computed
-     * for any page position without knowing the page's content.
+     * The header, body, and footer bands for one page position.
+     *
+     * The single owner of "where does anything sit vertically on this page" — placement in
+     * {@link createPage}, the body budget the flow loop spends, and the note area's anchor all
+     * read it, so those three cannot disagree about where the body ends.
+     *
+     * Deterministic: it depends only on the section's page setup and the registry's pre-measured
+     * story heights, never on the page's content, which is what keeps it lazy-loading compatible.
      */
-    getEffectiveHeights(dims, sectionIndex, pageInSection, globalPageNumber) {
+    getPageBands(dims, sectionIndex, pageInSection, globalPageNumber) {
         const sectionHf = this.hfRegistry.get(sectionIndex);
-        // Determine effective header height
-        let headerHeight = dims.marginTop;
-        if (sectionHf) {
-            let measuredHeaderHeight;
-            // Select the appropriate header height based on page position
-            if (pageInSection === 1 && sectionHf.headerFirstHeight != null) {
-                measuredHeaderHeight = sectionHf.headerFirstHeight;
-            }
-            else if (globalPageNumber % 2 === 0 && sectionHf.headerEvenHeight != null) {
-                measuredHeaderHeight = sectionHf.headerEvenHeight;
-            }
-            else if (sectionHf.headerDefaultHeight != null) {
-                measuredHeaderHeight = sectionHf.headerDefaultHeight;
-            }
-            if (measuredHeaderHeight != null) {
-                // Use the larger of margin height or measured content height
-                headerHeight = Math.max(dims.marginTop, measuredHeaderHeight);
-            }
-        }
-        // Determine effective footer height
-        let footerHeight = dims.marginBottom;
-        if (sectionHf) {
-            let measuredFooterHeight;
-            // Select the appropriate footer height based on page position
-            if (pageInSection === 1 && sectionHf.footerFirstHeight != null) {
-                measuredFooterHeight = sectionHf.footerFirstHeight;
-            }
-            else if (globalPageNumber % 2 === 0 && sectionHf.footerEvenHeight != null) {
-                measuredFooterHeight = sectionHf.footerEvenHeight;
-            }
-            else if (sectionHf.footerDefaultHeight != null) {
-                measuredFooterHeight = sectionHf.footerDefaultHeight;
-            }
-            if (measuredFooterHeight != null) {
-                // Use the larger of margin height or measured content height
-                footerHeight = Math.max(dims.marginBottom, measuredFooterHeight);
-            }
-        }
-        // Calculate effective content height
-        // contentHeight from dims is: pageHeight - marginTop - marginBottom
-        // We need to adjust for any header/footer expansion beyond margins
-        const headerExpansion = headerHeight - dims.marginTop;
-        const footerExpansion = footerHeight - dims.marginBottom;
-        const contentHeight = dims.contentHeight - headerExpansion - footerExpansion;
-        return { headerHeight, footerHeight, contentHeight };
+        return resolvePageBands(dims, this.selectStoryHeight(sectionHf?.headerFirstHeight, sectionHf?.headerEvenHeight, sectionHf?.headerDefaultHeight, pageInSection, globalPageNumber), this.selectStoryHeight(sectionHf?.footerFirstHeight, sectionHf?.footerEvenHeight, sectionHf?.footerDefaultHeight, pageInSection, globalPageNumber));
+    }
+    /**
+     * The measured height of the running story this page position selects, mirroring
+     * {@link selectHeader}/{@link selectFooter}. Zero when the page has no such story.
+     */
+    selectStoryHeight(first, even, fallback, pageInSection, globalPageNumber) {
+        if (pageInSection === 1 && first != null)
+            return first;
+        if (globalPageNumber % 2 === 0 && even != null)
+            return even;
+        return fallback ?? 0;
     }
     /**
      * Measures the content height of a header or footer element.
-     * This is needed because headers/footers can contain more content than fits in the margin area.
+     *
+     * This is what tells {@link resolvePageBands} whether the story stays inside its margin or
+     * pushes the body, so it must measure the story ALONE — any padding added here would have to
+     * be added to the rendered band too, and the two drifting apart is exactly how a header
+     * silently starts overlapping body text.
      */
     measureHeaderFooterHeight(source, contentWidth) {
         // Create a temporary measurement container
@@ -1056,8 +1162,6 @@ export class PaginationEngine {
         measureContainer.style.visibility = "hidden";
         measureContainer.style.width = `${contentWidth}pt`;
         measureContainer.style.left = "-9999px";
-        // Add padding to match the actual rendering
-        measureContainer.style.paddingBottom = "4pt";
         // Clone and add the header/footer content
         for (const child of Array.from(source.childNodes)) {
             measureContainer.appendChild(child.cloneNode(true));
@@ -1083,7 +1187,7 @@ export class PaginationEngine {
         // Track page number within this section for first-page header/footer selection
         let pageInSection = 1;
         // Get effective content height for first page (accounts for header/footer sizes)
-        let { contentHeight: effectiveContentHeight } = this.getEffectiveHeights(dims, sectionIndex, pageInSection, pageNumber);
+        let { bodyHeight: effectiveContentHeight } = this.getPageBands(dims, sectionIndex, pageInSection, pageNumber);
         let remainingHeight = effectiveContentHeight;
         // Track the previous block's bottom margin for margin collapsing
         let prevMarginBottomPt = 0;
@@ -1123,8 +1227,8 @@ export class PaginationEngine {
             pageInSection++;
             currentContent = [];
             // Get effective content height for new page position
-            const newHeights = this.getEffectiveHeights(dims, sectionIndex, pageInSection, pageNumber);
-            effectiveContentHeight = newHeights.contentHeight;
+            const newBands = this.getPageBands(dims, sectionIndex, pageInSection, pageNumber);
+            effectiveContentHeight = newBands.bodyHeight;
             remainingHeight = effectiveContentHeight;
             prevMarginBottomPt = 0; // Reset margin tracking for new page
             currentFootnoteIds = []; // Reset footnotes for new page
@@ -1184,18 +1288,18 @@ export class PaginationEngine {
                         const totalChainFootnoteHeight = this.measureFootnotesHeight([...currentFootnoteIds, ...newChainFootnoteIds], dims.contentWidth, currentContinuation);
                         additionalChainFootnoteHeight = Math.max(0, totalChainFootnoteHeight - currentFootnoteHeight);
                     }
-                    const currentChainHeight = this.measureKeepWithNextChainBodyHeight(keepChain, prevMarginBottomPt, currentContent.length === 0) +
+                    const currentChainHeight = this.measureKeepWithNextChainBodyHeight(keepChain, prevMarginBottomPt, currentContent.length === 0, pageInSection) +
                         additionalChainFootnoteHeight;
                     const currentAvailableHeight = remainingHeight - currentFootnoteHeight;
                     if (currentChainHeight > currentAvailableHeight) {
-                        const nextPageHeights = this.getEffectiveHeights(dims, sectionIndex, pageInSection + 1, pageNumber + 1);
-                        const freshChainBodyHeight = this.measureKeepWithNextChainBodyHeight(keepChain, 0, true);
+                        const nextPageBands = this.getPageBands(dims, sectionIndex, pageInSection + 1, pageNumber + 1);
+                        const freshChainBodyHeight = this.measureKeepWithNextChainBodyHeight(keepChain, 0, true, pageInSection + 1);
                         // finishPage transfers this continuation to the new page's
                         // currentContinuation state, so include it in the destination
                         // page's footnote reservation before deciding to move the chain.
                         const freshChainFootnoteHeight = this.measureFootnotesHeight(newChainFootnoteIds, dims.contentWidth, nextPageContinuation);
                         if (freshChainBodyHeight + freshChainFootnoteHeight <=
-                            nextPageHeights.contentHeight) {
+                            nextPageBands.bodyHeight) {
                             finishPage();
                         }
                     }
@@ -1217,11 +1321,7 @@ export class PaginationEngine {
             // Calculate the effective height this block will consume
             // Account for margin collapsing: the gap between blocks is max(prevBottom, currTop), not sum
             const isFirstOnPage = currentContent.length === 0;
-            let effectiveMarginTop = block.marginTopPt;
-            if (!isFirstOnPage) {
-                // Margin collapsing: use the larger of the two adjacent margins
-                effectiveMarginTop = Math.max(block.marginTopPt, prevMarginBottomPt) - prevMarginBottomPt;
-            }
+            const effectiveMarginTop = this.effectiveBlockMarginTop(block, prevMarginBottomPt, isFirstOnPage, pageInSection);
             // Visible height = top margin gap + content + footnote space
             // Note: bottom margin is NOT included in the fit check because the last block's
             // bottom margin extends beyond the content area and is clipped by overflow:hidden.
@@ -1248,7 +1348,7 @@ export class PaginationEngine {
             // Check if block fits on current page (including its footnotes)
             if (blockSpace <= effectiveRemainingHeight) {
                 // Block fits with current footnote allocation
-                currentContent.push(block.element.cloneNode(true));
+                currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
                 remainingHeight -= (effectiveMarginTop + block.heightPt + block.marginBottomPt);
                 prevMarginBottomPt = block.marginBottomPt;
                 // Add new footnotes to current page
@@ -1257,7 +1357,8 @@ export class PaginationEngine {
                     currentFootnoteHeight += additionalFootnoteHeight;
                 }
             }
-            else if (block.heightPt + block.marginTopPt <= effectiveContentHeight) {
+            else if (block.heightPt + this.effectiveBlockMarginTop(block, 0, true, pageInSection + 1) <=
+                effectiveContentHeight) {
                 // Block doesn't fit with current allocation - try expanding footnote area
                 const blockSpaceWithoutFootnotes = effectiveMarginTop + block.heightPt;
                 // Check if block fits if we expand footnote area
@@ -1266,7 +1367,7 @@ export class PaginationEngine {
                 const canExpandFootnotes = minBodySpaceNeeded <= effectiveContentHeight;
                 if (newFootnoteIds.length > 0 && blockSpaceWithoutFootnotes <= effectiveRemainingHeight) {
                     // Block itself fits, but footnotes don't - expand footnote area
-                    currentContent.push(block.element.cloneNode(true));
+                    currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
                     remainingHeight -= (effectiveMarginTop + block.heightPt + block.marginBottomPt);
                     prevMarginBottomPt = block.marginBottomPt;
                     // Calculate EXPANDED space available for footnotes
@@ -1325,7 +1426,7 @@ export class PaginationEngine {
                     const bodySpaceAfterExpansion = effectiveContentHeight - expandedFootnoteSpace;
                     if (blockSpaceWithoutFootnotes <= bodySpaceAfterExpansion - bodyContentUsed) {
                         // Block fits after expanding footnote area.
-                        currentContent.push(block.element.cloneNode(true));
+                        currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
                         // `remainingHeight` tracks BODY consumption only — every other branch maintains it
                         // that way, and the footnote reserve is applied separately via `effectiveRemainingHeight`
                         // at the top of each iteration. Assigning `bodySpaceAfterExpansion - …` here folded the
@@ -1343,8 +1444,9 @@ export class PaginationEngine {
                         const newPageFootnoteHeight = allBlockFootnoteIds.length > 0
                             ? this.measureFootnotesHeight(allBlockFootnoteIds, dims.contentWidth, currentContinuation)
                             : (currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0);
-                        const newPageSpace = block.marginTopPt + block.heightPt + block.marginBottomPt;
-                        currentContent.push(block.element.cloneNode(true));
+                        const newPageMarginTop = this.effectiveBlockMarginTop(block, 0, true, pageInSection);
+                        const newPageSpace = newPageMarginTop + block.heightPt + block.marginBottomPt;
+                        currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
                         remainingHeight = effectiveContentHeight - newPageSpace;
                         prevMarginBottomPt = block.marginBottomPt;
                         // Merge, never replace: finishPage() may have just seeded this page with notes deferred
@@ -1361,9 +1463,9 @@ export class PaginationEngine {
                     const newPageFootnoteHeight = allBlockFootnoteIds.length > 0
                         ? this.measureFootnotesHeight(allBlockFootnoteIds, dims.contentWidth, currentContinuation)
                         : (currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0);
-                    // Include full top margin
-                    const newPageSpace = block.marginTopPt + block.heightPt + block.marginBottomPt;
-                    currentContent.push(block.element.cloneNode(true));
+                    const newPageMarginTop = this.effectiveBlockMarginTop(block, 0, true, pageInSection);
+                    const newPageSpace = newPageMarginTop + block.heightPt + block.marginBottomPt;
+                    currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
                     remainingHeight = effectiveContentHeight - newPageSpace;
                     prevMarginBottomPt = block.marginBottomPt;
                     // Merge, never replace: finishPage() may have just seeded this page with notes deferred
@@ -1390,7 +1492,7 @@ export class PaginationEngine {
                 if (currentContent.length > 0) {
                     finishPage();
                 }
-                currentContent.push(block.element.cloneNode(true));
+                currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
                 // Merge, never replace: finishPage() may have just seeded this page with notes deferred
                 // from the previous one, and overwriting here dropped them from the document.
                 currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
@@ -1425,6 +1527,144 @@ export class PaginationEngine {
                 el.setAttribute("contenteditable", "false");
         }
     }
+    /**
+     * Resolves floating DrawingML objects after their anchor paragraphs have landed on a page.
+     *
+     * The converter deliberately carries the OOXML bases and offsets as data instead of flattening
+     * them into CSS: page/margin/column bases belong to the page, while paragraph/line/character
+     * bases belong to the laid-out anchor. Once both coordinate systems exist, promote the object
+     * from the clipped text column into the page box and position it in one shared point space.
+     */
+    positionDrawingAnchors(pageBox, contentArea, dims, pageNumber) {
+        const anchors = Array.from(contentArea.querySelectorAll('[data-docx-drawing-anchor="true"]'));
+        if (anchors.length === 0)
+            return;
+        const pageRect = pageBox.getBoundingClientRect();
+        const pixelsPerPoint = pageRect.width / dims.pageWidth;
+        if (!(pixelsPerPoint > 0))
+            return;
+        for (const anchor of anchors) {
+            const staticRect = anchor.getBoundingClientRect();
+            const paragraph = anchor.closest('p, h1, h2, h3, h4, h5, h6');
+            const paragraphRect = paragraph?.getBoundingClientRect() ?? staticRect;
+            const toPageX = (x) => (x - pageRect.left) / pixelsPerPoint;
+            const toPageY = (y) => (y - pageRect.top) / pixelsPerPoint;
+            const context = {
+                staticLeft: toPageX(staticRect.left),
+                staticTop: toPageY(staticRect.top),
+                lineHeight: paragraph
+                    ? (parseFloat(getComputedStyle(paragraph).lineHeight) || staticRect.height) / pixelsPerPoint
+                    : staticRect.height / pixelsPerPoint,
+                paragraphLeft: toPageX(paragraphRect.left),
+                paragraphTop: toPageY(paragraphRect.top),
+                paragraphWidth: paragraphRect.width / pixelsPerPoint,
+                paragraphHeight: paragraphRect.height / pixelsPerPoint,
+            };
+            const widthReference = this.horizontalAnchorReference(anchor.getAttribute('data-docx-anchor-width-relative') ?? 'margin', dims, pageNumber, context);
+            const widthPercent = this.anchorNumber(anchor, 'width-percent');
+            if (widthPercent !== undefined) {
+                anchor.style.width = `${widthReference.size * widthPercent / 100}pt`;
+            }
+            const heightReference = this.verticalAnchorReference(anchor.getAttribute('data-docx-anchor-height-relative') ?? 'margin', dims, pageNumber, context);
+            const heightPercent = this.anchorNumber(anchor, 'height-percent');
+            if (heightPercent !== undefined && anchor.dataset.docxAnchorAutofit !== 'true') {
+                anchor.style.height = `${heightReference.size * heightPercent / 100}pt`;
+            }
+            // Read the final border-box size after relative sizing and before reparenting. The stored
+            // wp:extent remains the fallback; wps:bodyPr insets stay inside it through border-box sizing.
+            const sizedRect = anchor.getBoundingClientRect();
+            const width = sizedRect.width / pixelsPerPoint;
+            const height = sizedRect.height / pixelsPerPoint;
+            const horizontal = this.horizontalAnchorReference(anchor.getAttribute('data-docx-anchor-h-relative') ?? 'column', dims, pageNumber, context);
+            const vertical = this.verticalAnchorReference(anchor.getAttribute('data-docx-anchor-v-relative') ?? 'paragraph', dims, pageNumber, context);
+            const left = this.resolveAnchorAxis(horizontal, width, anchor.getAttribute('data-docx-anchor-h-align'), this.anchorNumber(anchor, 'h-offset'), pageNumber);
+            const top = this.resolveAnchorAxis(vertical, height, anchor.getAttribute('data-docx-anchor-v-align'), this.anchorNumber(anchor, 'v-offset'), pageNumber);
+            pageBox.appendChild(anchor);
+            anchor.style.position = 'absolute';
+            anchor.style.left = `${left}pt`;
+            anchor.style.top = `${top}pt`;
+            anchor.style.margin = '0';
+        }
+    }
+    anchorNumber(anchor, suffix) {
+        const raw = anchor.getAttribute(`data-docx-anchor-${suffix}`);
+        if (raw === null)
+            return undefined;
+        const value = Number(raw);
+        return Number.isFinite(value) ? value : undefined;
+    }
+    horizontalAnchorReference(relativeFrom, dims, pageNumber, context) {
+        const leftMargin = { start: 0, size: dims.marginLeft };
+        const rightMargin = {
+            start: dims.marginLeft + dims.contentWidth,
+            size: dims.marginRight,
+        };
+        switch (relativeFrom) {
+            case 'page':
+                return { start: 0, size: dims.pageWidth };
+            case 'character':
+                return { start: context.staticLeft, size: 0 };
+            case 'leftMargin':
+                return leftMargin;
+            case 'rightMargin':
+                return rightMargin;
+            case 'insideMargin':
+                return pageNumber % 2 === 1 ? leftMargin : rightMargin;
+            case 'outsideMargin':
+                return pageNumber % 2 === 1 ? rightMargin : leftMargin;
+            case 'paragraph':
+                // Not part of ST_RelFromH, but accepting it gives malformed/legacy producers the
+                // intuitive base without conflating it with the whole text column.
+                return { start: context.paragraphLeft, size: context.paragraphWidth };
+            case 'column':
+            case 'margin':
+            default:
+                // The paginator currently lays out one text column per section, so the column and page
+                // margin boxes coincide. Keeping the names distinct here leaves multi-column geometry
+                // localized to this resolver when that layout support is added.
+                return { start: dims.marginLeft, size: dims.contentWidth };
+        }
+    }
+    verticalAnchorReference(relativeFrom, dims, pageNumber, context) {
+        const topMargin = { start: 0, size: dims.marginTop };
+        const bottomMargin = {
+            start: dims.marginTop + dims.contentHeight,
+            size: dims.marginBottom,
+        };
+        switch (relativeFrom) {
+            case 'page':
+                return { start: 0, size: dims.pageHeight };
+            case 'paragraph':
+                return { start: context.paragraphTop, size: context.paragraphHeight };
+            case 'line':
+                return { start: context.staticTop, size: context.lineHeight };
+            case 'topMargin':
+                return topMargin;
+            case 'bottomMargin':
+                return bottomMargin;
+            case 'insideMargin':
+                return pageNumber % 2 === 1 ? topMargin : bottomMargin;
+            case 'outsideMargin':
+                return pageNumber % 2 === 1 ? bottomMargin : topMargin;
+            case 'margin':
+            default:
+                return { start: dims.marginTop, size: dims.contentHeight };
+        }
+    }
+    resolveAnchorAxis(reference, objectSize, alignment, offset, pageNumber) {
+        if (offset !== undefined)
+            return reference.start + offset;
+        let fraction = 0;
+        if (alignment === 'center')
+            fraction = 0.5;
+        else if (alignment === 'right' || alignment === 'bottom')
+            fraction = 1;
+        else if (alignment === 'inside')
+            fraction = pageNumber % 2 === 1 ? 0 : 1;
+        else if (alignment === 'outside')
+            fraction = pageNumber % 2 === 1 ? 1 : 0;
+        return reference.start + (reference.size - objectSize) * fraction;
+    }
     /**
      * Creates a page container element.
      */
@@ -1464,24 +1704,27 @@ export class PaginationEngine {
         // Needed by substitutePageNumberFields: a section that restarts numbering counts from its own
         // first page, not from the document's.
         pageBox.dataset.pageInSection = String(pageInSection);
-        // Get pre-computed effective heights for this page position (no re-measurement needed)
-        const effectiveHeights = this.getEffectiveHeights(dims, sectionIndex, pageInSection, pageNumber);
+        // Where the three bands sit on this page (no re-measurement needed)
+        const bands = this.getPageBands(dims, sectionIndex, pageInSection, pageNumber);
         // Add header if available for this section/page
         const headerSource = this.selectHeader(sectionIndex, pageInSection, pageNumber);
         if (headerSource) {
             const headerDiv = document.createElement("div");
             headerDiv.className = `${this.cssPrefix}header`;
             headerDiv.style.position = "absolute";
-            headerDiv.style.top = "0"; // Start at page top
+            // `w:header` is the distance to the TOP of the story, and the story grows downward from
+            // there; `flex-start` therefore pins the edge the OOXML actually declares, and content
+            // taller than the measurement clips at the bottom rather than sliding up the page.
+            headerDiv.style.top = `${bands.headerTop}pt`;
+            headerDiv.style.bottom = "auto";
             headerDiv.style.left = `${dims.marginLeft}pt`;
             headerDiv.style.width = `${dims.contentWidth}pt`;
-            headerDiv.style.height = `${effectiveHeights.headerHeight}pt`; // Use pre-computed effective height
+            headerDiv.style.height = `${bands.headerHeight}pt`;
             headerDiv.style.overflow = "hidden";
             headerDiv.style.boxSizing = "border-box";
             headerDiv.style.display = "flex";
             headerDiv.style.flexDirection = "column";
-            headerDiv.style.justifyContent = "flex-end"; // Align content to bottom of header area
-            headerDiv.style.paddingBottom = "4pt"; // Small gap before content area
+            headerDiv.style.justifyContent = "flex-start";
             // Clone the header content (skip the wrapper div's data attributes)
             for (const child of Array.from(headerSource.childNodes)) {
                 const clonedheaderDiv = child.cloneNode(true);
@@ -1492,8 +1735,8 @@ export class PaginationEngine {
             pageBox.appendChild(headerDiv);
         }
         // Create content area using pre-computed effective heights
-        const contentAreaTop = effectiveHeights.headerHeight;
-        const contentAreaHeight = effectiveHeights.contentHeight;
+        const contentAreaTop = bands.bodyTop;
+        const contentAreaHeight = bands.bodyHeight;
         const contentArea = document.createElement("div");
         contentArea.className = `${this.cssPrefix}content`;
         contentArea.style.position = "absolute";
@@ -1510,7 +1753,7 @@ export class PaginationEngine {
         // Add footnotes if any references appear on this page (or continuation from previous)
         const hasContinuation = continuation && continuation.remainingElements.length > 0;
         if (footnoteIds.length > 0 || hasContinuation) {
-            this.addPageFootnotes(pageBox, footnoteIds, dims, footnoteHeight, continuation, partialFootnotes);
+            this.addPageFootnotes(pageBox, footnoteIds, dims, bands, footnoteHeight, continuation, partialFootnotes);
         }
         // Add footer if available for this section/page
         const footerSource = this.selectFooter(sectionIndex, pageInSection, pageNumber);
@@ -1518,16 +1761,18 @@ export class PaginationEngine {
             const footerDiv = document.createElement("div");
             footerDiv.className = `${this.cssPrefix}footer`;
             footerDiv.style.position = "absolute";
-            footerDiv.style.bottom = "0"; // Start at page bottom
+            // `w:footer` is the distance to the BOTTOM of the story, and the story grows upward from
+            // there — the mirror of the header, so `flex-end` and a bottom anchor.
+            footerDiv.style.top = "auto";
+            footerDiv.style.bottom = `${dims.footerDistance}pt`;
             footerDiv.style.left = `${dims.marginLeft}pt`;
             footerDiv.style.width = `${dims.contentWidth}pt`;
-            footerDiv.style.height = `${effectiveHeights.footerHeight}pt`; // Use pre-computed effective height
+            footerDiv.style.height = `${bands.footerHeight}pt`;
             footerDiv.style.overflow = "hidden";
             footerDiv.style.boxSizing = "border-box";
             footerDiv.style.display = "flex";
             footerDiv.style.flexDirection = "column";
-            footerDiv.style.justifyContent = "flex-start"; // Align content to top of footer area
-            footerDiv.style.paddingTop = "4pt"; // Small gap after content area
+            footerDiv.style.justifyContent = "flex-end";
             // Clone the footer content (skip the wrapper div's data attributes)
             for (const child of Array.from(footerSource.childNodes)) {
                 const clonedfooterDiv = child.cloneNode(true);
@@ -1546,6 +1791,9 @@ export class PaginationEngine {
         }
         // Add to container
         this.containerElement.appendChild(pageBox);
+        // Floating objects need the final page and anchor-paragraph boxes. Resolve them only after
+        // append, when getBoundingClientRect() is meaningful, and lift them out of content clipping.
+        this.positionDrawingAnchors(pageBox, contentArea, dims, pageNumber);
         // Body and notes must occupy DISJOINT bands. The note block is absolutely positioned against
         // the page bottom and grows upward, while the content area spans the whole text height — so
         // nothing but the layout loop's arithmetic keeps them apart, and any disagreement between the