docxodus 9.8.0 → 9.9.0

package/dist/embed.iife.js

@@ -1544,6 +1544,9 @@ var Docxodus = (() => {
   }
 
   // src/pagination.ts
+  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;
+  }
   var MAX_FOOTNOTE_AREA_RATIO = 0.6;
   var MIN_BODY_CONTENT_HEIGHT = 72;
   var PaginationEngine = class {
@@ -1589,16 +1592,43 @@ var Docxodus = (() => {
       );
       this.pageNumbering = this.parsePageNumbering(sections);
       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) {
         this.stagingElement.style.visibility = "hidden";
         this.stagingElement.style.position = "absolute";
         this.stagingElement.style.left = "-9999px";
         this.stagingElement.style.display = "block";
-        section.style.width = `${dims.contentWidth}pt`;
-        const blocks = this.measureBlocks(section, dims);
-        const sectionPages = this.flowToPages(blocks, dims, pageNumber, sectionIndex);
+        const blocks = [];
+        for (const section of run.sections) {
+          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));
+          }
+        }
+        const sectionPages = this.flowToPages(blocks, run.dims, pageNumber, run.sectionIndex);
         pages.push(...sectionPages);
         pageNumber += sectionPages.length;
       }
@@ -1687,11 +1717,70 @@ var Docxodus = (() => {
           keepWithNext: child.dataset.keepWithNext === "true",
           keepLines: child.dataset.keepLines === "true",
           pageBreakBefore: child.dataset.pageBreakBefore === "true",
-          isPageBreak
+          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 start2 = 0;
+      while (start2 < children.length) {
+        if (isBreak(children[start2])) {
+          blocks.push(this.measureElement(children[start2], dims));
+          start2++;
+          continue;
+        }
+        let end = start2 + 1;
+        let container = makeContainer(children.slice(start2, end));
+        let measured = this.measureElement(container, dims);
+        while (end < children.length && !isBreak(children[end])) {
+          const candidate = makeContainer(children.slice(start2, 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
+        });
+        start2 = end;
+      }
+      return blocks;
+    }
     /**
      * Measures one element in the same hidden staging context used for the source blocks.
      * This is intentionally DOM-based: table row heights cannot be inferred from individual
@@ -1716,7 +1805,8 @@ var Docxodus = (() => {
         keepWithNext: element.dataset.keepWithNext === "true",
         keepLines: element.dataset.keepLines === "true",
         pageBreakBefore: element.dataset.pageBreakBefore === "true",
-        isPageBreak: element.dataset.pageBreak === "true" || element.classList.contains(`${this.cssPrefix}break`)
+        isPageBreak: element.dataset.pageBreak === "true" || element.classList.contains(`${this.cssPrefix}break`),
+        isWordParagraph: this.isWordParagraphElement(element)
       };
       this.stagingElement.removeChild(measurementHost);
       return measured;
@@ -1748,10 +1838,15 @@ var Docxodus = (() => {
      * 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];
@@ -1760,6 +1855,35 @@ var Docxodus = (() => {
       }
       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.
@@ -2565,7 +2689,8 @@ var Docxodus = (() => {
             const currentChainHeight = this.measureKeepWithNextChainBodyHeight(
               keepChain,
               prevMarginBottomPt,
-              currentContent.length === 0
+              currentContent.length === 0,
+              pageInSection
             ) + additionalChainFootnoteHeight;
             const currentAvailableHeight = remainingHeight - currentFootnoteHeight;
             if (currentChainHeight > currentAvailableHeight) {
@@ -2578,7 +2703,8 @@ var Docxodus = (() => {
               const freshChainBodyHeight = this.measureKeepWithNextChainBodyHeight(
                 keepChain,
                 0,
-                true
+                true,
+                pageInSection + 1
               );
               const freshChainFootnoteHeight = this.measureFootnotesHeight(
                 newChainFootnoteIds,
@@ -2604,10 +2730,12 @@ var Docxodus = (() => {
           additionalFootnoteHeight = totalFootnoteHeight - currentFootnoteHeight;
         }
         const isFirstOnPage = currentContent.length === 0;
-        let effectiveMarginTop = block.marginTopPt;
-        if (!isFirstOnPage) {
-          effectiveMarginTop = Math.max(block.marginTopPt, prevMarginBottomPt) - prevMarginBottomPt;
-        }
+        const effectiveMarginTop = this.effectiveBlockMarginTop(
+          block,
+          prevMarginBottomPt,
+          isFirstOnPage,
+          pageInSection
+        );
         const blockSpace = effectiveMarginTop + block.heightPt + additionalFootnoteHeight;
         const effectiveRemainingHeight = remainingHeight - currentFootnoteHeight;
         const bodyContentUsed = effectiveContentHeight - remainingHeight;
@@ -2627,19 +2755,19 @@ var Docxodus = (() => {
           }
         }
         if (blockSpace <= effectiveRemainingHeight) {
-          currentContent.push(block.element.cloneNode(true));
+          currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
           remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
           prevMarginBottomPt = block.marginBottomPt;
           if (newFootnoteIds.length > 0) {
             currentFootnoteIds.push(...newFootnoteIds);
             currentFootnoteHeight += additionalFootnoteHeight;
           }
-        } else if (block.heightPt + block.marginTopPt <= effectiveContentHeight) {
+        } else if (block.heightPt + this.effectiveBlockMarginTop(block, 0, true, pageInSection + 1) <= effectiveContentHeight) {
           const blockSpaceWithoutFootnotes = effectiveMarginTop + block.heightPt;
           const minBodySpaceNeeded = bodyContentUsed + blockSpaceWithoutFootnotes + MIN_BODY_CONTENT_HEIGHT;
           const canExpandFootnotes = minBodySpaceNeeded <= effectiveContentHeight;
           if (newFootnoteIds.length > 0 && blockSpaceWithoutFootnotes <= effectiveRemainingHeight) {
-            currentContent.push(block.element.cloneNode(true));
+            currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
             remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
             prevMarginBottomPt = block.marginBottomPt;
             const availableForFootnotes = Math.min(
@@ -2686,7 +2814,7 @@ var Docxodus = (() => {
             const expandedFootnoteSpace = Math.min(maxFootnoteArea, additionalFootnoteHeight + currentFootnoteHeight);
             const bodySpaceAfterExpansion = effectiveContentHeight - expandedFootnoteSpace;
             if (blockSpaceWithoutFootnotes <= bodySpaceAfterExpansion - bodyContentUsed) {
-              currentContent.push(block.element.cloneNode(true));
+              currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
               remainingHeight = bodySpaceAfterExpansion - bodyContentUsed - blockSpaceWithoutFootnotes;
               prevMarginBottomPt = block.marginBottomPt;
               currentFootnoteIds.push(...newFootnoteIds);
@@ -2694,8 +2822,14 @@ var Docxodus = (() => {
             } else {
               finishPage();
               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;
               currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
@@ -2704,8 +2838,14 @@ var Docxodus = (() => {
           } else {
             finishPage();
             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;
             currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
@@ -2724,7 +2864,7 @@ var Docxodus = (() => {
           if (currentContent.length > 0) {
             finishPage();
           }
-          currentContent.push(block.element.cloneNode(true));
+          currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
           currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
           finishPage();
         }
@@ -9254,6 +9394,7 @@ var Docxodus = (() => {
   color: var(--dxr-ink);
   background: var(--dxr-desk);
   -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
 }
 .dxr *, .dxr *::before, .dxr *::after { box-sizing: border-box; }
 

package/dist/pagination.bundle.js

@@ -125,6 +125,9 @@ var DocxodusPagination = (() => {
   }
 
   // src/pagination.ts
+  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;
+  }
   var MAX_FOOTNOTE_AREA_RATIO = 0.6;
   var MIN_BODY_CONTENT_HEIGHT = 72;
   var PaginationEngine = class {
@@ -170,16 +173,43 @@ var DocxodusPagination = (() => {
       );
       this.pageNumbering = this.parsePageNumbering(sections);
       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) {
         this.stagingElement.style.visibility = "hidden";
         this.stagingElement.style.position = "absolute";
         this.stagingElement.style.left = "-9999px";
         this.stagingElement.style.display = "block";
-        section.style.width = `${dims.contentWidth}pt`;
-        const blocks = this.measureBlocks(section, dims);
-        const sectionPages = this.flowToPages(blocks, dims, pageNumber, sectionIndex);
+        const blocks = [];
+        for (const section of run.sections) {
+          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));
+          }
+        }
+        const sectionPages = this.flowToPages(blocks, run.dims, pageNumber, run.sectionIndex);
         pages.push(...sectionPages);
         pageNumber += sectionPages.length;
       }
@@ -268,11 +298,70 @@ var DocxodusPagination = (() => {
           keepWithNext: child.dataset.keepWithNext === "true",
           keepLines: child.dataset.keepLines === "true",
           pageBreakBefore: child.dataset.pageBreakBefore === "true",
-          isPageBreak
+          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;
+        }
+        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;
+    }
     /**
      * Measures one element in the same hidden staging context used for the source blocks.
      * This is intentionally DOM-based: table row heights cannot be inferred from individual
@@ -297,7 +386,8 @@ var DocxodusPagination = (() => {
         keepWithNext: element.dataset.keepWithNext === "true",
         keepLines: element.dataset.keepLines === "true",
         pageBreakBefore: element.dataset.pageBreakBefore === "true",
-        isPageBreak: element.dataset.pageBreak === "true" || element.classList.contains(`${this.cssPrefix}break`)
+        isPageBreak: element.dataset.pageBreak === "true" || element.classList.contains(`${this.cssPrefix}break`),
+        isWordParagraph: this.isWordParagraphElement(element)
       };
       this.stagingElement.removeChild(measurementHost);
       return measured;
@@ -329,10 +419,15 @@ var DocxodusPagination = (() => {
      * 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];
@@ -341,6 +436,35 @@ var DocxodusPagination = (() => {
       }
       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.
@@ -1146,7 +1270,8 @@ var DocxodusPagination = (() => {
             const currentChainHeight = this.measureKeepWithNextChainBodyHeight(
               keepChain,
               prevMarginBottomPt,
-              currentContent.length === 0
+              currentContent.length === 0,
+              pageInSection
             ) + additionalChainFootnoteHeight;
             const currentAvailableHeight = remainingHeight - currentFootnoteHeight;
             if (currentChainHeight > currentAvailableHeight) {
@@ -1159,7 +1284,8 @@ var DocxodusPagination = (() => {
               const freshChainBodyHeight = this.measureKeepWithNextChainBodyHeight(
                 keepChain,
                 0,
-                true
+                true,
+                pageInSection + 1
               );
               const freshChainFootnoteHeight = this.measureFootnotesHeight(
                 newChainFootnoteIds,
@@ -1185,10 +1311,12 @@ var DocxodusPagination = (() => {
           additionalFootnoteHeight = totalFootnoteHeight - currentFootnoteHeight;
         }
         const isFirstOnPage = currentContent.length === 0;
-        let effectiveMarginTop = block.marginTopPt;
-        if (!isFirstOnPage) {
-          effectiveMarginTop = Math.max(block.marginTopPt, prevMarginBottomPt) - prevMarginBottomPt;
-        }
+        const effectiveMarginTop = this.effectiveBlockMarginTop(
+          block,
+          prevMarginBottomPt,
+          isFirstOnPage,
+          pageInSection
+        );
         const blockSpace = effectiveMarginTop + block.heightPt + additionalFootnoteHeight;
         const effectiveRemainingHeight = remainingHeight - currentFootnoteHeight;
         const bodyContentUsed = effectiveContentHeight - remainingHeight;
@@ -1208,19 +1336,19 @@ var DocxodusPagination = (() => {
           }
         }
         if (blockSpace <= effectiveRemainingHeight) {
-          currentContent.push(block.element.cloneNode(true));
+          currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
           remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
           prevMarginBottomPt = block.marginBottomPt;
           if (newFootnoteIds.length > 0) {
             currentFootnoteIds.push(...newFootnoteIds);
             currentFootnoteHeight += additionalFootnoteHeight;
           }
-        } else if (block.heightPt + block.marginTopPt <= effectiveContentHeight) {
+        } else if (block.heightPt + this.effectiveBlockMarginTop(block, 0, true, pageInSection + 1) <= effectiveContentHeight) {
           const blockSpaceWithoutFootnotes = effectiveMarginTop + block.heightPt;
           const minBodySpaceNeeded = bodyContentUsed + blockSpaceWithoutFootnotes + MIN_BODY_CONTENT_HEIGHT;
           const canExpandFootnotes = minBodySpaceNeeded <= effectiveContentHeight;
           if (newFootnoteIds.length > 0 && blockSpaceWithoutFootnotes <= effectiveRemainingHeight) {
-            currentContent.push(block.element.cloneNode(true));
+            currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
             remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
             prevMarginBottomPt = block.marginBottomPt;
             const availableForFootnotes = Math.min(
@@ -1267,7 +1395,7 @@ var DocxodusPagination = (() => {
             const expandedFootnoteSpace = Math.min(maxFootnoteArea, additionalFootnoteHeight + currentFootnoteHeight);
             const bodySpaceAfterExpansion = effectiveContentHeight - expandedFootnoteSpace;
             if (blockSpaceWithoutFootnotes <= bodySpaceAfterExpansion - bodyContentUsed) {
-              currentContent.push(block.element.cloneNode(true));
+              currentContent.push(this.cloneBlockForPage(block, isFirstOnPage, pageInSection));
               remainingHeight = bodySpaceAfterExpansion - bodyContentUsed - blockSpaceWithoutFootnotes;
               prevMarginBottomPt = block.marginBottomPt;
               currentFootnoteIds.push(...newFootnoteIds);
@@ -1275,8 +1403,14 @@ var DocxodusPagination = (() => {
             } else {
               finishPage();
               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;
               currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
@@ -1285,8 +1419,14 @@ var DocxodusPagination = (() => {
           } else {
             finishPage();
             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;
             currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
@@ -1305,7 +1445,7 @@ var DocxodusPagination = (() => {
           if (currentContent.length > 0) {
             finishPage();
           }
-          currentContent.push(block.element.cloneNode(true));
+          currentContent.push(this.cloneBlockForPage(block, true, pageInSection));
           currentFootnoteIds = [...currentFootnoteIds, ...allBlockFootnoteIds];
           finishPage();
         }

package/dist/pagination.d.ts

@@ -59,6 +59,8 @@ export interface MeasuredBlock {
     pageBreakBefore: boolean;
     /** Whether this is a page break marker */
     isPageBreak: boolean;
+    /** Whether the block is a Word paragraph whose top margin represents paragraph space-before */
+    isWordParagraph?: boolean;
 }
 /**
  * Information about a rendered page.
@@ -162,6 +164,18 @@ export declare class PaginationEngine {
      * Measures all content blocks in a section.
      */
     private measureBlocks;
+    /**
+     * 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.
+     */
+    private buildColumnBlocks;
     /**
      * Measures one element in the same hidden staging context used for the source blocks.
      * This is intentionally DOM-based: table row heights cannot be inferred from individual
@@ -182,6 +196,20 @@ export declare class PaginationEngine {
      * intentionally excluded, matching the individual block fit check.
      */
     private measureKeepWithNextChainBodyHeight;
+    /** Word paragraphs render as `p`, or as `h1`–`h6` when their style has an outline level. */
+    private isWordParagraphElement;
+    private shouldSuppressPageTopSpacing;
+    /**
+     * 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.
+     */
+    private effectiveBlockMarginTop;
+    /** Clone a source block with the same page-top spacing decision used by the height budget. */
+    private cloneBlockForPage;
     /**
      * Finds footnote references introduced by a sequence of blocks, preserving
      * document order and excluding references already assigned to the page.