docxodus 7.1.0 → 9.0.0

package/dist/pagination.js

@@ -4,6 +4,7 @@
  * This module provides client-side pagination that measures rendered content
  * and flows it across fixed-size page containers based on document dimensions.
  */
+import { formatPageNumber } from "./page-number-format.js";
 // Default letter size in points (612 x 792 = 8.5" x 11")
 const DEFAULT_PAGE_WIDTH = 612;
 const DEFAULT_PAGE_HEIGHT = 792;
@@ -64,6 +65,8 @@ export class PaginationEngine {
      */
     constructor(staging, container, options = {}) {
         this.pendingFootnoteContinuation = null;
+        /** Per-section `w:pgNumType` (start / format), read off the section wrappers. */
+        this.pageNumbering = new Map();
         this.stagingElement =
             typeof staging === "string"
                 ? document.getElementById(staging)
@@ -82,6 +85,7 @@ export class PaginationEngine {
         this.cssPrefix = options.cssPrefix ?? "page-";
         this.showPageNumbers = options.showPageNumbers ?? true;
         this.pageGap = options.pageGap ?? 20;
+        this.fragmentParagraphs = options.fragmentParagraphs ?? false;
         this.hfRegistry = new Map();
         this.footnoteRegistry = new Map();
     }
@@ -99,6 +103,7 @@ export class PaginationEngine {
         this.footnoteRegistry = this.parseFootnoteRegistry();
         // Find all section containers
         const sections = this.stagingElement.querySelectorAll("[data-section-index]");
+        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];
         for (const section of sectionsToProcess) {
@@ -120,8 +125,65 @@ export class PaginationEngine {
         }
         // Hide staging after measurement
         this.stagingElement.style.display = "none";
+        // Every page box exists now, so NUMPAGES has an answer and each PAGE marker knows its page.
+        this.substitutePageNumberFields(pages.length);
         return { totalPages: pages.length, pages };
     }
+    /** Read each section's `w:pgNumType` off its wrapper (see {@link SectionPageNumbering}). */
+    parsePageNumbering(sections) {
+        const map = new Map();
+        for (const section of Array.from(sections)) {
+            const index = parseInt(section.dataset.sectionIndex || "0", 10);
+            const rawStart = section.dataset.pageNumStart;
+            const start = rawStart === undefined ? undefined : parseInt(rawStart, 10);
+            map.set(index, {
+                start: start !== undefined && Number.isFinite(start) ? start : undefined,
+                format: section.dataset.pageNumFmt,
+            });
+        }
+        return map;
+    }
+    /**
+     * Fill in the page-number fields inside every page's cloned header/footer.
+     *
+     * A header/footer is authored once and cloned onto each page, so a PAGE field's single cached
+     * result would otherwise show the same number on every page — the whole reason the converter
+     * marks these. `data-field-format` (the field's own `\*` switch) wins over the section's format
+     * when present, which is exactly how Word resolves the two.
+     *
+     * Runs after layout because NUMPAGES cannot be known before the last page exists. The
+     * substituted text can therefore be marginally wider than the cached result the header was
+     * measured with; the header band clips, so the failure mode is a hair of overflow rather than
+     * a layout that disagrees with itself.
+     *
+     * Scoped to the CLONED header/footer regions on purpose. A page-number field in body text is
+     * ordinary run content that the editor may make editable, and committing an edited block writes
+     * back whatever text the DOM holds — rewriting it here would mean a body field commits a number
+     * the document never contained. Body content is also not cloned, so it does not have the problem
+     * this method exists to solve.
+     */
+    substitutePageNumberFields(totalPages) {
+        const boxes = this.containerElement.querySelectorAll(`.${this.cssPrefix}box`);
+        for (const box of Array.from(boxes)) {
+            const markers = box.querySelectorAll(`.${this.cssPrefix}header [data-field], .${this.cssPrefix}footer [data-field]`);
+            if (markers.length === 0)
+                continue;
+            const sectionIndex = parseInt(box.dataset.sectionIndex || "0", 10);
+            const pageNumber = parseInt(box.dataset.pageNumber || "1", 10);
+            const pageInSection = parseInt(box.dataset.pageInSection || "1", 10);
+            const numbering = this.pageNumbering.get(sectionIndex) ?? {};
+            // A section that restarts numbering counts from its own start; one that does not continues
+            // the document-wide running number.
+            const displayed = numbering.start !== undefined ? numbering.start + pageInSection - 1 : pageNumber;
+            for (const marker of Array.from(markers)) {
+                const kind = marker.dataset.field;
+                if (kind !== "PAGE" && kind !== "NUMPAGES")
+                    continue;
+                const format = marker.dataset.fieldFormat ?? numbering.format;
+                marker.textContent = formatPageNumber(kind === "PAGE" ? displayed : totalPages, format);
+            }
+        }
+    }
     /**
      * Measures all content blocks in a section.
      */
@@ -161,6 +223,443 @@ export class PaginationEngine {
         }
         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);
+        // The eligibility gate permits only colgroups alongside the body. Keep each
+        // colgroup so fixed and proportional column widths remain stable per fragment.
+        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);
+        // Use the source's full vertical margins while forming groups. Continuation
+        // fragments later clear their joining margins, so this conservative bound
+        // cannot create a fragment that overflows a header/footer variant.
+        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++;
+            }
+            // Even a one-row fragment cannot fit. Preserve the established overflow
+            // fallback rather than looping or clipping a partially split row.
+            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);
+            // Keep the source's outer spacing only at the table's real boundaries.
+            // Continuation margins would otherwise add blank space at the top/bottom
+            // of every paginated fragment.
+            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;
+            // A whitespace boundary preserves normal word wrapping. Always retain the
+            // end of a run too: adjacent runs can change formatting without containing
+            // a whitespace character between them.
+            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;
+        }
+        // The outer paragraph may carry its source identity. Descendant identities
+        // are not safe to duplicate in a continuation fragment, so reject them.
+        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;
+        }
+        // A range clone preserves nested inline formatting exactly. Anything that
+        // establishes its own box/layout context is intentionally deferred until a
+        // future fragmenter can model it accurately.
+        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");
+            // A continuation starts with a normal line rather than repeating a first-
+            // line/hanging indent. Keep the side margin so paragraph alignment remains.
+            fragment.style.setProperty("margin-top", "0", "important");
+            fragment.style.setProperty("text-indent", "0", "important");
+        }
+        if (!isFinalFragment) {
+            // The original bottom spacing belongs after the complete paragraph, not
+            // between synthetic page fragments.
+            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);
+        // The final endpoint is the full paragraph and cannot leave a tail. A
+        // single text run with no earlier whitespace remains an overflow fallback.
+        if (endpoints.length < 2) {
+            return null;
+        }
+        let low = 0;
+        let high = endpoints.length - 2;
+        let best = null;
+        // Fragment height is monotonic for the deliberately narrow eligible subset,
+        // so binary search avoids measuring every word in long body paragraphs.
+        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.
@@ -267,12 +766,16 @@ export class PaginationEngine {
         if ((footnoteIds.length === 0 && !hasContinuation) || this.footnoteRegistry.size === 0) {
             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
+        // block against body type and the reserve can never match what is drawn.
         // Create a temporary measurement container
         const measureContainer = document.createElement("div");
         measureContainer.style.position = "absolute";
         measureContainer.style.visibility = "hidden";
         measureContainer.style.width = `${contentWidth}pt`;
         measureContainer.style.left = "-9999px";
+        measureContainer.className = this.cssPrefix + "footnotes";
         // Add separator line (same as will be rendered)
         const hr = document.createElement("hr");
         measureContainer.appendChild(hr);
@@ -313,6 +816,7 @@ export class PaginationEngine {
         measureContainer.style.visibility = "hidden";
         measureContainer.style.width = `${contentWidth}pt`;
         measureContainer.style.left = "-9999px";
+        measureContainer.className = this.cssPrefix + "footnotes";
         // Add separator line
         const hr = document.createElement("hr");
         measureContainer.appendChild(hr);
@@ -331,16 +835,29 @@ export class PaginationEngine {
      * Returns the elements that fit and the elements that need to continue.
      */
     splitFootnoteToFit(footnoteElement, availableHeightPt, contentWidth) {
-        // Get child elements (paragraphs) of the footnote content
+        // Get child elements (paragraphs) of the footnote content.
+        //
+        // `fits` is spliced into a freshly built `.footnote-item` > `.footnote-content` wrapper by
+        // addPageFootnotes, so it must contain the note's CONTENT, never the note element itself.
+        // Returning the whole `.footnote-item` here nested a complete item (number span and all)
+        // inside another item's content span; the inner block-level div then broke the line, so the
+        // note's number rendered alone above its text — the same visible symptom as the escaped-CSS
+        // bug, from an unrelated cause, on the notes that happened to take a can't-split path.
         const footnoteContent = footnoteElement.querySelector(".footnote-content");
         if (!footnoteContent) {
-            // No content structure, can't split - return whole footnote
-            return { fits: [footnoteElement.cloneNode(true)], overflow: [] };
+            // No content structure to split — hand back the element's own children.
+            return {
+                fits: Array.from(footnoteElement.children).map((el) => el.cloneNode(true)),
+                overflow: [],
+            };
         }
         const children = Array.from(footnoteContent.children);
         if (children.length <= 1) {
-            // Single paragraph, can't split at paragraph level
-            return { fits: [footnoteElement.cloneNode(true)], overflow: [] };
+            // Single paragraph: can't split at paragraph level, but the whole content still fits.
+            return {
+                fits: children.map((el) => el.cloneNode(true)),
+                overflow: [],
+            };
         }
         const fits = [];
         const overflow = [];
@@ -351,6 +868,7 @@ export class PaginationEngine {
         hrMeasure.style.visibility = "hidden";
         hrMeasure.style.width = `${contentWidth}pt`;
         hrMeasure.style.left = "-9999px";
+        hrMeasure.className = this.cssPrefix + "footnotes";
         const hr = document.createElement("hr");
         hrMeasure.appendChild(hr);
         this.stagingElement.appendChild(hrMeasure);
@@ -367,6 +885,7 @@ export class PaginationEngine {
             measureContainer.style.visibility = "hidden";
             measureContainer.style.width = `${contentWidth}pt`;
             measureContainer.style.left = "-9999px";
+            measureContainer.className = this.cssPrefix + "footnotes";
             measureContainer.appendChild(child.cloneNode(true));
             this.stagingElement.appendChild(measureContainer);
             const childHeight = pxToPt(measureContainer.getBoundingClientRect().height);
@@ -397,6 +916,7 @@ export class PaginationEngine {
         measureContainer.style.visibility = "hidden";
         measureContainer.style.width = `${contentWidth}pt`;
         measureContainer.style.left = "-9999px";
+        measureContainer.className = this.cssPrefix + "footnotes";
         measureContainer.appendChild(footnote.cloneNode(true));
         this.stagingElement.appendChild(measureContainer);
         const rect = measureContainer.getBoundingClientRect();
@@ -618,6 +1138,18 @@ export class PaginationEngine {
         let currentContinuation = this.pendingFootnoteContinuation;
         // Track any new continuation that will carry to next page
         let nextPageContinuation = null;
+        /**
+         * Whole notes that could not be started on this page and must render on the next one.
+         *
+         * `nextPageContinuation` is a single slot, but the code that fills it runs once per note in a
+         * page's citation list — so when two notes on the same page both failed to fit, the second
+         * overwrote the first and that note was never rendered anywhere. On a 94-footnote document
+         * four notes disappeared from the output entirely. A deferral queue keeps the single-slot
+         * continuation for its real meaning (the tail of a note that was SPLIT) and carries
+         * never-started notes forward as ordinary footnote ids, which the next page already knows how
+         * to lay out.
+         */
+        let deferredFootnoteIds = [];
         // Track partial footnotes for current page (footnotes that were split)
         let currentPartialFootnotes = [];
         // Account for any continuation from previous section/page
@@ -625,7 +1157,8 @@ export class PaginationEngine {
             currentFootnoteHeight = this.measureContinuationHeight(currentContinuation, dims.contentWidth);
         }
         const finishPage = () => {
-            if (currentContent.length === 0 && !currentContinuation)
+            const hasCurrentContinuation = (currentContinuation?.remainingElements.length ?? 0) > 0;
+            if (currentContent.length === 0 && !hasCurrentContinuation)
                 return;
             const page = this.createPage(dims, pageNumber, sectionIndex, currentContent, pageInSection, currentFootnoteIds, currentFootnoteHeight, currentContinuation, currentPartialFootnotes.length > 0 ? currentPartialFootnotes : undefined);
             pages.push(page);
@@ -642,6 +1175,13 @@ export class PaginationEngine {
             // Carry over continuation to next page
             currentContinuation = nextPageContinuation;
             nextPageContinuation = null;
+            // Notes that never got started land at the top of the new page's note area. They are
+            // ordinary footnotes from here on, so the normal fitting path handles them — and because
+            // this page is fresh, the space they were denied now exists.
+            if (deferredFootnoteIds.length > 0) {
+                currentFootnoteIds = [...deferredFootnoteIds];
+                deferredFootnoteIds = [];
+            }
             // Account for continuation height on new page
             if (currentContinuation && currentContinuation.remainingElements.length > 0) {
                 currentFootnoteHeight = this.measureContinuationHeight(currentContinuation, dims.contentWidth);
@@ -649,10 +1189,12 @@ export class PaginationEngine {
             else {
                 currentFootnoteHeight = 0;
             }
+            if (currentFootnoteIds.length > 0) {
+                currentFootnoteHeight += this.measureFootnotesHeight(currentFootnoteIds, dims.contentWidth, null);
+            }
         };
         for (let i = 0; i < blocks.length; i++) {
             const block = blocks[i];
-            const nextBlock = blocks[i + 1];
             // Handle explicit page breaks
             if (block.isPageBreak) {
                 finishPage();
@@ -662,10 +1204,50 @@ export class PaginationEngine {
             if (block.pageBreakBefore && currentContent.length > 0) {
                 finishPage();
             }
+            // A series of keep-with-next blocks is one indivisible placement unit
+            // when it can fit a new page. The former one-block lookahead was never
+            // applied to the placement decision, and it could not preserve a chain of
+            // headings/paragraphs. Do not force an oversized chain to a fresh page:
+            // its members retain the established greedy/overflow behavior instead.
+            const previousBlock = blocks[i - 1];
+            const startsKeepChain = !previousBlock ||
+                !previousBlock.keepWithNext ||
+                previousBlock.isPageBreak ||
+                block.pageBreakBefore;
+            // A footnote continuation also occupies this page even when its body has
+            // no blocks yet. In that case a feasible chain may need to move past the
+            // continuation as a unit.
+            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);
+                        // 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) {
+                            finishPage();
+                        }
+                    }
+                }
+            }
             // Extract footnote references from this block
-            const blockFootnoteIds = this.extractFootnoteRefs(block.element);
+            const allBlockFootnoteIds = this.extractFootnoteRefs(block.element);
             // Only count new footnotes (not already on this page)
-            const newFootnoteIds = blockFootnoteIds.filter(id => !currentFootnoteIds.includes(id));
+            const newFootnoteIds = this.collectNewFootnoteIds([block], currentFootnoteIds);
             // Calculate additional footnote height if this block is added
             let additionalFootnoteHeight = 0;
             if (newFootnoteIds.length > 0 && this.footnoteRegistry.size > 0) {
@@ -688,20 +1270,24 @@ export class PaginationEngine {
             // bottom margin extends beyond the content area and is clipped by overflow:hidden.
             // It is still tracked in remainingHeight for correct margin collapsing with the next block.
             const blockSpace = effectiveMarginTop + block.heightPt + additionalFootnoteHeight;
-            // Calculate needed height (including keepWithNext)
-            let neededHeight = blockSpace;
-            if (block.keepWithNext && nextBlock && !nextBlock.isPageBreak) {
-                // For keepWithNext, include the next block with collapsed margins
-                const collapsedMargin = Math.max(block.marginBottomPt, nextBlock.marginTopPt);
-                neededHeight = effectiveMarginTop + block.heightPt + collapsedMargin +
-                    nextBlock.heightPt + additionalFootnoteHeight;
-            }
             // Effective remaining height (content area minus footnotes already on page)
             const effectiveRemainingHeight = remainingHeight - currentFootnoteHeight;
             // Calculate maximum footnote area for this page (can expand into body content space)
             const bodyContentUsed = effectiveContentHeight - remainingHeight;
             const maxFootnoteArea = effectiveContentHeight * MAX_FOOTNOTE_AREA_RATIO;
             const maxFootnoteExpansion = Math.max(0, maxFootnoteArea - currentFootnoteHeight);
+            // A paragraph that cannot fit as a whole may still have a simple text-only
+            // prefix that fits this page. Fragment before the ordinary next-page or
+            // oversized fallback so the cloned head participates in the same margin
+            // and footnote accounting as every other block.
+            if (blockSpace > effectiveRemainingHeight) {
+                const paragraphFragments = this.tryFragmentParagraph(block, dims, effectiveRemainingHeight, effectiveMarginTop);
+                if (paragraphFragments) {
+                    blocks.splice(i, 1, ...paragraphFragments);
+                    i--;
+                    continue;
+                }
+            }
             // Check if block fits on current page (including its footnotes)
             if (blockSpace <= effectiveRemainingHeight) {
                 // Block fits with current footnote allocation
@@ -752,34 +1338,23 @@ export class PaginationEngine {
                                         footnoteId,
                                         fittingElements: fits
                                     });
-                                    nextPageContinuation = {
-                                        footnoteId,
-                                        remainingElements: overflow
-                                    };
+                                    if (overflow.length > 0) {
+                                        nextPageContinuation = {
+                                            footnoteId,
+                                            remainingElements: overflow
+                                        };
+                                    }
                                     currentFootnoteHeight = availableForFootnotes;
                                 }
                                 else {
-                                    // Nothing fits, entire footnote continues to next page
-                                    nextPageContinuation = {
-                                        footnoteId,
-                                        remainingElements: Array.from(footnote.querySelectorAll(".footnote-content > *"))
-                                            .map(el => el.cloneNode(true))
-                                    };
-                                    if (nextPageContinuation.remainingElements.length === 0) {
-                                        nextPageContinuation.remainingElements = [footnote.cloneNode(true)];
-                                    }
+                                    // Nothing of this note fits: defer the WHOLE note rather than assigning the
+                                    // single continuation slot, which a later note on this page would overwrite.
+                                    deferredFootnoteIds.push(footnoteId);
                                 }
                             }
                             else {
-                                // Not enough space to start footnote - continue whole thing
-                                nextPageContinuation = {
-                                    footnoteId,
-                                    remainingElements: Array.from(footnote.querySelectorAll(".footnote-content > *"))
-                                        .map(el => el.cloneNode(true))
-                                };
-                                if (nextPageContinuation.remainingElements.length === 0) {
-                                    nextPageContinuation.remainingElements = [footnote.cloneNode(true)];
-                                }
+                                // Not enough space to even start the note — same deferral.
+                                deferredFootnoteIds.push(footnoteId);
                             }
                         }
                     }
@@ -792,8 +1367,14 @@ export class PaginationEngine {
                     const expandedFootnoteSpace = Math.min(maxFootnoteArea, additionalFootnoteHeight + currentFootnoteHeight);
                     const bodySpaceAfterExpansion = effectiveContentHeight - expandedFootnoteSpace;
                     if (blockSpaceWithoutFootnotes <= bodySpaceAfterExpansion - bodyContentUsed) {
-                        // Block fits after expanding footnote area
+                        // Block fits after expanding footnote area.
                         currentContent.push(block.element.cloneNode(true));
+                        // `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
+                        // reserve in a second time, so a later block would see a body budget short by the whole
+                        // footnote area. Consistency fix: no measurable difference on the documents tested, but
+                        // the two meanings must not coexist or the next change here inherits a latent bug.
                         remainingHeight = bodySpaceAfterExpansion - bodyContentUsed - blockSpaceWithoutFootnotes;
                         prevMarginBottomPt = block.marginBottomPt;
                         currentFootnoteIds.push(...newFootnoteIds);
@@ -802,14 +1383,16 @@ export class PaginationEngine {
                     else {
                         // Still doesn't fit - start new page
                         finishPage();
-                        const newPageFootnoteHeight = blockFootnoteIds.length > 0
-                            ? this.measureFootnotesHeight(blockFootnoteIds, dims.contentWidth, currentContinuation)
+                        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];
+                        // 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];
                         currentFootnoteHeight = newPageFootnoteHeight;
                     }
                 }
@@ -818,26 +1401,42 @@ export class PaginationEngine {
                     finishPage();
                     // On new page, recalculate footnote height for just this block's footnotes
                     // (plus any continuation from previous page)
-                    const newPageFootnoteHeight = blockFootnoteIds.length > 0
-                        ? this.measureFootnotesHeight(blockFootnoteIds, dims.contentWidth, currentContinuation)
+                    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));
                     remainingHeight = effectiveContentHeight - newPageSpace;
                     prevMarginBottomPt = block.marginBottomPt;
-                    currentFootnoteIds = [...blockFootnoteIds];
+                    // 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];
                     currentFootnoteHeight = newPageFootnoteHeight;
                 }
             }
             else {
-                // Block is taller than a page - add it and let it overflow
-                // (In a more sophisticated implementation, we would split the block)
+                // Block is taller than a page. Ordinary tables can be split at complete
+                // row boundaries; every other block retains the established overflow path.
+                const tableFragments = this.trySplitSimpleOversizedTable(block, dims, sectionIndex);
+                if (tableFragments) {
+                    if (currentContent.length > 0 || currentContinuation) {
+                        finishPage();
+                    }
+                    blocks.splice(i, 1, ...tableFragments);
+                    i--;
+                    continue;
+                }
+                // Unsupported oversized blocks are intentionally left intact. Splitting
+                // arbitrary HTML, merged tables, or footnote-bearing tables would be less
+                // correct than the prior clipped fallback.
                 if (currentContent.length > 0) {
                     finishPage();
                 }
                 currentContent.push(block.element.cloneNode(true));
-                currentFootnoteIds = [...blockFootnoteIds];
+                // 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];
                 finishPage();
             }
         }
@@ -847,6 +1446,28 @@ export class PaginationEngine {
         this.pendingFootnoteContinuation = nextPageContinuation;
         return pages;
     }
+    /**
+     * Strip block addressing from a header/footer node cloned into a page box.
+     *
+     * A running story is authored ONCE and cloned onto every page, so the clones all carry the same
+     * `data-anchor` — on this document, 42 page boxes claiming one footer paragraph. Left editable,
+     * committing any one of them writes back through that single shared anchor, and the per-page
+     * page-number substitution makes it worse: each clone shows a DIFFERENT number, so a commit
+     * writes that page's number into the story as literal text and destroys the PAGE field.
+     *
+     * Page-box header/footer content is presentation. The docked editing bands
+     * (`editor-headerfooter.ts`) are the addressable affordance, and they exist precisely because a
+     * cloned node cannot be uniquely addressed.
+     */
+    makeClonedStoryInert(root) {
+        const nodes = [root, ...Array.from(root.querySelectorAll("*"))];
+        for (const el of nodes) {
+            el.removeAttribute("data-anchor");
+            el.removeAttribute("data-committed-text");
+            if (el.getAttribute("contenteditable") !== null)
+                el.setAttribute("contenteditable", "false");
+        }
+    }
     /**
      * Creates a page container element.
      */
@@ -883,6 +1504,9 @@ export class PaginationEngine {
         pageBox.style.contain = "layout paint";
         pageBox.dataset.pageNumber = String(pageNumber);
         pageBox.dataset.sectionIndex = String(sectionIndex);
+        // 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);
         // Add header if available for this section/page
@@ -903,7 +1527,10 @@ export class PaginationEngine {
             headerDiv.style.paddingBottom = "4pt"; // Small gap before content area
             // Clone the header content (skip the wrapper div's data attributes)
             for (const child of Array.from(headerSource.childNodes)) {
-                headerDiv.appendChild(child.cloneNode(true));
+                const clonedheaderDiv = child.cloneNode(true);
+                if (clonedheaderDiv.nodeType === 1)
+                    this.makeClonedStoryInert(clonedheaderDiv);
+                headerDiv.appendChild(clonedheaderDiv);
             }
             pageBox.appendChild(headerDiv);
         }
@@ -946,7 +1573,10 @@ export class PaginationEngine {
             footerDiv.style.paddingTop = "4pt"; // Small gap after content area
             // Clone the footer content (skip the wrapper div's data attributes)
             for (const child of Array.from(footerSource.childNodes)) {
-                footerDiv.appendChild(child.cloneNode(true));
+                const clonedfooterDiv = child.cloneNode(true);
+                if (clonedfooterDiv.nodeType === 1)
+                    this.makeClonedStoryInert(clonedfooterDiv);
+                footerDiv.appendChild(clonedfooterDiv);
             }
             pageBox.appendChild(footerDiv);
         }
@@ -959,6 +1589,24 @@ export class PaginationEngine {
         }
         // Add to container
         this.containerElement.appendChild(pageBox);
+        // 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
+        // height the loop reserved and the height the notes actually render at draws body text and note
+        // text on top of each other (observed on a 94-footnote document: ~134pt of superimposed,
+        // illegible glyphs). Shrinking the content area to the space the notes actually left removes
+        // the failure mode by construction — the worst case becomes a clean clip by the content area's
+        // existing `overflow: hidden`, which is obvious and recoverable rather than silent corruption.
+        //
+        // This runs AFTER the append on purpose: `getBoundingClientRect()` on a detached node is all
+        // zeroes, so measuring while building the page silently did nothing.
+        const notesEl = pageBox.querySelector(`.${this.cssPrefix}footnotes`);
+        if (notesEl) {
+            const notesHeightPt = pxToPt(notesEl.getBoundingClientRect().height);
+            if (notesHeightPt > 0) {
+                contentArea.style.height = `${Math.max(0, contentAreaHeight - notesHeightPt)}pt`;
+            }
+        }
         return {
             pageNumber,
             sectionIndex,
@@ -1014,7 +1662,13 @@ export function paginateHtml(html, container, options = {}) {
     if (!pageContainer) {
         throw new Error("Pagination container element not found");
     }
-    const engine = new PaginationEngine(staging, pageContainer, options);
+    // This convenience function is the read-only HTML viewer path. Keep the
+    // lower-level engine conservative by default, while enabling paragraph
+    // fragmentation here unless a caller deliberately opts out.
+    const engine = new PaginationEngine(staging, pageContainer, {
+        ...options,
+        fragmentParagraphs: options.fragmentParagraphs ?? true,
+    });
     return engine.paginate();
 }
 //# sourceMappingURL=pagination.js.map