docxodus 7.1.0 → 8.0.0

package/dist/editor.bundle.js

@@ -84,6 +84,7 @@ var DocxodusEditor = (() => {
       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();
     }
@@ -150,6 +151,393 @@ var DocxodusEditor = (() => {
       }
       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.
@@ -548,7 +936,8 @@ var DocxodusEditor = (() => {
         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,
@@ -580,7 +969,6 @@ var DocxodusEditor = (() => {
       };
       for (let i = 0; i < blocks.length; i++) {
         const block = blocks[i];
-        const nextBlock = blocks[i + 1];
         if (block.isPageBreak) {
           finishPage();
           continue;
@@ -588,8 +976,59 @@ var DocxodusEditor = (() => {
         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];
@@ -606,15 +1045,23 @@ var DocxodusEditor = (() => {
           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;
@@ -656,10 +1103,12 @@ var DocxodusEditor = (() => {
                       footnoteId,
                       fittingElements: fits
                     });
-                    nextPageContinuation = {
-                      footnoteId,
-                      remainingElements: overflow
-                    };
+                    if (overflow.length > 0) {
+                      nextPageContinuation = {
+                        footnoteId,
+                        remainingElements: overflow
+                      };
+                    }
                     currentFootnoteHeight = availableForFootnotes;
                   } else {
                     nextPageContinuation = {
@@ -692,30 +1141,39 @@ var DocxodusEditor = (() => {
               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();
         }
       }
@@ -839,10 +1297,360 @@ var DocxodusEditor = (() => {
     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();
   }
 
+  // src/editor-headerfooter.ts
+  var KIND_LABELS = [
+    { value: "default", label: "Default" },
+    { value: "first", label: "First page" },
+    { value: "even", label: "Even pages" }
+  ];
+  var EVEN_WARNING = "w:evenAndOddHeaders is document-global and governs footers too \u2014 even pages stop inheriting the Default stories, so a section with only a Default footer shows no footer at all on even pages.";
+  var FIRST_WARNING = "w:titlePg makes page 1 use its own first-page header AND footer instead of the Default ones, so an empty first-page footer leaves page 1 with no footer.";
+  var STORY_BLOCK_KINDS = /* @__PURE__ */ new Set(["p", "h", "li"]);
+  var HeaderFooterRegion = class {
+    constructor(bridge, handle, options, callbacks) {
+      /** The body anchor whose section the bands currently describe (needed to seed a story). */
+      this.bodyAnchorId = null;
+      this.sectionInfo = null;
+      /** Memoized body anchor → governing sectionUnid, so repeat focus costs no bridge call. */
+      this.sectionOfAnchor = /* @__PURE__ */ new Map();
+      this.kinds = {
+        header: "default",
+        footer: "default"
+      };
+      this.bridge = bridge;
+      this.handle = handle;
+      this.options = options;
+      this.callbacks = callbacks;
+      this.headerBand = this.buildBand("header");
+      this.footerBand = this.buildBand("footer");
+    }
+    // ─── public surface ──────────────────────────────────────────────────
+    /**
+     * Point the bands at the section governing `bodyAnchorId` and repaint if it changed.
+     * Cheap to call on every focus change: the anchor → section lookup is memoized, and an
+     * unchanged `sectionUnid` returns without touching the DOM (so it never clobbers the
+     * user's kind selection).
+     */
+    syncToBody(bodyAnchorId) {
+      if (!bodyAnchorId) return;
+      const cached = this.sectionOfAnchor.get(bodyAnchorId);
+      if (cached !== void 0 && cached === this.sectionInfo?.sectionUnid) {
+        this.bodyAnchorId = bodyAnchorId;
+        return;
+      }
+      const info = this.readSectionInfo(bodyAnchorId);
+      if (!info) return;
+      this.sectionOfAnchor.set(bodyAnchorId, info.sectionUnid);
+      const changed = info.sectionUnid !== this.sectionInfo?.sectionUnid;
+      this.bodyAnchorId = bodyAnchorId;
+      this.sectionInfo = info;
+      if (changed) this.refreshAll();
+    }
+    /** Repaint one band from the live session. */
+    refresh(which) {
+      this.sectionInfo = this.bodyAnchorId ? this.readSectionInfo(this.bodyAnchorId) : null;
+      this.renderBand(which);
+    }
+    /** Repaint both bands from the live session (after a remount, undo/redo, or section change). */
+    refreshAll() {
+      this.renderBand("header");
+      this.renderBand("footer");
+    }
+    /** Select (and, if absent, create) the story kind a band edits, and make it render. */
+    setKind(which, kind) {
+      this.kinds[which] = kind;
+      const select = this.bandFor(which).querySelector("[data-hf-kind]");
+      if (select && select.value !== kind) select.value = kind;
+      if (!this.partUriFor(which, kind)) this.seedStory(which, kind);
+      if (this.bodyAnchorId && kind !== "default") {
+        this.bridge.EnsureHeaderFooterVisible(this.handle, this.bodyAnchorId, kind);
+      }
+      this.refresh(which);
+    }
+    /** The kind a band is currently editing. */
+    kindOf(which) {
+      return this.kinds[which];
+    }
+    /** Append a PAGE / NUMPAGES field to the story paragraph addressed by `anchorId`. */
+    insertPageNumber(which, anchorId, field) {
+      const res = parseResult(this.bridge.InsertPageNumberField(this.handle, anchorId, field));
+      if (!res.success) return false;
+      this.refresh(which);
+      return true;
+    }
+    /** Insert a page number into a band's own target paragraph (focused, else last). Seeds the
+     *  story first if the band's selected kind has none, so the command is never a silent no-op. */
+    insertPageNumberInBand(which, field) {
+      if (!this.partUriFor(which, this.kinds[which])) {
+        this.seedStory(which, this.kinds[which]);
+        this.renderBand(which);
+      }
+      const target = this.pageNumberTarget(which);
+      return target ? this.insertPageNumber(which, target, field) : false;
+    }
+    /** The band element containing `node`, or null. */
+    bandOf(node) {
+      const el = node && node.nodeType === 1 ? node : node?.parentElement ?? null;
+      const band = el?.closest("[data-hf-band]") ?? null;
+      return band === this.headerBand || band === this.footerBand ? band : null;
+    }
+    /** The block-list root (a band's story container) owning `node`, or null. */
+    blockRootOf(node) {
+      const band = this.bandOf(node);
+      return band ? band.querySelector("[data-hf-body]") : null;
+    }
+    /** True when `node` is inside either band (including its chrome). */
+    contains(node) {
+      return this.bandOf(node) !== null;
+    }
+    /** `"header"` / `"footer"` for a band element produced by this region. */
+    whichOf(band) {
+      return band === this.footerBand ? "footer" : "header";
+    }
+    // ─── section + anchor resolution ─────────────────────────────────────
+    readSectionInfo(bodyAnchorId) {
+      try {
+        const raw = this.bridge.GetSectionInfo(this.handle, bodyAnchorId);
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed.sectionUnid === "string" ? parsed : null;
+      } catch {
+        return null;
+      }
+    }
+    refsFor(which) {
+      const info = this.sectionInfo;
+      if (!info) return [];
+      return (which === "header" ? info.headerRefs : info.footerRefs) ?? [];
+    }
+    /** The reference supplying `kind` for this band — possibly inherited from an earlier section. */
+    refFor(which, kind) {
+      return this.refsFor(which).find((r) => r.kind === kind) ?? null;
+    }
+    /** URI of the part supplying `kind` for this band, or null when the story doesn't exist. */
+    partUriFor(which, kind) {
+      return this.refFor(which, kind)?.partUri ?? null;
+    }
+    /** Full anchor ids of the story paragraphs held in `partUri`, in document order. */
+    storyAnchors(partUri) {
+      let index;
+      try {
+        index = JSON.parse(this.bridge.Project(this.handle)).anchorIndex;
+      } catch {
+        return [];
+      }
+      return Object.entries(index).filter(([, t]) => t.partUri === partUri && STORY_BLOCK_KINDS.has(t.kind)).map(([id]) => id);
+    }
+    /**
+     * Create an empty story for `kind`. Seeding happens the moment a kind is selected rather than
+     * lazily on first keystroke: an absent story renders no contenteditable element, so there
+     * would be nothing to click into.
+     */
+    seedStory(which, kind) {
+      if (!this.bodyAnchorId) return;
+      const set = which === "header" ? this.bridge.SetHeaderText : this.bridge.SetFooterText;
+      const res = parseResult(set(this.handle, this.bodyAnchorId, kind, ""));
+      if (!res.success) return;
+      this.callbacks.refreshAnchorMap();
+      this.sectionInfo = this.readSectionInfo(this.bodyAnchorId);
+    }
+    // ─── rendering ───────────────────────────────────────────────────────
+    bandFor(which) {
+      return which === "header" ? this.headerBand : this.footerBand;
+    }
+    buildBand(which) {
+      const band = document.createElement("div");
+      band.className = "docx-hf-band";
+      band.setAttribute("data-hf-band", which);
+      const chrome = document.createElement("div");
+      chrome.className = "docx-hf-chrome";
+      const label = document.createElement("span");
+      label.className = "docx-hf-label";
+      label.textContent = which === "header" ? "Header" : "Footer";
+      chrome.appendChild(label);
+      const kindSelect = document.createElement("select");
+      kindSelect.setAttribute("data-hf-kind", "");
+      kindSelect.title = "Which header/footer story to edit";
+      for (const k of KIND_LABELS) {
+        const opt = document.createElement("option");
+        opt.value = k.value;
+        opt.textContent = k.label;
+        kindSelect.appendChild(opt);
+      }
+      kindSelect.addEventListener(
+        "change",
+        () => this.setKind(which, kindSelect.value)
+      );
+      chrome.appendChild(kindSelect);
+      const pageNum = document.createElement("select");
+      pageNum.setAttribute("data-hf-pagenum", "");
+      pageNum.title = "Insert a page-number field into the focused story paragraph";
+      for (const o of [
+        { value: "", label: "Page \u2116\u2026" },
+        { value: "currentPage", label: "Page number" },
+        { value: "totalPages", label: "Total pages" }
+      ]) {
+        const opt = document.createElement("option");
+        opt.value = o.value;
+        opt.textContent = o.label;
+        pageNum.appendChild(opt);
+      }
+      pageNum.addEventListener("change", () => {
+        const field = pageNum.value;
+        pageNum.value = "";
+        if (field !== "currentPage" && field !== "totalPages") return;
+        const target = this.pageNumberTarget(which);
+        if (target) this.insertPageNumber(which, target, field);
+      });
+      chrome.appendChild(pageNum);
+      const inheritedNote = document.createElement("span");
+      inheritedNote.className = "docx-hf-inherited";
+      inheritedNote.setAttribute("data-hf-inherited-note", "");
+      inheritedNote.hidden = true;
+      chrome.appendChild(inheritedNote);
+      band.appendChild(chrome);
+      const warning = document.createElement("div");
+      warning.className = "docx-hf-warning";
+      warning.setAttribute("data-hf-warning", "");
+      warning.hidden = true;
+      band.appendChild(warning);
+      const body = document.createElement("div");
+      body.className = "docx-hf-body";
+      body.setAttribute("data-hf-body", "");
+      band.appendChild(body);
+      return band;
+    }
+    /**
+     * Which story paragraph a page-number insert targets: the last one the user focused in this
+     * band if it is still attached, else the band's last paragraph (Word's convention — the page
+     * number goes at the end of the footer line).
+     */
+    pageNumberTarget(which) {
+      const body = this.bandFor(which).querySelector("[data-hf-body]");
+      if (!body) return null;
+      const focused = body.querySelector('[data-hf-focused="true"][data-hf-anchor]');
+      const blocks = Array.from(body.querySelectorAll("[data-hf-anchor]"));
+      const target = focused ?? blocks[blocks.length - 1];
+      return target?.getAttribute("data-hf-anchor") ?? null;
+    }
+    renderBand(which) {
+      const band = this.bandFor(which);
+      const body = band.querySelector("[data-hf-body]");
+      if (!body) return;
+      const kind = this.kinds[which];
+      const select = band.querySelector("[data-hf-kind]");
+      if (select && select.value !== kind) select.value = kind;
+      const inherited = this.refFor(which, kind)?.inherited === true;
+      band.toggleAttribute("data-hf-inherited", inherited);
+      const note = band.querySelector("[data-hf-inherited-note]");
+      if (note) {
+        note.hidden = !inherited;
+        note.textContent = inherited ? "inherited from an earlier section" : "";
+      }
+      this.renderKindWarning(which);
+      body.innerHTML = "";
+      const partUri = this.partUriFor(which, kind);
+      if (!partUri) {
+        body.appendChild(this.placeholder(which, kind));
+        band.setAttribute("data-hf-empty", "true");
+        return;
+      }
+      band.removeAttribute("data-hf-empty");
+      const anchors = this.storyAnchors(partUri);
+      if (anchors.length === 0) {
+        body.appendChild(this.placeholder(which, kind));
+        return;
+      }
+      for (const anchorId of anchors) {
+        const el = this.renderStoryBlock(anchorId);
+        if (!el) continue;
+        body.appendChild(el);
+        this.adoptBlock(el, anchorId);
+        this.callbacks.wireBlock(el);
+      }
+    }
+    /**
+     * Mark a story paragraph as belonging to this region. The full anchor id is stamped alongside
+     * `data-anchor` (which carries only the bare unid, matching the body's convention) so band
+     * chrome can address the block without going through the editor's unid map. Called on first
+     * render AND after an incremental swap, which replaces the DOM node.
+     */
+    adoptBlock(el, anchorId) {
+      const body = this.blockRootOf(el);
+      if (!body) return;
+      el.setAttribute("data-hf-anchor", anchorId);
+      if (el.dataset.hfAdopted === "true") return;
+      el.dataset.hfAdopted = "true";
+      el.addEventListener("focus", () => {
+        body.querySelectorAll("[data-hf-focused]").forEach((sib) => sib.removeAttribute("data-hf-focused"));
+        el.setAttribute("data-hf-focused", "true");
+      });
+    }
+    renderStoryBlock(anchorId) {
+      const html = this.bridge.RenderBlockHtml(
+        this.handle,
+        anchorId,
+        this.options.cssPrefix,
+        this.options.fabricateClasses
+      );
+      if (html.charCodeAt(0) === 123) return null;
+      return new DOMParser().parseFromString(html, "text/html").body.firstElementChild;
+    }
+    placeholder(which, kind) {
+      const el = document.createElement("div");
+      el.className = "docx-hf-placeholder";
+      el.setAttribute("data-hf-placeholder", "");
+      const label = KIND_LABELS.find((k) => k.value === kind)?.label ?? kind;
+      el.textContent = `No ${label.toLowerCase()} ${which} \u2014 pick a kind to create one.`;
+      return el;
+    }
+    /**
+     * Surface the caveat that comes with the selected kind. Turning on first/even means those pages
+     * stop using the Default stories entirely, which bites hardest on the OTHER band: enabling an
+     * even header with no even footer leaves even pages footer-less, and enabling a first-page
+     * header with an empty first-page footer leaves page 1 footer-less. The note is shown whenever
+     * first/even is selected (the behavior change is real either way); the fix button appears only
+     * when the counterpart story is missing entirely, which is what a user almost always wants next.
+     */
+    renderKindWarning(which) {
+      const band = this.bandFor(which);
+      const warning = band.querySelector("[data-hf-warning]");
+      if (!warning) return;
+      const kind = this.kinds[which];
+      if (kind === "default") {
+        warning.hidden = true;
+        warning.textContent = "";
+        return;
+      }
+      const other = which === "header" ? "footer" : "header";
+      warning.hidden = false;
+      warning.textContent = `${kind === "even" ? EVEN_WARNING : FIRST_WARNING} `;
+      if (this.partUriFor(other, kind)) return;
+      const fix = document.createElement("button");
+      fix.type = "button";
+      fix.setAttribute("data-hf-fix-counterpart", "");
+      fix.textContent = `Also create a ${kind === "even" ? "matching even" : "first-page"} ${other}`;
+      fix.addEventListener("click", () => {
+        this.setKind(other, kind);
+        this.renderKindWarning(which);
+      });
+      warning.appendChild(fix);
+    }
+  };
+  function parseResult(json) {
+    try {
+      return JSON.parse(json);
+    } catch {
+      return { success: false };
+    }
+  }
+
   // src/editor.ts
   var EDITABLE_TAGS = /* @__PURE__ */ new Set(["P", "H1", "H2", "H3", "H4", "H5", "H6"]);
   function fontWeightIsBold(w) {
@@ -976,11 +1784,22 @@ var DocxodusEditor = (() => {
     return out;
   }
   function trimmedSplitOffset(block, domOffset) {
-    const content = blockContentText(block);
-    const leading = content.length - content.replace(/^\s+/, "").length;
-    const trimmedLen = content.trim().length;
+    const { leading, trimmedLen } = trimBounds(block);
     return Math.max(0, Math.min(domOffset - Math.min(domOffset, leading), trimmedLen));
   }
+  function trimBounds(block) {
+    const content = blockContentText(block);
+    return {
+      leading: content.length - content.replace(/^\s+/, "").length,
+      trimmedLen: content.trim().length
+    };
+  }
+  function trimmedSpan(block, span) {
+    const { leading, trimmedLen } = trimBounds(block);
+    const start = Math.max(0, Math.min(span.start - Math.min(span.start, leading), trimmedLen));
+    const end = Math.max(start, Math.min(span.start + span.length - leading, trimmedLen));
+    return { start, length: end - start };
+  }
   function contentPositionIn(el, offset) {
     let remaining = offset;
     let result = null;
@@ -1047,7 +1866,8 @@ var DocxodusEditor = (() => {
     if (!block.contains(range.startContainer) || !block.contains(range.endContainer)) return null;
     const start = contentOffsetOf(block, range.startContainer, range.startOffset);
     const end = contentOffsetOf(block, range.endContainer, range.endOffset);
-    return { start: Math.min(start, end), length: Math.abs(end - start) };
+    const span = trimmedSpan(block, { start: Math.min(start, end), length: Math.abs(end - start) });
+    return span.length > 0 ? span : null;
   }
   function selectRange(el, start, length) {
     const sel = typeof window !== "undefined" ? window.getSelection() : null;
@@ -1167,6 +1987,8 @@ var DocxodusEditor = (() => {
        * block, and cleared when a caret is collapsed inside a block (so it never goes stale).
        */
       this.lastSelection = null;
+      /** The docked header/footer bands, when `options.headerFooter` is on. */
+      this.region = null;
       /** Track the last meaningful selection so focus-stealing toolbar controls can still target it. */
       this.onSelectionChange = () => {
         if (this.closed) return;
@@ -1192,12 +2014,39 @@ var DocxodusEditor = (() => {
       if (typeof document !== "undefined")
         document.addEventListener("selectionchange", this.onSelectionChange);
     }
-    /** The editable block (contenteditable [data-anchor]) containing `node`, if any, within this editor. */
+    /** The editable block (contenteditable [data-anchor]) containing `node`, if any, within this editor.
+     *  Fenced by `container`, not `editRoot`, so header/footer band blocks — which live outside the
+     *  body edit root by design — also register. The fence still rejects other editors on the page. */
     editableBlockOf(node) {
       if (!node) return null;
       const start = node.nodeType === 1 ? node : node.parentElement;
       const block = start?.closest('[data-anchor][contenteditable="true"]') ?? null;
-      return block && this.editRoot.contains(block) ? block : null;
+      return block && this.container.contains(block) ? block : null;
+    }
+    /**
+     * The root owning `el`'s sibling block list: its header/footer band's story container, else the
+     * body edit root. Keeps a multi-block selection from spanning a band and the body, whose block
+     * lists belong to different OOXML parts.
+     */
+    ownerRoot(el) {
+      return this.region?.blockRootOf(el) ?? this.editRoot;
+    }
+    /** True when `el` is a header/footer band block rather than a body block. */
+    isBandBlock(el) {
+      return !!this.region?.contains(el);
+    }
+    /**
+     * Repaint after an edit to `block` that would otherwise remount the whole document: a band
+     * repaints only itself (a story is one to three paragraphs), leaving the body DOM — and the
+     * user's place in it — untouched.
+     */
+    refreshAfter(block, focusIndex, caretAtEnd = false) {
+      const band = this.region?.bandOf(block);
+      if (band) {
+        this.region.refresh(this.region.whichOf(band));
+        return;
+      }
+      this.remount(focusIndex, caretAtEnd);
     }
     /** Open a document, render it into `container`, and wire up editing. */
     static open(container, bytes, exports, options = {}) {
@@ -1207,16 +2056,19 @@ var DocxodusEditor = (() => {
         editable: options.editable ?? true,
         paginated: options.paginated ?? false,
         scale: options.scale ?? 1,
+        headerFooter: options.headerFooter ?? false,
         onEdit: options.onEdit
       };
       const handle = exports.DocxSessionBridge.OpenSession(bytes, '{"persistAnchorIds":true}');
       const editor = new _DocxEditor(container, exports, handle, opts);
       editor.refreshAnchorMap();
+      if (opts.headerFooter) editor.createRegion();
       const fullHtml = exports.DocumentConverter.ConvertDocxToHtmlComplete(
         ...completeArgs(bytes, opts.cssPrefix, opts.fabricateClasses, opts.paginated, opts.scale)
       );
       if (opts.paginated) editor.mountPaginated(fullHtml);
       else editor.mountHtml(fullHtml);
+      editor.syncRegionToBody();
       return editor;
     }
     /**
@@ -1259,29 +2111,113 @@ var DocxodusEditor = (() => {
     assertOpen() {
       if (this.closed) throw new Error("DocxEditor is closed");
     }
-    /** Rebuild unid → full-anchor-id from the live session projection. */
+    /**
+     * Rebuild unid → full-anchor-id from the live session projection.
+     *
+     * Unids are CONTENT-ADDRESSED, so blocks with identical content in DIFFERENT parts collide —
+     * e.g. a document with empty default/first/even header stories has one unid for several
+     * header parts. A collision must resolve to the BODY entry: body blocks carry only
+     * `data-anchor` (the bare unid) and have nothing else to resolve through, whereas a
+     * header/footer band block carries its full anchor in `data-hf-anchor` and is resolved from
+     * that (see `anchorIdOf`). Letting a non-body scope win here would silently redirect a body
+     * edit into a header part.
+     */
     refreshAnchorMap() {
       const proj = JSON.parse(this.exports.DocxSessionBridge.Project(this.handle));
       this.unidToFullId.clear();
+      const bodyOwned = /* @__PURE__ */ new Set();
       for (const [fullId, target] of Object.entries(proj.anchorIndex)) {
+        const isBody = target.scope === "body";
+        if (!isBody && bodyOwned.has(target.unid)) continue;
         this.unidToFullId.set(target.unid, fullId);
+        if (isBody) bodyOwned.add(target.unid);
       }
     }
+    /**
+     * The full `kind:scope:unid` anchor for a rendered block. A header/footer band block carries
+     * its own — the unid map cannot disambiguate one, since several parts' story paragraphs can
+     * share a content-addressed unid (a real Word document with empty default/first/even stories
+     * does exactly that, and a unid-keyed lookup would land the edit in the wrong header part).
+     */
+    anchorIdOf(el) {
+      const stamped = el.getAttribute("data-hf-anchor");
+      if (stamped) return stamped;
+      const unid = el.getAttribute("data-anchor");
+      return unid ? this.unidToFullId.get(unid) : void 0;
+    }
+    /** Build the header/footer region (called once, before the first mount). */
+    createRegion() {
+      this.region = new HeaderFooterRegion(
+        this.exports.DocxSessionBridge,
+        this.handle,
+        { cssPrefix: this.options.cssPrefix, fabricateClasses: this.options.fabricateClasses },
+        {
+          wireBlock: (el) => this.wireBlock(el),
+          refreshAnchorMap: () => this.refreshAnchorMap()
+        }
+      );
+    }
+    /**
+     * Point the bands at the section governing the current focus (or the first body block).
+     * Called after every mount, and on focus of a body block, so a multi-section document shows
+     * the stories that actually apply where the caret is.
+     */
+    syncRegionToBody(fromBlock) {
+      if (!this.region) return;
+      const block = fromBlock ?? this.editableList()[0];
+      const unid = block?.getAttribute("data-anchor");
+      const id = unid ? this.unidToFullId.get(unid) : void 0;
+      this.region.syncToBody(id ?? null);
+    }
+    /**
+     * Insert the bands around `bodyRoot` and make `bodyRoot` the edit root. Band blocks must stay
+     * OUT of the edit root: `editableList()`/`blockIndex()` enumerate it to compute remount focus
+     * indices, and band blocks in that list would shift every index.
+     */
+    dockBands(bodyRoot) {
+      if (!this.region) return;
+      bodyRoot.before(this.region.headerBand);
+      bodyRoot.after(this.region.footerBand);
+      this.region.refreshAll();
+    }
     /** Continuous (non-paginated) mount: inject the converter's styles + body, wire blocks. */
     mountHtml(fullHtml) {
       const parsed = new DOMParser().parseFromString(fullHtml, "text/html");
       const styles = Array.from(parsed.querySelectorAll("style")).map((s) => s.outerHTML).join("");
-      this.container.innerHTML = styles + parsed.body.innerHTML;
-      this.editRoot = this.container;
-      if (this.options.editable) this.wireBlocks(this.container);
+      if (!this.region) {
+        this.container.innerHTML = styles + parsed.body.innerHTML;
+        this.editRoot = this.container;
+        if (this.options.editable) this.wireBlocks(this.container);
+        return;
+      }
+      this.container.innerHTML = styles;
+      const flow = document.createElement("div");
+      flow.className = "docx-body-flow";
+      flow.innerHTML = parsed.body.innerHTML;
+      this.container.appendChild(flow);
+      this.editRoot = flow;
+      if (this.options.editable) this.wireBlocks(flow);
+      this.dockBands(flow);
     }
     /** Paginated mount: flow blocks into page boxes via pagination.ts, wire the page clones. */
     mountPaginated(fullHtml) {
-      paginateHtml(fullHtml, this.container, { scale: this.options.scale, cssPrefix: "page-" });
+      let target = this.container;
+      if (this.region) {
+        this.container.innerHTML = "";
+        target = document.createElement("div");
+        target.className = "docx-body-flow";
+        this.container.appendChild(target);
+      }
+      paginateHtml(fullHtml, target, {
+        scale: this.options.scale,
+        cssPrefix: "page-",
+        fragmentParagraphs: false
+      });
       this.container.querySelector("#pagination-staging, .page-staging")?.remove();
-      const pageRoot = this.container.querySelector("#pagination-container") ?? this.container;
+      const pageRoot = target.querySelector("#pagination-container") ?? target;
       this.editRoot = pageRoot;
       if (this.options.editable) this.wireBlocks(pageRoot);
+      if (this.region) this.dockBands(target);
     }
     wireBlocks(root) {
       root.querySelectorAll("[data-anchor]").forEach((el) => this.wireBlock(el));
@@ -1289,15 +2225,18 @@ var DocxodusEditor = (() => {
     wireBlock(el) {
       if (!EDITABLE_TAGS.has(el.tagName)) return;
       const unid = el.getAttribute("data-anchor");
-      if (!unid || !this.unidToFullId.has(unid)) return;
+      if (!unid || !this.anchorIdOf(el)) return;
       el.setAttribute("contenteditable", "true");
       el.querySelectorAll("[data-list-marker]").forEach((m) => m.setAttribute("contenteditable", "false"));
       el.dataset.committedText = blockContentText(el);
       el.addEventListener("focus", () => {
         this.activeBlock = el;
+        if (this.region && !this.isBandBlock(el)) this.syncRegionToBody(el);
       });
       el.addEventListener("blur", () => this.commitBlock(el));
       el.addEventListener("keydown", (ev) => this.onKeydown(el, ev));
+      const stamped = el.getAttribute("data-hf-anchor");
+      if (stamped && this.region?.contains(el)) this.region.adoptBlock(el, stamped);
     }
     /**
      * Replace `oldEl` with `newNodes`, suppressing the re-entrant blur→commit that removing a focused
@@ -1327,7 +2266,7 @@ var DocxodusEditor = (() => {
       if (this.closed || this.replacing) return;
       const unid = el.getAttribute("data-anchor");
       if (!unid) return;
-      const fullId = this.unidToFullId.get(unid);
+      const fullId = this.anchorIdOf(el);
       if (!fullId) return;
       const result = this.commitTextChange(el, fullId);
       if (!result) return;
@@ -1354,9 +2293,14 @@ var DocxodusEditor = (() => {
       );
       if (html.charCodeAt(0) !== 123) {
         const fresh = new DOMParser().parseFromString(html, "text/html").body.firstElementChild;
+        const inBand = this.isBandBlock(el);
         if (fresh && this.replaceNode(el, fresh)) {
-          this.unidToFullId.delete(unid);
-          this.unidToFullId.set(newUnid, newAnchor);
+          if (inBand) {
+            this.region.adoptBlock(fresh, newAnchor);
+          } else {
+            this.unidToFullId.delete(unid);
+            this.unidToFullId.set(newUnid, newAnchor);
+          }
           this.wireBlock(fresh);
           if (this.activeBlock === el) this.activeBlock = fresh;
         }
@@ -1432,7 +2376,7 @@ var DocxodusEditor = (() => {
       const rawOffset = caretOffsetIn(el);
       const unid = el.getAttribute("data-anchor");
       if (rawOffset == null || !unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(el);
       if (!fullId) return;
       const offset = trimmedSplitOffset(el, rawOffset);
       const idx = this.blockIndex(el);
@@ -1444,17 +2388,23 @@ var DocxodusEditor = (() => {
       const second = res.created?.[0];
       if (!first || !second) return;
       if (this.affectsList(res) || wrappedInBorder) {
-        this.remount(idx + 1, false);
+        this.refreshAfter(el, idx + 1, false);
         this.options.onEdit?.({ anchorId: second.id, unid: second.unid });
         return;
       }
       const firstEl = this.renderInto(first.id);
       const secondEl = this.renderInto(second.id);
       if (!firstEl || !secondEl) return;
+      const inBand = this.isBandBlock(el);
       if (!this.replaceNode(el, firstEl, secondEl)) return;
-      this.unidToFullId.delete(unid);
-      this.unidToFullId.set(first.unid, first.id);
-      this.unidToFullId.set(second.unid, second.id);
+      if (inBand) {
+        this.region.adoptBlock(firstEl, first.id);
+        this.region.adoptBlock(secondEl, second.id);
+      } else {
+        this.unidToFullId.delete(unid);
+        this.unidToFullId.set(first.unid, first.id);
+        this.unidToFullId.set(second.unid, second.id);
+      }
       this.wireBlock(firstEl);
       this.wireBlock(secondEl);
       placeCaretAtOffset(secondEl, 0);
@@ -1465,8 +2415,8 @@ var DocxodusEditor = (() => {
       const prevUnid = prev.getAttribute("data-anchor");
       const thisUnid = el.getAttribute("data-anchor");
       if (!prevUnid || !thisUnid) return;
-      let prevId = this.unidToFullId.get(prevUnid);
-      let thisId = this.unidToFullId.get(thisUnid);
+      let prevId = this.anchorIdOf(prev);
+      let thisId = this.anchorIdOf(el);
       if (!prevId || !thisId) return;
       const prevIdx = this.blockIndex(prev);
       const wrappedInBorder = inBorderWrapper(prev) || inBorderWrapper(el);
@@ -1478,17 +2428,22 @@ var DocxodusEditor = (() => {
       const merged = res.modified?.[0];
       if (!merged) return;
       if (this.affectsList(res) || wrappedInBorder) {
-        this.remount(prevIdx, true);
+        this.refreshAfter(el, prevIdx, true);
         this.options.onEdit?.({ anchorId: merged.id, unid: merged.unid });
         return;
       }
       const mergedEl = this.renderInto(merged.id);
       if (!mergedEl) return;
+      const inBand = this.isBandBlock(prev);
       if (!this.replaceNode(prev, mergedEl)) return;
       el.remove();
-      this.unidToFullId.delete(prevUnid);
-      this.unidToFullId.delete(thisUnid);
-      this.unidToFullId.set(merged.unid, merged.id);
+      if (inBand) {
+        this.region.adoptBlock(mergedEl, merged.id);
+      } else {
+        this.unidToFullId.delete(prevUnid);
+        this.unidToFullId.delete(thisUnid);
+        this.unidToFullId.set(merged.unid, merged.id);
+      }
       this.wireBlock(mergedEl);
       placeCaretAtOffset(mergedEl, caret);
       this.options.onEdit?.({ anchorId: merged.id, unid: merged.unid });
@@ -1551,10 +2506,10 @@ var DocxodusEditor = (() => {
       if (html.charCodeAt(0) === 123) return null;
       return new DOMParser().parseFromString(html, "text/html").body.firstElementChild;
     }
-    /** The editable block immediately before `el` in document order, or null. */
+    /** The editable block immediately before `el` within its own root, or null. */
     previousEditable(el) {
       const all = Array.from(
-        this.editRoot.querySelectorAll('[data-anchor][contenteditable="true"]')
+        this.ownerRoot(el).querySelectorAll('[data-anchor][contenteditable="true"]')
       );
       const i = all.indexOf(el);
       return i > 0 ? all[i - 1] : null;
@@ -1574,8 +2529,9 @@ var DocxodusEditor = (() => {
      *  A collapsed or single-block selection yields just the active block. */
     selectedBlocks() {
       const sel = typeof window !== "undefined" ? window.getSelection() : null;
+      const root = this.activeBlock ? this.ownerRoot(this.activeBlock) : this.editRoot;
       const all = Array.from(
-        this.editRoot.querySelectorAll('[data-anchor][contenteditable="true"]')
+        root.querySelectorAll('[data-anchor][contenteditable="true"]')
       );
       if (sel && sel.rangeCount > 0 && !sel.isCollapsed) {
         const range = sel.getRangeAt(0);
@@ -1605,13 +2561,13 @@ var DocxodusEditor = (() => {
       const contentLen = blockContentText(block).length;
       if (hasStart) {
         const start = contentOffsetOf(block, range.startContainer, range.startOffset);
-        return { start, length: Math.max(0, contentLen - start) };
+        return trimmedSpan(block, { start, length: Math.max(0, contentLen - start) });
       }
       if (hasEnd) {
         const end = contentOffsetOf(block, range.endContainer, range.endOffset);
-        return { start: 0, length: end };
+        return trimmedSpan(block, { start: 0, length: end });
       }
-      return { start: 0, length: contentLen };
+      return trimmedSpan(block, { start: 0, length: contentLen });
     }
     /** Apply an inline ApplyFormat op to each block's slice of the selection, then reconcile
      *  the DOM incrementally (see {@link finishMultiBlockOp} — a full remount costs a whole-
@@ -1658,7 +2614,7 @@ var DocxodusEditor = (() => {
         return {
           block: b,
           unid,
-          fullId: unid ? this.unidToFullId.get(unid) : void 0,
+          fullId: this.anchorIdOf(b),
           span: this.blockSpanForSelection(b),
           res: null
         };
@@ -1678,7 +2634,7 @@ var DocxodusEditor = (() => {
       const edited = targets.filter((t) => t.res && t.unid);
       if (edited.length === 0) return;
       if (forceRemount || this.options.paginated || edited.some((t) => this.affectsList(t.res))) {
-        this.remount();
+        this.refreshAfter(edited[0].block, -1, false);
         return;
       }
       const swapped = [];
@@ -1721,7 +2677,7 @@ var DocxodusEditor = (() => {
       }
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const span = selectionSpanIn(block);
       const on = value ?? !selectionHasFormat(key, block);
@@ -1737,7 +2693,7 @@ var DocxodusEditor = (() => {
       );
       if (!res.success) return;
       if (this.affectsList(res)) {
-        this.remount(this.blockIndex(block), false);
+        this.refreshAfter(block, this.blockIndex(block), false);
         return;
       }
       const fresh = this.swapBlock(block, unid, res.modified?.[0]);
@@ -1756,7 +2712,7 @@ var DocxodusEditor = (() => {
       if (blocks.length > 1 && this.applyInlineOpAcrossBlocks(blocks, { fontSizePts: pts })) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       let span = selectionSpanIn(block);
       if (!span && this.lastSelection && this.lastSelection.unid === unid) span = this.lastSelection.span;
@@ -1771,7 +2727,7 @@ var DocxodusEditor = (() => {
       );
       if (!res.success) return;
       if (this.affectsList(res)) {
-        this.remount(this.blockIndex(block), false);
+        this.refreshAfter(block, this.blockIndex(block), false);
         return;
       }
       const fresh = this.swapBlock(block, unid, res.modified?.[0]);
@@ -1792,7 +2748,7 @@ var DocxodusEditor = (() => {
       if (blocks.length > 1 && this.applyInlineOpAcrossBlocks(blocks, { fontFamily: name })) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       let span = selectionSpanIn(block);
       if (!span && this.lastSelection && this.lastSelection.unid === unid) span = this.lastSelection.span;
@@ -1807,7 +2763,7 @@ var DocxodusEditor = (() => {
       );
       if (!res.success) return;
       if (this.affectsList(res)) {
-        this.remount(this.blockIndex(block), false);
+        this.refreshAfter(block, this.blockIndex(block), false);
         return;
       }
       const fresh = this.swapBlock(block, unid, res.modified?.[0]);
@@ -1828,7 +2784,7 @@ var DocxodusEditor = (() => {
       if (this.closed || !block) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
@@ -1841,7 +2797,7 @@ var DocxodusEditor = (() => {
         )
       );
       if (!res.success) return;
-      this.remount(idx, false);
+      this.refreshAfter(block, idx, false);
     }
     /**
      * Insert a `rows`×`cols` table after the active block. `options.cellContents` (row-major
@@ -1853,7 +2809,7 @@ var DocxodusEditor = (() => {
       if (this.closed || !block) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
@@ -1869,7 +2825,7 @@ var DocxodusEditor = (() => {
         )
       );
       if (!res.success) return;
-      this.remount(idx, false);
+      this.refreshAfter(block, idx, false);
     }
     // ─── Table row / column editing (active block must be inside a table cell) ──────────
     /** Run a table-structure op on the active cell (a cell-paragraph block) and re-render. */
@@ -1878,13 +2834,13 @@ var DocxodusEditor = (() => {
       if (this.closed || !block || !block.closest("table")) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
       const res = this.parseEdit(run(fullId));
       if (!res.success) return;
-      this.remount(idx, false);
+      this.refreshAfter(block, idx, false);
     }
     /** Insert a row above/below the active cell's row. No-op outside a table. */
     insertTableRow(where) {
@@ -1925,13 +2881,13 @@ var DocxodusEditor = (() => {
       if (this.closed || !block) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
       const res = this.parseEdit(this.exports.DocxSessionBridge.SetListLevel(this.handle, fullId, delta));
       if (!res.success) return;
-      this.remount(idx, false);
+      this.refreshAfter(block, idx, false);
     }
     /** Toggle (or set) page-break-before on the active block. */
     pageBreakBefore(value = true) {
@@ -1946,7 +2902,7 @@ var DocxodusEditor = (() => {
       if (this.closed || !block) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       let membership = null;
       try {
@@ -1960,7 +2916,7 @@ var DocxodusEditor = (() => {
         this.exports.DocxSessionBridge.ApplyListFormat(this.handle, fullId, isThisKind ? "none" : kind)
       );
       if (!res.success) return;
-      this.remount(idx, false);
+      this.refreshAfter(block, idx, false);
     }
     /** Clear all paragraph borders (e.g. remove an inserted horizontal rule) on the active block —
      *  or every block in a multi-block selection. The engine/wire already accept `clearBorders`;
@@ -1982,12 +2938,12 @@ var DocxodusEditor = (() => {
       if (this.editableList().length <= 1) return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      const fullId = this.unidToFullId.get(unid);
+      const fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       const res = this.parseEdit(this.exports.DocxSessionBridge.DeleteBlock(this.handle, fullId));
       if (!res.success) return;
-      this.remount(Math.max(0, idx - 1), true);
+      this.refreshAfter(block, Math.max(0, idx - 1), true);
     }
     applyParagraphFormat(op) {
       const block = this.activeBlock;
@@ -2002,7 +2958,7 @@ var DocxodusEditor = (() => {
         return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
@@ -2011,7 +2967,7 @@ var DocxodusEditor = (() => {
       );
       if (!res.success) return;
       if (this.affectsList(res) || op.clearBorders) {
-        this.remount(idx, false);
+        this.refreshAfter(block, idx, false);
         return;
       }
       this.swapBlock(block, unid, res.modified?.[0])?.focus();
@@ -2029,14 +2985,14 @@ var DocxodusEditor = (() => {
         return;
       const unid = block.getAttribute("data-anchor");
       if (!unid) return;
-      let fullId = this.unidToFullId.get(unid);
+      let fullId = this.anchorIdOf(block);
       if (!fullId) return;
       const idx = this.blockIndex(block);
       fullId = this.syncBlock(block, fullId);
       const res = this.parseEdit(this.exports.DocxSessionBridge.SetParagraphStyle(this.handle, fullId, styleId));
       if (!res.success) return;
       if (this.affectsList(res)) {
-        this.remount(idx, false);
+        this.refreshAfter(block, idx, false);
         return;
       }
       this.swapBlock(block, unid, res.modified?.[0])?.focus();
@@ -2051,6 +3007,37 @@ var DocxodusEditor = (() => {
       if (this.closed) return;
       if (this.exports.DocxSessionBridge.Redo(this.handle)) this.remount();
     }
+    // ─── Header/footer region commands (no-ops unless `headerFooter` is on) ───────────────
+    /**
+     * Select which story kind a band edits (`"default"` / `"first"` / `"even"`). A kind with no
+     * existing part is created empty, so the band always presents something editable. `"first"`
+     * sets the section's `w:titlePg`; `"even"` sets the document-global `w:evenAndOddHeaders`
+     * (which also governs footers — the band surfaces that caveat inline).
+     */
+    setHeaderFooterKind(which, kind) {
+      this.assertOpen();
+      this.region?.setKind(which, kind);
+    }
+    /** The story kind a band is currently editing, or null when the region is off. */
+    headerFooterKind(which) {
+      return this.region?.kindOf(which) ?? null;
+    }
+    /**
+     * Append a page-number field to the focused header/footer story paragraph (falling back to the
+     * band's last paragraph — Word's convention). No-op outside a band.
+     */
+    insertPageNumber(field = "currentPage") {
+      this.assertOpen();
+      if (!this.region) return;
+      const block = this.activeBlock;
+      const band = block ? this.region.bandOf(block) : null;
+      const anchorId = block?.getAttribute("data-hf-anchor");
+      if (band && anchorId) {
+        this.region.insertPageNumber(this.region.whichOf(band), anchorId, field);
+        return;
+      }
+      this.region.insertPageNumberInBand("footer", field);
+    }
     /** Which inline formats the current selection carries — for ribbon button highlighting. */
     queryFormatState() {
       const block = this.activeBlock ?? this.editRoot;
@@ -2066,13 +3053,17 @@ var DocxodusEditor = (() => {
     }
     /** Re-render one block from the live session by EditResult ref, swapping it in place. */
     swapBlock(oldEl, oldUnid, ref) {
-      const anchorId = ref?.id ?? this.unidToFullId.get(oldUnid);
+      const inBand = this.isBandBlock(oldEl);
+      const anchorId = ref?.id ?? this.anchorIdOf(oldEl);
       const newUnid = ref?.unid ?? oldUnid;
       if (!anchorId) return null;
       const fresh = this.renderInto(anchorId);
       if (!fresh || !this.replaceNode(oldEl, fresh)) return null;
-      this.unidToFullId.delete(oldUnid);
-      this.unidToFullId.set(newUnid, anchorId);
+      if (!inBand) {
+        this.unidToFullId.delete(oldUnid);
+        this.unidToFullId.set(newUnid, anchorId);
+      }
+      if (inBand) this.region.adoptBlock(fresh, anchorId);
       this.wireBlock(fresh);
       this.activeBlock = fresh;
       this.options.onEdit?.({ anchorId, unid: newUnid });
@@ -2102,12 +3093,14 @@ var DocxodusEditor = (() => {
         ...completeArgs(bytes, this.options.cssPrefix, this.options.fabricateClasses, this.options.paginated, this.options.scale)
       );
     }
-    /** Editable blocks in document order. */
+    /** Editable BODY blocks in document order (band blocks are enumerated by `ownerRoot`). */
     editableList() {
       return Array.from(this.editRoot.querySelectorAll('[data-anchor][contenteditable="true"]'));
     }
     blockIndex(el) {
-      return this.editableList().indexOf(el);
+      return Array.from(
+        this.ownerRoot(el).querySelectorAll('[data-anchor][contenteditable="true"]')
+      ).indexOf(el);
     }
     /**
      * True when an edit produced or touched a list item (kind "li"). List markers and
@@ -2137,6 +3130,7 @@ var DocxodusEditor = (() => {
           placeCaretAtOffset(target, caretAtEnd ? (target.textContent ?? "").length : 0);
         }
       }
+      this.syncRegionToBody(this.activeBlock ?? void 0);
     }
   };
   return __toCommonJS(editor_exports);