docxodus 7.1.0 → 8.0.0

package/dist/pagination.bundle.js

@@ -82,6 +82,7 @@ var DocxodusPagination = (() => {
       this.cssPrefix = options.cssPrefix ?? "page-";
       this.showPageNumbers = options.showPageNumbers ?? true;
       this.pageGap = options.pageGap ?? 20;
+      this.fragmentParagraphs = options.fragmentParagraphs ?? false;
       this.hfRegistry = /* @__PURE__ */ new Map();
       this.footnoteRegistry = /* @__PURE__ */ new Map();
     }
@@ -148,6 +149,393 @@ var DocxodusPagination = (() => {
       }
       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
+     * rows because wrapping and collapsed borders change the height of a fragment.
+     */
+    measureElement(element, dims) {
+      const measurementHost = document.createElement("div");
+      measurementHost.style.position = "absolute";
+      measurementHost.style.visibility = "hidden";
+      measurementHost.style.left = "-9999px";
+      measurementHost.style.width = `${dims.contentWidth}pt`;
+      const measuredElement = element.cloneNode(true);
+      measurementHost.appendChild(measuredElement);
+      this.stagingElement.appendChild(measurementHost);
+      const rect = measuredElement.getBoundingClientRect();
+      const style = window.getComputedStyle(measuredElement);
+      const measured = {
+        element,
+        heightPt: pxToPt(rect.height),
+        marginTopPt: pxToPt(parseFloat(style.marginTop) || 0),
+        marginBottomPt: pxToPt(parseFloat(style.marginBottom) || 0),
+        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`)
+      };
+      this.stagingElement.removeChild(measurementHost);
+      return measured;
+    }
+    /**
+     * Returns the contiguous keep-with-next chain beginning at a block.
+     *
+     * A hard page break or a page-break-before directive is stronger than a
+     * keep-with-next directive, so it terminates the chain. The caller only
+     * keeps a chain together when the whole chain can fit on a fresh page.
+     */
+    getKeepWithNextChain(blocks, startIndex) {
+      const firstBlock = blocks[startIndex];
+      if (!firstBlock) return [];
+      const chain = [firstBlock];
+      let lastIndex = startIndex;
+      while (blocks[lastIndex].keepWithNext) {
+        const nextBlock = blocks[lastIndex + 1];
+        if (!nextBlock || nextBlock.isPageBreak || nextBlock.pageBreakBefore) {
+          break;
+        }
+        chain.push(nextBlock);
+        lastIndex++;
+      }
+      return chain;
+    }
+    /**
+     * Measures the visible body height of a keep-with-next chain using the same
+     * collapsed-margin rules as normal block placement. The trailing margin is
+     * intentionally excluded, matching the individual block fit check.
+     */
+    measureKeepWithNextChainBodyHeight(chain, previousMarginBottomPt, isFirstOnPage) {
+      const firstBlock = chain[0];
+      if (!firstBlock) return 0;
+      const firstMarginTop = isFirstOnPage ? firstBlock.marginTopPt : Math.max(firstBlock.marginTopPt, previousMarginBottomPt) - previousMarginBottomPt;
+      let bodyHeight = firstMarginTop + firstBlock.heightPt;
+      for (let index = 1; index < chain.length; index++) {
+        const previousBlock = chain[index - 1];
+        const block = chain[index];
+        bodyHeight += Math.max(previousBlock.marginBottomPt, block.marginTopPt) + block.heightPt;
+      }
+      return bodyHeight;
+    }
+    /**
+     * Finds footnote references introduced by a sequence of blocks, preserving
+     * document order and excluding references already assigned to the page.
+     */
+    collectNewFootnoteIds(blocks, existingFootnoteIds) {
+      const knownIds = new Set(existingFootnoteIds);
+      const newIds = [];
+      for (const block of blocks) {
+        for (const id of this.extractFootnoteRefs(block.element)) {
+          if (!knownIds.has(id)) {
+            knownIds.add(id);
+            newIds.push(id);
+          }
+        }
+      }
+      return newIds;
+    }
+    /**
+     * The shortest body available to a section's first, default, or even page.
+     * A row fragment must fit every variant, otherwise a later header/footer could
+     * 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
+      );
+    }
+    /**
+     * Builds a clone of a simple table wrapper containing a contiguous run of rows.
+     * Complex table features are deliberately rejected by the caller: a split across
+     * merged cells, nested tables, or footnotes cannot be made correct by cloning rows.
+     */
+    createSimpleTableFragment(wrapper, table, body, rows, retainAnchor) {
+      const wrapperClone = wrapper.cloneNode(false);
+      const tableClone = table.cloneNode(false);
+      for (const child of Array.from(table.children)) {
+        if (child !== body) {
+          tableClone.appendChild(child.cloneNode(true));
+        }
+      }
+      const bodyClone = body.cloneNode(false);
+      for (const row of rows) {
+        bodyClone.appendChild(row.cloneNode(true));
+      }
+      tableClone.appendChild(bodyClone);
+      if (!retainAnchor) {
+        wrapperClone.removeAttribute("data-anchor");
+        tableClone.removeAttribute("data-anchor");
+      }
+      wrapperClone.appendChild(tableClone);
+      return wrapperClone;
+    }
+    /**
+     * Splits an oversized, ordinary table at row boundaries. This only participates
+     * in the existing oversized-block fallback; unsupported tables keep the previous
+     * overflow behavior rather than risking broken table semantics.
+     */
+    trySplitSimpleOversizedTable(block, dims, sectionIndex) {
+      const wrapper = block.element;
+      if (wrapper.tagName !== "DIV" || wrapper.children.length !== 1 || block.keepWithNext || block.keepLines || block.pageBreakBefore || block.isPageBreak) {
+        return null;
+      }
+      const table = wrapper.firstElementChild;
+      if (!(table instanceof HTMLTableElement)) {
+        return null;
+      }
+      const body = table.tBodies.length === 1 ? table.tBodies[0] : null;
+      if (!body || table.tHead || table.tFoot || body.rows.length < 2 || Array.from(table.children).some((child) => child !== body && child.tagName !== "COLGROUP") || table.querySelector("table, [rowspan], [colspan], [data-footnote-id]") || wrapper.querySelector("[data-footnote-id]")) {
+        return null;
+      }
+      const rows = Array.from(body.rows);
+      const minimumContentHeight = this.smallestEffectiveContentHeight(dims, sectionIndex);
+      const maximumFragmentHeight = minimumContentHeight - block.marginTopPt - block.marginBottomPt;
+      if (maximumFragmentHeight <= 0) {
+        return null;
+      }
+      const groups = [];
+      let start = 0;
+      while (start < rows.length) {
+        let end = start;
+        while (end < rows.length) {
+          const candidate = this.createSimpleTableFragment(
+            wrapper,
+            table,
+            body,
+            rows.slice(start, end + 1),
+            start === 0
+          );
+          const measured = this.measureElement(candidate, dims);
+          if (measured.heightPt > maximumFragmentHeight) {
+            break;
+          }
+          end++;
+        }
+        if (end === start) {
+          return null;
+        }
+        groups.push(rows.slice(start, end));
+        start = end;
+      }
+      if (groups.length < 2) {
+        return null;
+      }
+      const fragments = [];
+      for (let index = 0; index < groups.length; index++) {
+        const isFirst = index === 0;
+        const isLast = index === groups.length - 1;
+        const fragment = this.createSimpleTableFragment(
+          wrapper,
+          table,
+          body,
+          groups[index],
+          isFirst
+        );
+        if (!isFirst) {
+          fragment.style.setProperty("margin-top", "0", "important");
+        }
+        if (!isLast) {
+          fragment.style.setProperty("margin-bottom", "0", "important");
+        }
+        const measured = this.measureElement(fragment, dims);
+        if (measured.heightPt + measured.marginTopPt + measured.marginBottomPt > minimumContentHeight) {
+          return null;
+        }
+        fragments.push({
+          ...measured,
+          keepWithNext: false,
+          keepLines: false,
+          pageBreakBefore: false,
+          isPageBreak: false
+        });
+      }
+      return fragments;
+    }
+    /**
+     * A DOM endpoint that can finish a paragraph fragment. Endpoints are chosen
+     * after whitespace or at a run boundary so the paginator never deliberately
+     * cuts through an ordinary word merely to fill a little more of a page.
+     */
+    paragraphFragmentEndpoints(paragraph) {
+      const endpoints = [];
+      const walker = document.createTreeWalker(paragraph, NodeFilter.SHOW_TEXT);
+      let textNode;
+      while (textNode = walker.nextNode()) {
+        const text = textNode.data;
+        if (text.length === 0) continue;
+        const whitespace = /\s+/g;
+        let match;
+        while ((match = whitespace.exec(text)) !== null) {
+          endpoints.push({ node: textNode, offset: match.index + match[0].length });
+        }
+        if (endpoints.length === 0 || endpoints[endpoints.length - 1].node !== textNode || endpoints[endpoints.length - 1].offset !== text.length) {
+          endpoints.push({ node: textNode, offset: text.length });
+        }
+      }
+      return endpoints;
+    }
+    /**
+     * Whether a range contains visible text after ignoring bidi/zero-width marks.
+     * Paragraph fragmentation deliberately excludes non-textual descendants, so
+     * this is enough to reject empty head or tail fragments.
+     */
+    hasVisibleFragmentText(fragment) {
+      return (fragment.textContent || "").replace(/[\u200B-\u200F\uFEFF]/g, "").trim().length > 0;
+    }
+    /**
+     * Phase one only handles text-like paragraph descendants. Objects, explicit
+     * line breaks, list markers, notes, and out-of-flow/inline-block content all
+     * require their own line-layout rules and retain the established whole-block
+     * fallback instead of risking broken content or duplicate anchors.
+     */
+    canFragmentParagraph(block) {
+      if (!this.fragmentParagraphs || block.element.tagName !== "P") {
+        return false;
+      }
+      const paragraph = block.element;
+      if (block.keepWithNext || block.keepLines || block.pageBreakBefore || block.isPageBreak || paragraph.dataset.widowControl === "true" || paragraph.hasAttribute("contenteditable")) {
+        return false;
+      }
+      const unsupportedDescendants = [
+        "br",
+        "img",
+        "picture",
+        "svg",
+        "math",
+        "canvas",
+        "video",
+        "audio",
+        "iframe",
+        "object",
+        "embed",
+        "input",
+        "button",
+        "select",
+        "textarea",
+        "table",
+        "ol",
+        "ul",
+        "li",
+        "dl",
+        "div",
+        "p",
+        "section",
+        "article",
+        "aside",
+        "figure",
+        "fieldset",
+        "details",
+        "[data-footnote-id]",
+        "[data-list-marker]",
+        "[data-anchor]",
+        "[id]",
+        "[contenteditable]"
+      ].join(", ");
+      if (paragraph.querySelector(unsupportedDescendants)) {
+        return false;
+      }
+      const paragraphStyle = window.getComputedStyle(paragraph);
+      if (paragraphStyle.display !== "block" || paragraphStyle.position !== "static" || paragraphStyle.float !== "none" || paragraphStyle.whiteSpace !== "normal" || paragraphStyle.breakBefore !== "auto" || paragraphStyle.breakAfter !== "auto" || paragraphStyle.breakInside === "avoid" || paragraphStyle.pageBreakBefore !== "auto" || paragraphStyle.pageBreakAfter !== "auto" || paragraphStyle.pageBreakInside === "avoid") {
+        return false;
+      }
+      for (const descendant of Array.from(paragraph.querySelectorAll("*"))) {
+        const style = window.getComputedStyle(descendant);
+        if (style.display !== "inline" || style.position !== "static" || style.float !== "none" || style.whiteSpace !== "normal") {
+          return false;
+        }
+      }
+      return true;
+    }
+    /**
+     * Builds one range-cloned paragraph fragment. Only the leading fragment keeps
+     * the source paragraph's addressability; continuations must not duplicate an
+     * id/data-anchor in the rendered document.
+     */
+    createParagraphFragment(paragraph, range, retainSourceIdentity, isFinalFragment) {
+      const fragment = paragraph.cloneNode(false);
+      const contents = range.cloneContents();
+      fragment.appendChild(contents);
+      if (!retainSourceIdentity) {
+        fragment.removeAttribute("id");
+        fragment.removeAttribute("data-anchor");
+        fragment.style.setProperty("margin-top", "0", "important");
+        fragment.style.setProperty("text-indent", "0", "important");
+      }
+      if (!isFinalFragment) {
+        fragment.style.setProperty("margin-bottom", "0", "important");
+      }
+      return fragment;
+    }
+    /**
+     * Splits a simple paragraph at the largest DOM Range endpoint that fits the
+     * currently available body space. The caller then processes the tail normally,
+     * allowing it to fragment again on later pages when necessary.
+     */
+    tryFragmentParagraph(block, dims, availableHeightPt, effectiveMarginTopPt) {
+      if (!this.canFragmentParagraph(block) || availableHeightPt <= effectiveMarginTopPt) {
+        return null;
+      }
+      const paragraph = block.element;
+      const endpoints = this.paragraphFragmentEndpoints(paragraph);
+      if (endpoints.length < 2) {
+        return null;
+      }
+      let low = 0;
+      let high = endpoints.length - 2;
+      let best = null;
+      while (low <= high) {
+        const middle = Math.floor((low + high) / 2);
+        const endpoint = endpoints[middle];
+        const headRange = document.createRange();
+        headRange.setStart(paragraph, 0);
+        headRange.setEnd(endpoint.node, endpoint.offset);
+        const headContents = headRange.cloneContents();
+        if (!this.hasVisibleFragmentText(headContents)) {
+          low = middle + 1;
+          continue;
+        }
+        const head = this.createParagraphFragment(paragraph, headRange, true, false);
+        const measured = this.measureElement(head, dims);
+        if (effectiveMarginTopPt + measured.heightPt <= availableHeightPt) {
+          best = { endpoint, element: head, measured };
+          low = middle + 1;
+        } else {
+          high = middle - 1;
+        }
+      }
+      if (!best) {
+        return null;
+      }
+      const tailRange = document.createRange();
+      tailRange.setStart(best.endpoint.node, best.endpoint.offset);
+      tailRange.setEnd(paragraph, paragraph.childNodes.length);
+      const tailContents = tailRange.cloneContents();
+      if (!this.hasVisibleFragmentText(tailContents)) {
+        return null;
+      }
+      const tail = this.createParagraphFragment(paragraph, tailRange, false, true);
+      const tailMeasured = this.measureElement(tail, dims);
+      return [
+        {
+          ...best.measured,
+          element: best.element,
+          keepWithNext: false,
+          keepLines: false,
+          pageBreakBefore: false,
+          isPageBreak: false
+        },
+        {
+          ...tailMeasured,
+          element: tail,
+          keepWithNext: false,
+          keepLines: false,
+          pageBreakBefore: false,
+          isPageBreak: false
+        }
+      ];
+    }
     /**
      * Parses the header/footer registry from the staging element.
      * Also measures heights during parsing for lazy-loading compatibility.
@@ -546,7 +934,8 @@ var DocxodusPagination = (() => {
         currentFootnoteHeight = this.measureContinuationHeight(currentContinuation, dims.contentWidth);
       }
       const finishPage = () => {
-        if (currentContent.length === 0 && !currentContinuation) return;
+        const hasCurrentContinuation = (currentContinuation?.remainingElements.length ?? 0) > 0;
+        if (currentContent.length === 0 && !hasCurrentContinuation) return;
         const page = this.createPage(
           dims,
           pageNumber,
@@ -578,7 +967,6 @@ var DocxodusPagination = (() => {
       };
       for (let i = 0; i < blocks.length; i++) {
         const block = blocks[i];
-        const nextBlock = blocks[i + 1];
         if (block.isPageBreak) {
           finishPage();
           continue;
@@ -586,8 +974,59 @@ var DocxodusPagination = (() => {
         if (block.pageBreakBefore && currentContent.length > 0) {
           finishPage();
         }
-        const blockFootnoteIds = this.extractFootnoteRefs(block.element);
-        const newFootnoteIds = blockFootnoteIds.filter((id) => !currentFootnoteIds.includes(id));
+        const previousBlock = blocks[i - 1];
+        const startsKeepChain = !previousBlock || !previousBlock.keepWithNext || previousBlock.isPageBreak || block.pageBreakBefore;
+        const pageHasOccupiedSpace = currentContent.length > 0 || currentFootnoteHeight > 0;
+        if (pageHasOccupiedSpace && block.keepWithNext && startsKeepChain) {
+          const keepChain = this.getKeepWithNextChain(blocks, i);
+          if (keepChain.length > 1) {
+            const newChainFootnoteIds = this.collectNewFootnoteIds(
+              keepChain,
+              currentFootnoteIds
+            );
+            let additionalChainFootnoteHeight = 0;
+            if (newChainFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
+              const totalChainFootnoteHeight = this.measureFootnotesHeight(
+                [...currentFootnoteIds, ...newChainFootnoteIds],
+                dims.contentWidth,
+                currentContinuation
+              );
+              additionalChainFootnoteHeight = Math.max(
+                0,
+                totalChainFootnoteHeight - currentFootnoteHeight
+              );
+            }
+            const currentChainHeight = this.measureKeepWithNextChainBodyHeight(
+              keepChain,
+              prevMarginBottomPt,
+              currentContent.length === 0
+            ) + 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 freshChainFootnoteHeight = this.measureFootnotesHeight(
+                newChainFootnoteIds,
+                dims.contentWidth,
+                nextPageContinuation
+              );
+              if (freshChainBodyHeight + freshChainFootnoteHeight <= nextPageHeights.contentHeight) {
+                finishPage();
+              }
+            }
+          }
+        }
+        const allBlockFootnoteIds = this.extractFootnoteRefs(block.element);
+        const newFootnoteIds = this.collectNewFootnoteIds([block], currentFootnoteIds);
         let additionalFootnoteHeight = 0;
         if (newFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
           const combinedFootnoteIds = [...currentFootnoteIds, ...newFootnoteIds];
@@ -604,15 +1043,23 @@ var DocxodusPagination = (() => {
           effectiveMarginTop = Math.max(block.marginTopPt, prevMarginBottomPt) - prevMarginBottomPt;
         }
         const blockSpace = effectiveMarginTop + block.heightPt + additionalFootnoteHeight;
-        let neededHeight = blockSpace;
-        if (block.keepWithNext && nextBlock && !nextBlock.isPageBreak) {
-          const collapsedMargin = Math.max(block.marginBottomPt, nextBlock.marginTopPt);
-          neededHeight = effectiveMarginTop + block.heightPt + collapsedMargin + nextBlock.heightPt + additionalFootnoteHeight;
-        }
         const effectiveRemainingHeight = remainingHeight - currentFootnoteHeight;
         const bodyContentUsed = effectiveContentHeight - remainingHeight;
         const maxFootnoteArea = effectiveContentHeight * MAX_FOOTNOTE_AREA_RATIO;
         const maxFootnoteExpansion = Math.max(0, maxFootnoteArea - currentFootnoteHeight);
+        if (blockSpace > effectiveRemainingHeight) {
+          const paragraphFragments = this.tryFragmentParagraph(
+            block,
+            dims,
+            effectiveRemainingHeight,
+            effectiveMarginTop
+          );
+          if (paragraphFragments) {
+            blocks.splice(i, 1, ...paragraphFragments);
+            i--;
+            continue;
+          }
+        }
         if (blockSpace <= effectiveRemainingHeight) {
           currentContent.push(block.element.cloneNode(true));
           remainingHeight -= effectiveMarginTop + block.heightPt + block.marginBottomPt;
@@ -654,10 +1101,12 @@ var DocxodusPagination = (() => {
                       footnoteId,
                       fittingElements: fits
                     });
-                    nextPageContinuation = {
-                      footnoteId,
-                      remainingElements: overflow
-                    };
+                    if (overflow.length > 0) {
+                      nextPageContinuation = {
+                        footnoteId,
+                        remainingElements: overflow
+                      };
+                    }
                     currentFootnoteHeight = availableForFootnotes;
                   } else {
                     nextPageContinuation = {
@@ -690,30 +1139,39 @@ var DocxodusPagination = (() => {
               currentFootnoteHeight = expandedFootnoteSpace;
             } else {
               finishPage();
-              const newPageFootnoteHeight = blockFootnoteIds.length > 0 ? this.measureFootnotesHeight(blockFootnoteIds, dims.contentWidth, currentContinuation) : currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0;
+              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));
               remainingHeight = effectiveContentHeight - newPageSpace;
               prevMarginBottomPt = block.marginBottomPt;
-              currentFootnoteIds = [...blockFootnoteIds];
+              currentFootnoteIds = [...allBlockFootnoteIds];
               currentFootnoteHeight = newPageFootnoteHeight;
             }
           } else {
             finishPage();
-            const newPageFootnoteHeight = blockFootnoteIds.length > 0 ? this.measureFootnotesHeight(blockFootnoteIds, dims.contentWidth, currentContinuation) : currentContinuation ? this.measureContinuationHeight(currentContinuation, dims.contentWidth) : 0;
+            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));
             remainingHeight = effectiveContentHeight - newPageSpace;
             prevMarginBottomPt = block.marginBottomPt;
-            currentFootnoteIds = [...blockFootnoteIds];
+            currentFootnoteIds = [...allBlockFootnoteIds];
             currentFootnoteHeight = newPageFootnoteHeight;
           }
         } else {
+          const tableFragments = this.trySplitSimpleOversizedTable(block, dims, sectionIndex);
+          if (tableFragments) {
+            if (currentContent.length > 0 || currentContinuation) {
+              finishPage();
+            }
+            blocks.splice(i, 1, ...tableFragments);
+            i--;
+            continue;
+          }
           if (currentContent.length > 0) {
             finishPage();
           }
           currentContent.push(block.element.cloneNode(true));
-          currentFootnoteIds = [...blockFootnoteIds];
+          currentFootnoteIds = [...allBlockFootnoteIds];
           finishPage();
         }
       }
@@ -837,7 +1295,10 @@ var DocxodusPagination = (() => {
     if (!pageContainer) {
       throw new Error("Pagination container element not found");
     }
-    const engine = new PaginationEngine(staging, pageContainer, options);
+    const engine = new PaginationEngine(staging, pageContainer, {
+      ...options,
+      fragmentParagraphs: options.fragmentParagraphs ?? true
+    });
     return engine.paginate();
   }
   return __toCommonJS(pagination_exports);

package/dist/pagination.d.ts

@@ -117,6 +117,12 @@ export interface PaginationOptions {
     showPageNumbers?: boolean;
     /** Gap between pages in pixels. Default: 20 */
     pageGap?: number;
+    /**
+     * Whether ordinary paragraphs may be fragmented across page boundaries.
+     * Defaults to false for direct PaginationEngine callers; read-only viewer
+     * entry points opt in explicitly.
+     */
+    fragmentParagraphs?: boolean;
 }
 /**
  * Pagination engine that converts HTML with pagination metadata
@@ -133,6 +139,7 @@ export declare class PaginationEngine {
     private cssPrefix;
     private showPageNumbers;
     private pageGap;
+    private fragmentParagraphs;
     private hfRegistry;
     private footnoteRegistry;
     private pendingFootnoteContinuation;
@@ -154,6 +161,80 @@ export declare class PaginationEngine {
      * Measures all content blocks in a section.
      */
     private measureBlocks;
+    /**
+     * 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
+     * rows because wrapping and collapsed borders change the height of a fragment.
+     */
+    private measureElement;
+    /**
+     * Returns the contiguous keep-with-next chain beginning at a block.
+     *
+     * A hard page break or a page-break-before directive is stronger than a
+     * keep-with-next directive, so it terminates the chain. The caller only
+     * keeps a chain together when the whole chain can fit on a fresh page.
+     */
+    private getKeepWithNextChain;
+    /**
+     * Measures the visible body height of a keep-with-next chain using the same
+     * collapsed-margin rules as normal block placement. The trailing margin is
+     * intentionally excluded, matching the individual block fit check.
+     */
+    private measureKeepWithNextChainBodyHeight;
+    /**
+     * Finds footnote references introduced by a sequence of blocks, preserving
+     * document order and excluding references already assigned to the page.
+     */
+    private collectNewFootnoteIds;
+    /**
+     * The shortest body available to a section's first, default, or even page.
+     * A row fragment must fit every variant, otherwise a later header/footer could
+     * send it through the oversized-block fallback again.
+     */
+    private smallestEffectiveContentHeight;
+    /**
+     * Builds a clone of a simple table wrapper containing a contiguous run of rows.
+     * Complex table features are deliberately rejected by the caller: a split across
+     * merged cells, nested tables, or footnotes cannot be made correct by cloning rows.
+     */
+    private createSimpleTableFragment;
+    /**
+     * Splits an oversized, ordinary table at row boundaries. This only participates
+     * in the existing oversized-block fallback; unsupported tables keep the previous
+     * overflow behavior rather than risking broken table semantics.
+     */
+    private trySplitSimpleOversizedTable;
+    /**
+     * A DOM endpoint that can finish a paragraph fragment. Endpoints are chosen
+     * after whitespace or at a run boundary so the paginator never deliberately
+     * cuts through an ordinary word merely to fill a little more of a page.
+     */
+    private paragraphFragmentEndpoints;
+    /**
+     * Whether a range contains visible text after ignoring bidi/zero-width marks.
+     * Paragraph fragmentation deliberately excludes non-textual descendants, so
+     * this is enough to reject empty head or tail fragments.
+     */
+    private hasVisibleFragmentText;
+    /**
+     * Phase one only handles text-like paragraph descendants. Objects, explicit
+     * line breaks, list markers, notes, and out-of-flow/inline-block content all
+     * require their own line-layout rules and retain the established whole-block
+     * fallback instead of risking broken content or duplicate anchors.
+     */
+    private canFragmentParagraph;
+    /**
+     * Builds one range-cloned paragraph fragment. Only the leading fragment keeps
+     * the source paragraph's addressability; continuations must not duplicate an
+     * id/data-anchor in the rendered document.
+     */
+    private createParagraphFragment;
+    /**
+     * Splits a simple paragraph at the largest DOM Range endpoint that fits the
+     * currently available body space. The caller then processes the tail normally,
+     * allowing it to fragment again on later pages when necessary.
+     */
+    private tryFragmentParagraph;
     /**
      * Parses the header/footer registry from the staging element.
      * Also measures heights during parsing for lazy-loading compatibility.