docxodus 7.1.0 → 9.0.0

package/dist/editor.js

@@ -17,6 +17,8 @@
  * full fidelity, and save() is lossless for them.
  */
 import { paginateHtml } from "./pagination.js";
+import { HeaderFooterRegion } from "./editor-headerfooter.js";
+import { diffUnits, needsRemount, unidOf } from "./editor-reconcile.js";
 const EDITABLE_TAGS = new Set(["P", "H1", "H2", "H3", "H4", "H5", "H6"]);
 function fontWeightIsBold(w) {
     if (w === "bold" || w === "bolder")
@@ -30,8 +32,9 @@ function escapeInlineMarkdown(text) {
 }
 function collectInlineSegments(node, out) {
     node.childNodes.forEach((child) => {
-        // Skip generated list-marker spans — they aren't part of the paragraph's content.
-        if (child.nodeType === 1 && child.hasAttribute?.("data-list-marker"))
+        // Skip converter-generated chrome (list markers, note citation markers, note backrefs) —
+        // it isn't part of the paragraph's content and must never be committed as text.
+        if (isGeneratedChrome(child))
             return;
         if (child.nodeType === 3 /* TEXT_NODE */) {
             const text = child.textContent ?? "";
@@ -111,11 +114,27 @@ export function serializeInlineMarkdown(block) {
 function isListBlock(block) {
     return !!block.querySelector(":scope > [data-list-marker]");
 }
-/** True if `node` is, or is inside, a generated list-marker span (not editable content). */
+/**
+ * Inline chrome the CONVERTER generates that is not part of a paragraph's run text: list
+ * number/bullet markers, footnote/endnote citation markers
+ * (`<a class="footnote-ref"><sup>1</sup></a>`), and the note backrefs (`↩`).
+ *
+ * The session's run text contains none of it. A citation is a zero-width
+ * `w:footnoteReference` — the displayed number is computed by the renderer from document order —
+ * so every character of chrome the editor fails to exclude shifts its content-offset space away
+ * from the session's. Each omission has its own failure mode: excluded from offsets but not from
+ * serialization and the display number gets COMMITTED as literal text (destroying the citation
+ * run); left editable and the user can delete a marker outright, orphaning the note.
+ */
+const GENERATED_CHROME_SELECTOR = '[data-list-marker], a.footnote-ref, a.endnote-ref, a[class$="-backref"]';
+function isGeneratedChrome(node) {
+    return node?.nodeType === 1 && !!node.matches?.(GENERATED_CHROME_SELECTOR);
+}
+/** True if `node` is, or is inside, generated chrome (not editable content). */
 function isInMarker(node) {
     let el = node && node.nodeType === 1 ? node : node?.parentElement ?? null;
     while (el) {
-        if (el.hasAttribute && el.hasAttribute("data-list-marker"))
+        if (isGeneratedChrome(el))
             return true;
         el = el.parentElement;
     }
@@ -221,11 +240,36 @@ function blockContentText(block) {
  * trimmed length keeps the split offset consistent with what was committed.
  */
 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));
 }
+/** How far `block`'s DOM content text is offset from, and longer than, its committed form. */
+function trimBounds(block) {
+    const content = blockContentText(block);
+    return {
+        leading: content.length - content.replace(/^\s+/, "").length,
+        trimmedLen: content.trim().length,
+    };
+}
+/**
+ * Map a DOM content SPAN into the run-text space the session holds after a commit — the span
+ * analogue of {@link trimmedSplitOffset}, and for the same reason.
+ *
+ * A block rendered with edge whitespace produces a span longer than the text the commit stores:
+ * an empty header/footer story renders as a lone NBSP placeholder, so typing into it leaves a
+ * trailing NBSP that `serializeInlineMarkdown(...).trim()` removes (JS `trim()` treats U+00A0 as
+ * whitespace). "Select all, then Bold" then asks `ApplyFormat` for [0, len+1) — one past the
+ * committed end — and the op is REJECTED with OffsetOutOfRange, so the format silently does
+ * nothing. The demo's format buttons preventDefault on mousedown to keep the selection alive,
+ * which is exactly the path that computes the span before `syncBlock` commits, so this is the
+ * ordinary case rather than an edge one.
+ */
+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 };
+}
 /**
  * DOM (node, offset) for content offset `offset` within `el` — the same content-offset
  * space as contentOffsetOf (marker text and injected bidi marks excluded). Clamps past-end
@@ -314,7 +358,10 @@ function selectionSpanIn(block) {
         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) };
+    // Normalized into the committed run-text space: every consumer feeds this straight to a
+    // DocxSession op, which rejects a span that overshoots the committed length.
+    const span = trimmedSpan(block, { start: Math.min(start, end), length: Math.abs(end - start) });
+    return span.length > 0 ? span : null;
 }
 /** Restore a content-text selection spanning [start, start+length) within `el` (skips markers). */
 function selectRange(el, start, length) {
@@ -396,7 +443,10 @@ function completeArgs(bytes, cssPrefix, fabricate, paginated, scale) {
         bytes, "Document", cssPrefix, fabricate, "", -1, "comment-",
         /* paginationMode */ paginated ? 1 : 0, /* paginationScale */ scale, "page-",
         false, 0, "annot-",
-        /* renderFootnotesAndEndnotes */ false, /* renderHeadersAndFooters */ paginated,
+        // Footnotes/endnotes ON: they are document content, and the editor makes the rendered note
+        // paragraphs editable. Must stay in step with DocxSessionOps.RenderHtml (the remount path),
+        // whose output has to match this first paint byte-for-byte.
+        /* renderFootnotesAndEndnotes */ true, /* renderHeadersAndFooters */ paginated,
         false, true, true, false, null, /* stampAnchors */ true,
     ];
 }
@@ -422,6 +472,11 @@ export class DocxEditor {
          * 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;
+        /** Why the last reconcile() fell back to a full remount (null = it patched). For
+         *  diagnostics/specs; not part of the public API. */
+        this.lastReconcileFallback = null;
         /** Track the last meaningful selection so focus-stealing toolbar controls can still target it. */
         this.onSelectionChange = () => {
             if (this.closed)
@@ -452,13 +507,46 @@ export class DocxEditor {
         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; a body edit reconciles incrementally. `forceRemount` is
+     * for ops whose repaint provably needs whole-document context the reconciler cannot see:
+     * list membership/level changes (sibling numbering shifts without sibling XML changing)
+     * and border-div regrouping (HR insert, clearBorders).
+     */
+    refreshAfter(block, focusIndex, caretAtEnd = false, forceRemount = false) {
+        const band = this.region?.bandOf(block);
+        if (band) {
+            this.region.refresh(this.region.whichOf(band));
+            return;
+        }
+        if (forceRemount)
+            this.remount(focusIndex, caretAtEnd);
+        else
+            this.reconcile(focusIndex, caretAtEnd);
     }
     /** Open a document, render it into `container`, and wire up editing. */
     static open(container, bytes, exports, options = {}) {
@@ -468,20 +556,26 @@ export class DocxEditor {
             editable: options.editable ?? true,
             paginated: options.paginated ?? false,
             scale: options.scale ?? 1,
+            headerFooter: options.headerFooter ?? false,
             onEdit: options.onEdit,
         };
-        // persistAnchorIds=true keeps PtOpenXml:Unid attributes in Save() output, so a remount's
-        // full re-render keeps the SAME unids the live session uses (a content change like becoming
-        // a list otherwise re-derives a fresh unid, leaving the block unwired). The cost is that
-        // saved bytes carry the Unid attributes (Word ignores them).
-        const handle = exports.DocxSessionBridge.OpenSession(bytes, '{"persistAnchorIds":true}');
+        // NOT persistAnchorIds: that setting applies to every Save on the session, so it put the
+        // projector's Unid bookkeeping into the bytes the USER downloads — ~6x the file size for
+        // attributes no renderer reads. Only the remount's re-render needs id stability across a
+        // save/re-render hop, and it asks for that per call via SaveWithAnchorIds.
+        // emitMarkdownPatch off: the editor re-renders from HTML, never from markdown patches,
+        // so paying a whole-document re-projection per op would be dead weight.
+        const handle = exports.DocxSessionBridge.OpenSession(bytes, '{"emitMarkdownPatch":false}');
         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;
     }
     /**
@@ -527,28 +621,126 @@ export class DocxEditor {
         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));
+        const bridge = this.exports.DocxSessionBridge;
+        // ListAnchors returns the same {anchorIndex} object WITHOUT the markdown payload —
+        // marshaling the full projection (a couple hundred KB on a real document) made
+        // this refresh the single biggest term of every incremental repaint.
+        const raw = typeof bridge.ListAnchors === "function"
+            ? bridge.ListAnchors(this.handle)
+            : bridge.Project(this.handle);
+        const proj = JSON.parse(raw);
         this.unidToFullId.clear();
+        const bodyOwned = 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) : undefined;
+    }
+    /** 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) : undefined;
+        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.region) {
+            this.container.innerHTML = styles + parsed.body.innerHTML;
+            this.editRoot = this.container;
+            if (this.options.editable)
+                this.wireBlocks(this.container);
+            this.stampPlanState();
+            return;
+        }
+        // With bands docked, the body flow needs its own wrapper to be the edit root.
+        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(this.container);
+            this.wireBlocks(flow);
+        this.stampPlanState();
+        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-" });
+        // With bands docked, pagination writes into its own wrapper so the bands can sit outside the
+        // page stack (and so pagination's innerHTML reset can never eat them).
+        let target = this.container;
+        if (this.region) {
+            this.container.innerHTML = "";
+            target = document.createElement("div");
+            target.className = "docx-body-flow";
+            this.container.appendChild(target);
+        }
+        // Fragmented paragraphs intentionally have only one addressable head and
+        // are therefore unsuitable for the editor's one-block editing model.
+        paginateHtml(fullHtml, target, {
+            scale: this.options.scale,
+            cssPrefix: "page-",
+            fragmentParagraphs: false,
+        });
         // pagination.ts measures the hidden #pagination-staging subtree ONCE, then flows CLONES of its
         // blocks into the visible page boxes. Leaving staging in the live DOM is a trap: every
         // data-anchor exists twice (staging + page-box copy), so document.querySelector('[data-anchor]')
@@ -557,10 +749,14 @@ export class DocxEditor {
         // is a transient measurement scaffold; drop it so the page-box copies are the single source of
         // truth. A remount (setPaginated, list/undo edits) rebuilds staging fresh from the live session.
         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);
+        // The page boxes render their own (read-only) header/footer margins; the editable bands dock
+        // around the page stack, so there is still exactly one addressable node per story paragraph.
+        if (this.region)
+            this.dockBands(target);
     }
     wireBlocks(root) {
         root.querySelectorAll("[data-anchor]").forEach((el) => this.wireBlock(el));
@@ -573,18 +769,34 @@ export class DocxEditor {
         // table-cell paragraphs (the projection indexes them), so cell text IS editable — but structural
         // keys are kept inert inside a cell (see onKeydown / GAP3) so single-block editing can't corrupt
         // table structure. Anything the projection does not index (unstamped content) stays read-only.
-        if (!unid || !this.unidToFullId.has(unid))
+        // A band block is authoritative via its stamped `data-hf-anchor` even when the unid map
+        // resolves that unid to a different part (content-addressed unids collide across parts).
+        if (!unid || !this.anchorIdOf(el))
             return;
         el.setAttribute("contenteditable", "true");
-        // Generated list markers (number/bullet + suffix) are not editable content — keep the
-        // caret out of them so offsets stay aligned with the paragraph's run text.
-        el.querySelectorAll("[data-list-marker]").forEach((m) => m.setAttribute("contenteditable", "false"));
+        // Generated chrome (list number/bullet, footnote/endnote citation markers, note backrefs) is
+        // not editable content — keep the caret out so offsets stay aligned with the run text, and so
+        // a citation marker can't be deleted directly (which would orphan its note definition).
+        el.querySelectorAll(GENERATED_CHROME_SELECTOR)
+            .forEach((m) => m.setAttribute("contenteditable", "false"));
         // Baseline for the commit diff: CONTENT text (list markers + injected bidi marks excluded),
         // matching the session's flat run-text offset space.
         el.dataset.committedText = blockContentText(el);
-        el.addEventListener("focus", () => { this.activeBlock = el; });
+        el.addEventListener("focus", () => {
+            this.activeBlock = el;
+            // Follow the caret's section so a cover-page-plus-body document shows the stories that
+            // actually apply. Focusing a BAND block must not re-sync: it has no governing section of
+            // its own, and re-resolving would clobber the user's kind selection.
+            if (this.region && !this.isBandBlock(el))
+                this.syncRegionToBody(el);
+        });
         el.addEventListener("blur", () => this.commitBlock(el));
         el.addEventListener("keydown", (ev) => this.onKeydown(el, ev));
+        // A band block re-rendered by an incremental swap is a fresh DOM node; re-adopt it (with the
+        // anchor its caller already stamped) so the band chrome can still address it.
+        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
@@ -619,7 +831,7 @@ export class DocxEditor {
         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);
@@ -651,12 +863,22 @@ export class DocxEditor {
         const html = this.exports.DocxSessionBridge.RenderBlockHtml(this.handle, newAnchor, this.options.cssPrefix, this.options.fabricateClasses);
         if (html.charCodeAt(0) !== 0x7b /* not an error object */) {
             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);
+                // Band blocks resolve through `data-hf-anchor`; their unid can collide with another
+                // part's, so writing it into the map would corrupt that entry (see anchorIdOf).
+                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; // keep ribbon target valid
+                // The throwaway render numbers citation markers from 1 — repair in place.
+                this.maybeRenumberNotes(fresh);
             }
         }
         this.options.onEdit?.({ anchorId: newAnchor, unid: newUnid });
@@ -748,7 +970,7 @@ export class DocxEditor {
         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;
         // The session commits trimmed text, so map the DOM caret offset into the trimmed run-text
@@ -770,7 +992,7 @@ export class DocxEditor {
         // document re-render so numbering continues / border <div>s regroup correctly. An in-place node
         // swap would leave the new paragraph inside the old border div (the rule's line under its text).
         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;
         }
@@ -780,11 +1002,19 @@ export class DocxEditor {
             return;
         // el is the focused block — replaceNode guards the re-entrant blur→commit and tolerates a
         // node detached mid-focus-transfer; replacing with both new blocks at once keeps them adjacent.
+        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);
+        // Band blocks resolve through `data-hf-anchor` (their unids can collide across parts).
+        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);
@@ -796,8 +1026,8 @@ export class DocxEditor {
         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); // capture before the op
@@ -816,7 +1046,7 @@ export class DocxEditor {
         // Merging list items renumbers the list, and merging across a border <div> boundary changes the
         // border grouping — both need a whole-document re-render (caret at the merge boundary).
         if (this.affectsList(res) || wrappedInBorder) {
-            this.remount(prevIdx, true);
+            this.refreshAfter(el, prevIdx, true);
             this.options.onEdit?.({ anchorId: merged.id, unid: merged.unid });
             return;
         }
@@ -824,12 +1054,19 @@ export class DocxEditor {
         if (!mergedEl)
             return;
         // prev may be focused — replaceNode guards re-entrancy and tolerates a detached node.
+        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);
+        // Band blocks resolve through `data-hf-anchor` (their unids can collide across parts).
+        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 });
@@ -896,9 +1133,9 @@ export class DocxEditor {
             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"]'));
+        const all = Array.from(this.ownerRoot(el).querySelectorAll('[data-anchor][contenteditable="true"]'));
         const i = all.indexOf(el);
         return i > 0 ? all[i - 1] : null;
     }
@@ -918,7 +1155,10 @@ export class DocxEditor {
      *  A collapsed or single-block selection yields just the active block. */
     selectedBlocks() {
         const sel = typeof window !== "undefined" ? window.getSelection() : null;
-        const all = Array.from(this.editRoot.querySelectorAll('[data-anchor][contenteditable="true"]'));
+        // Enumerate the ACTIVE block's own root — a band's story container, else the body edit root —
+        // so a selection can never span a band and the body (different OOXML parts).
+        const root = this.activeBlock ? this.ownerRoot(this.activeBlock) : this.editRoot;
+        const all = Array.from(root.querySelectorAll('[data-anchor][contenteditable="true"]'));
         if (sel && sel.rangeCount > 0 && !sel.isCollapsed) {
             const range = sel.getRangeAt(0);
             const hit = all.filter((b) => {
@@ -948,16 +1188,18 @@ export class DocxEditor {
         const hasEnd = block.contains(range.endContainer);
         if (hasStart && hasEnd)
             return selectionSpanIn(block);
+        // Partial/whole slices are normalized into the committed run-text space for the same reason
+        // selectionSpanIn is (see trimmedSpan): a session op rejects a span past the committed end.
         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 }; // fully-spanned middle block
+        return trimmedSpan(block, { start: 0, length: contentLen }); // fully-spanned middle block
     }
     /** 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-
@@ -1005,7 +1247,7 @@ export class DocxEditor {
             return {
                 block: b,
                 unid,
-                fullId: unid ? this.unidToFullId.get(unid) : undefined,
+                fullId: this.anchorIdOf(b),
                 span: this.blockSpanForSelection(b),
                 res: null,
             };
@@ -1029,7 +1271,7 @@ export class DocxEditor {
         // need a reflow — keep the (pre-existing) full remount there until M4 lands a scoped
         // re-paginate. Continuous mode reconciles incrementally.
         if (forceRemount || this.options.paginated || edited.some((t) => this.affectsList(t.res))) {
-            this.remount();
+            this.refreshAfter(edited[0].block, -1, false);
             return;
         }
         const swapped = [];
@@ -1081,7 +1323,7 @@ export class DocxEditor {
         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);
@@ -1095,7 +1337,7 @@ export class DocxEditor {
         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]);
@@ -1119,7 +1361,7 @@ export class DocxEditor {
         const unid = block.getAttribute("data-anchor");
         if (!unid)
             return;
-        let fullId = this.unidToFullId.get(unid);
+        let fullId = this.anchorIdOf(block);
         if (!fullId)
             return;
         // Use the live selection; if the font-size combobox stole focus and collapsed it, fall back to
@@ -1132,7 +1374,7 @@ export class DocxEditor {
         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]);
@@ -1158,7 +1400,7 @@ export class DocxEditor {
         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);
@@ -1169,7 +1411,7 @@ export class DocxEditor {
         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]);
@@ -1194,7 +1436,7 @@ export class DocxEditor {
         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);
@@ -1202,9 +1444,10 @@ export class DocxEditor {
         const res = this.parseEdit(this.exports.DocxSessionBridge.InsertHorizontalRule(this.handle, fullId, position === "above" ? "before" : "after", JSON.stringify({ style, size: weight, color: "auto" })));
         if (!res.success)
             return;
-        // remount from the active block's index re-renders the new rule whether it landed just
-        // above (at idx) or just below (at idx+1) the active block.
-        this.remount(idx, false);
+        // Remount from the active block's index re-renders the new rule whether it landed just
+        // above (at idx) or just below (at idx+1) the active block. Forced: a rule is a bordered
+        // paragraph, and border-div grouping is whole-document render context.
+        this.refreshAfter(block, idx, false, /* forceRemount */ true);
     }
     /**
      * Insert a `rows`×`cols` table after the active block. `options.cellContents` (row-major
@@ -1218,7 +1461,7 @@ export class DocxEditor {
         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);
@@ -1230,7 +1473,7 @@ export class DocxEditor {
         const res = this.parseEdit(this.exports.DocxSessionBridge.InsertTable(this.handle, fullId, emptyHere ? "before" : "after", rows, cols, options ? JSON.stringify(options) : ""));
         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. */
@@ -1241,7 +1484,7 @@ export class DocxEditor {
         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);
@@ -1249,7 +1492,7 @@ export class DocxEditor {
         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) {
@@ -1288,7 +1531,7 @@ export class DocxEditor {
         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);
@@ -1297,8 +1540,8 @@ export class DocxEditor {
         if (!res.success)
             return;
         // A level change ripples through the whole list's numbering — re-render with full document
-        // context (a single-block render can't compute nested numbering), keeping the caret in place.
-        this.remount(idx, false);
+        // context (sibling numbers shift without sibling XML changing), keeping the caret in place.
+        this.refreshAfter(block, idx, false, /* forceRemount */ true);
     }
     /** Toggle (or set) page-break-before on the active block. */
     pageBreakBefore(value = true) {
@@ -1315,7 +1558,7 @@ export class DocxEditor {
         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;
@@ -1331,8 +1574,8 @@ export class DocxEditor {
         if (!res.success)
             return;
         // Numbering continuation across the list needs whole-document context — re-render fully
-        // (a single-block render would show every numbered item as "1.").
-        this.remount(idx, false);
+        // (sibling numbers shift without sibling XML changing).
+        this.refreshAfter(block, idx, false, /* forceRemount */ true);
     }
     /** 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`;
@@ -1358,14 +1601,56 @@ export class DocxEditor {
         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);
+    }
+    /**
+     * Cite a new footnote from the caret position in the active body block. The note definition is
+     * created (writing the whole Word scaffold — part, reserved separator notes, settings
+     * declaration, styles — on a document that has none yet) and its body renders as ordinary
+     * editable `data-anchor` blocks in the notes section, so editing it afterwards needs no new op.
+     *
+     * Body blocks only: Word disallows a note reference inside a header/footer story or inside
+     * another note, and the session rejects those with `AnchorWrongKind`. Remounts, because a new
+     * note renumbers the citations after it and can add a whole part.
+     */
+    insertFootnote(markdown = "New footnote.") {
+        this.insertNote("footnote", markdown);
+    }
+    /** Cite a new endnote from the caret — see {@link insertFootnote}; writes the endnotes part. */
+    insertEndnote(markdown = "New endnote.") {
+        this.insertNote("endnote", markdown);
+    }
+    insertNote(kind, markdown) {
+        const block = this.activeBlock;
+        if (this.closed || !block)
+            return;
+        // A note reference is legal only in the main story: not in a header/footer band, and not
+        // inside an existing note's body (both render as editable blocks here).
+        if (this.isBandBlock(block) || block.closest(".footnotes, .endnotes"))
+            return;
+        let fullId = this.anchorIdOf(block);
+        if (!fullId)
+            return;
+        const idx = this.blockIndex(block);
+        // Offset first: syncBlock re-renders the block and would drop the live selection.
+        const raw = caretOffsetIn(block);
+        fullId = this.syncBlock(block, fullId);
+        const offset = trimmedSplitOffset(block, raw ?? (block.textContent ?? "").length);
+        const bridge = this.exports.DocxSessionBridge;
+        const call = kind === "footnote" ? bridge.InsertFootnote : bridge.InsertEndnote;
+        if (!call)
+            return; // bridge predates note authoring
+        const res = this.parseEdit(call.call(bridge, this.handle, fullId, offset, markdown));
+        if (!res.success)
+            return;
+        this.reconcile(idx, false);
     }
     applyParagraphFormat(op) {
         const block = this.activeBlock;
@@ -1380,7 +1665,7 @@ export class DocxEditor {
         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);
@@ -1391,7 +1676,7 @@ export class DocxEditor {
         // A border change adds/removes the wrapping border <div>, so a single-block swap can't restructure
         // it correctly — re-render fully (like list edits) so the wrapper appears/disappears cleanly.
         if (this.affectsList(res) || op.clearBorders) {
-            this.remount(idx, false);
+            this.refreshAfter(block, idx, false, true);
             return;
         }
         this.swapBlock(block, unid, res.modified?.[0])?.focus();
@@ -1409,7 +1694,7 @@ export class DocxEditor {
         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);
@@ -1418,24 +1703,82 @@ export class DocxEditor {
         if (!res.success)
             return;
         if (this.affectsList(res)) {
-            this.remount(idx, false);
+            this.refreshAfter(block, idx, false, true);
             return;
         }
         this.swapBlock(block, unid, res.modified?.[0])?.focus();
     }
-    /** Undo the last edit (re-renders the document). */
+    /** Undo the last edit (incremental repaint; falls back to a full re-render). */
     undo() {
         if (this.closed)
             return;
         if (this.exports.DocxSessionBridge.Undo(this.handle))
-            this.remount();
+            this.reconcile();
     }
-    /** Redo the last undone edit (re-renders the document). */
+    /** Redo the last undone edit (incremental repaint; falls back to a full re-render). */
     redo() {
         if (this.closed)
             return;
         if (this.exports.DocxSessionBridge.Redo(this.handle))
-            this.remount();
+            this.reconcile();
+    }
+    // ─── 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;
+        }
+        // No band block focused — target the footer, where page numbers overwhelmingly live.
+        this.region.insertPageNumberInBand("footer", field);
+    }
+    /**
+     * Set the page numbering of the section the bands describe (`w:pgNumType`) — Word's *Format Page
+     * Numbers…*: `start` restarts numbering at that number, `format` chooses `1, 2, 3` vs
+     * `i, ii, iii` etc. Omitted fields are left unchanged. Requires the header/footer region
+     * (`{ headerFooter: true }`); a no-op otherwise.
+     *
+     * Inserted page-number fields are plain, so they render through this. The editor's own view still
+     * shows each field's cached result — Word recomputes on open — but `{ paginated: true }`
+     * substitutes the real per-page number and so reflects the change immediately.
+     */
+    setPageNumbering(op) {
+        this.assertOpen();
+        this.region?.setPageNumbering(op);
+    }
+    /** Remove the section's page-numbering start/format: it reverts to continuing the previous
+     *  section's numbering in Word's default `1, 2, 3`. */
+    clearPageNumbering() {
+        this.assertOpen();
+        this.region?.clearPageNumbering();
+    }
+    /** This section's page numbering as the document currently states it — `{}` when the section
+     *  sets neither (it continues the previous section in the default format). */
+    pageNumbering() {
+        return this.region?.pageNumbering() ?? {};
     }
     /** Which inline formats the current selection carries — for ribbon button highlighting. */
     queryFormatState() {
@@ -1452,17 +1795,27 @@ export class DocxEditor {
     }
     /** 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);
+        // A band block resolves through its stamped `data-hf-anchor`, never the unid map — and its
+        // unid can collide with another part's, so writing it here would corrupt that entry.
+        if (!inBand) {
+            this.unidToFullId.delete(oldUnid);
+            this.unidToFullId.set(newUnid, anchorId);
+        }
+        // Stamp BEFORE wiring so wireBlock's own resolution sees the authoritative id.
+        if (inBand)
+            this.region.adoptBlock(fresh, anchorId);
         this.wireBlock(fresh);
         this.activeBlock = fresh;
+        // The throwaway render numbers citation markers from 1 — repair in place.
+        this.maybeRenumberNotes(fresh);
         this.options.onEdit?.({ anchorId, unid: newUnid });
         return fresh;
     }
@@ -1480,15 +1833,21 @@ export class DocxEditor {
             if (html.charCodeAt(0) !== 0x7b /* not an error object */)
                 return html;
         }
-        const bytes = bridge.Save(this.handle);
+        // Fallback only (no RenderHtml on this bridge, or it errored). These bytes are re-rendered and
+        // discarded, and the re-render has to resolve to the SAME anchors the live session holds — a
+        // content change re-derives a block's content-hashed unid, which would leave it unwired. So ask
+        // for the Unid-bearing save here, and here only; DocxEditor.save() stays clean.
+        const bytes = typeof bridge.SaveWithAnchorIds === "function"
+            ? bridge.SaveWithAnchorIds(this.handle)
+            : bridge.Save(this.handle);
         return this.exports.DocumentConverter.ConvertDocxToHtmlComplete(...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
@@ -1498,6 +1857,426 @@ export class DocxEditor {
     affectsList(res) {
         return [...(res.modified ?? []), ...(res.created ?? [])].some((r) => r.kind === "li");
     }
+    // ─── Incremental structural reconcile ─────────────────────────────────
+    //
+    // After a structural op (insert table/row/col, footnote, delete block, undo/redo)
+    // the DOM is patched from a unit-sequence diff against the session's render plan
+    // instead of remounting the whole document (~3 s of full-document conversion on a
+    // 350-block file). Full remount remains the universal FALLBACK: any ambiguity,
+    // unsupported bridge, paginated mode, list-membership change, or thrown error
+    // lands there — correctness never depends on the diff being right.
+    /** True when the bridge carries the reconcile trio and the mode allows patching. */
+    canReconcile() {
+        const b = this.exports.DocxSessionBridge;
+        return (!this.options.paginated &&
+            typeof b.ListBlocks === "function" &&
+            typeof b.RenderBlocksHtml === "function" &&
+            typeof b.ListNotes === "function");
+    }
+    /** The body's top-level unit nodes in document order: `[data-anchor]` elements not
+     *  nested in another unit (cell paragraphs collapse into their table) and not in the
+     *  notes sections. */
+    bodyUnitNodes() {
+        const all = Array.from(this.editRoot.querySelectorAll("[data-anchor]"));
+        return all.filter((el) => {
+            if (el.closest("section.footnotes, section.endnotes"))
+                return false;
+            const ancestor = el.parentElement?.closest("[data-anchor]");
+            return !(ancestor && this.editRoot.contains(ancestor));
+        });
+    }
+    /** The DOM diff token for a body unit node (see editor-reconcile.tokenOf). */
+    static domTokenOf(el) {
+        const unid = el.getAttribute("data-anchor") ?? "";
+        const sig = el.getAttribute("data-render-sig");
+        return sig ? `${unid}|${sig}` : unid;
+    }
+    /** The kind a body unit node would have in the plan (only 'li'/'tbl' matter to the
+     *  remount guard). */
+    static domKindOf(el) {
+        if (el.tagName === "TABLE")
+            return "tbl";
+        return el.querySelector(":scope > [data-list-marker]") ? "li" : "p";
+    }
+    static listMarkerText(el) {
+        const m = el?.querySelector(":scope > [data-list-marker]");
+        return m ? m.textContent : null;
+    }
+    /**
+     * Incrementally patch the DOM from the session's render plan; falls back to
+     * {@link remount} whenever it cannot prove the patch correct. Same focus contract
+     * as remount.
+     */
+    reconcile(focusIndex = -1, caretAtEnd = false) {
+        if (!this.canReconcile()) {
+            this.remount(focusIndex, caretAtEnd);
+            return;
+        }
+        try {
+            if (!this.reconcileCore()) {
+                this.remount(focusIndex, caretAtEnd);
+                return;
+            }
+        }
+        catch (err) {
+            this.lastReconcileFallback = `threw: ${err instanceof Error ? err.message : String(err)}`;
+            this.remount(focusIndex, caretAtEnd);
+            return;
+        }
+        if (focusIndex >= 0) {
+            const blocks = this.editableList();
+            const target = blocks[Math.min(focusIndex, blocks.length - 1)];
+            if (target) {
+                this.activeBlock = target;
+                placeCaretAtOffset(target, caretAtEnd ? (target.textContent ?? "").length : 0);
+            }
+        }
+        this.syncRegionToBody(this.activeBlock ?? undefined);
+    }
+    /** The patch itself. Returns false to request the remount fallback. */
+    reconcileCore() {
+        const bridge = this.exports.DocxSessionBridge;
+        // Refresh the unid → anchor map FIRST: wiring freshly rendered nodes (wireBlock)
+        // resolves through it, and the map must reflect the post-op session.
+        this.refreshAnchorMap();
+        const plan = JSON.parse(bridge.ListBlocks(this.handle));
+        if (plan.error)
+            return this.bail(`plan error: ${plan.error}`);
+        const oldNodes = this.bodyUnitNodes();
+        const oldTokens = oldNodes.map(DocxEditor.domTokenOf);
+        const oldKinds = oldNodes.map(DocxEditor.domKindOf);
+        const bodyDiff = diffUnits(oldTokens, plan.body);
+        if (needsRemount(bodyDiff, plan.body, oldKinds))
+            return this.bail("needsRemount (li change or churn)");
+        const fnState = this.notesDiff("footnotes", plan.footnotes);
+        const enState = this.notesDiff("endnotes", plan.endnotes);
+        if (fnState === null || enState === null)
+            return this.bail("notes container unstampable/missing");
+        // One batch render for everything that needs fresh HTML.
+        const addedBodyIds = bodyDiff.added.map((j) => plan.body[j].id);
+        const addedNoteIds = fnState.diff.added
+            .map((j) => plan.footnotes[j].id)
+            .concat(enState.diff.added.map((j) => plan.endnotes[j].id));
+        const allIds = addedBodyIds.concat(addedNoteIds);
+        let rendered = {};
+        if (allIds.length > 0) {
+            rendered = JSON.parse(bridge.RenderBlocksHtml(this.handle, JSON.stringify(allIds), this.options.cssPrefix, this.options.fabricateClasses));
+            if (rendered.error)
+                return this.bail(`render error: ${rendered.error}`);
+            for (const id of allIds)
+                if (!rendered[id])
+                    return this.bail(`unrenderable: ${id}`);
+        }
+        // A substituted list item may only swap in place if its rendered marker matches
+        // the old node's — a marker change (level/membership/numbering) means sibling
+        // numbers shifted too, which only a remount repaints.
+        const parse = (html) => {
+            const el = new DOMParser().parseFromString(html, "text/html").body
+                .firstElementChild;
+            // Per-block converter output carries the XHTML xmlns; a full render only has it
+            // on the document root, so drop it to keep reconciled DOM ≡ remounted DOM.
+            el?.removeAttribute("xmlns");
+            return el;
+        };
+        const freshBody = new Map();
+        for (const j of bodyDiff.added) {
+            const el = parse(rendered[plan.body[j].id]);
+            if (!el)
+                return this.bail(`unparseable render: ${plan.body[j].id}`);
+            freshBody.set(j, el);
+        }
+        for (const { oldIndex, newIndex } of bodyDiff.substituted) {
+            const freshRoot = freshBody.get(newIndex);
+            const oldMarker = DocxEditor.listMarkerText(oldNodes[oldIndex]);
+            const newMarker = DocxEditor.listMarkerText(freshRoot ? DocxEditor.anchorElOf(freshRoot) : null);
+            if (oldMarker !== newMarker)
+                return this.bail("substituted li marker drift");
+        }
+        if (!this.applyBodyDiff(oldNodes, plan.body, bodyDiff, freshBody))
+            return this.bail("applyBodyDiff bail");
+        this.applyNotesDiff("footnotes", plan.footnotes, fnState, rendered);
+        this.applyNotesDiff("endnotes", plan.endnotes, enState, rendered);
+        // Note chrome (marker sup text / hrefs / li values) is position-derived and NOT
+        // covered by the unit diff — renumber whenever notes changed or any fresh body
+        // node carries a citation marker.
+        const freshHasMarker = [...freshBody.values()].some((el) => el.querySelector("a.footnote-ref, a.endnote-ref"));
+        if (fnState.diff.added.length + fnState.diff.removed.length > 0 || freshHasMarker)
+            this.renumberNoteChrome("footnote");
+        if (enState.diff.added.length + enState.diff.removed.length > 0 || freshHasMarker)
+            this.renumberNoteChrome("endnote");
+        this.lastReconcileFallback = null;
+        return true;
+    }
+    bail(reason) {
+        this.lastReconcileFallback = reason;
+        return false;
+    }
+    /** The generated single-child wrapper chain around a unit node (a table's alignment
+     *  <div>). Climbs while the parent is an anchor-less DIV whose ONLY element child is
+     *  the current node — never a section div (multi-child) or the edit root. */
+    unitWrapperOf(el) {
+        let n = el;
+        while (n.parentElement &&
+            n.parentElement !== this.editRoot &&
+            n.parentElement.tagName === "DIV" &&
+            !n.parentElement.hasAttribute("data-anchor") &&
+            n.parentElement.childElementCount === 1) {
+            n = n.parentElement;
+        }
+        return n;
+    }
+    /** The `[data-anchor]` element of a fresh render root (the root itself for a leaf
+     *  block, its descendant for a wrapper-shaped render like a table's align div). */
+    static anchorElOf(root) {
+        return root.hasAttribute("data-anchor")
+            ? root
+            : root.querySelector("[data-anchor]");
+    }
+    /** Insert/remove/swap body unit nodes per the diff. Returns false to bail (parent
+     *  ambiguity, order violation, wrapper semantics) — the session is already correct,
+     *  so bailing just means a full repaint. */
+    applyBodyDiff(oldNodes, units, diff, fresh) {
+        // Kept nodes must appear in increasing old order (no move support in v1).
+        let lastOld = -1;
+        for (let j = 0; j < units.length; j++) {
+            const oi = diff.keep.get(j);
+            if (oi === undefined)
+                continue;
+            if (oi < lastOld)
+                return false;
+            lastOld = oi;
+        }
+        // In-place substitutions first: replace at WRAPPER level so a table swaps with its
+        // alignment div. A LEAF render replacing a wrapped node would break the wrapper's
+        // semantics (border <div> grouping) — that is remount territory.
+        const subOldByNew = new Map(diff.substituted.map((s) => [s.newIndex, s.oldIndex]));
+        for (const [nj, oi] of subOldByNew) {
+            const freshRoot = fresh.get(nj);
+            const oldWrapper = this.unitWrapperOf(oldNodes[oi]);
+            if (!freshRoot.hasAttribute("data-anchor")) {
+                oldWrapper.replaceWith(freshRoot); // wrapper-shaped render (table) ⇄ wrapper
+            }
+            else if (oldWrapper === oldNodes[oi]) {
+                oldNodes[oi].replaceWith(freshRoot);
+            }
+            else {
+                return false; // leaf render into a wrapped slot — border-div semantics, remount
+            }
+            this.wireUnit(freshRoot, units[nj]);
+        }
+        // Pure inserts against kept/substituted neighbors (at wrapper level).
+        const pureAdded = diff.added.filter((j) => !subOldByNew.has(j));
+        const pureRemoved = diff.removed.filter((i) => !diff.substituted.some((s) => s.oldIndex === i));
+        const nodeAt = (j) => {
+            const oi = diff.keep.get(j);
+            if (oi !== undefined)
+                return oldNodes[oi];
+            if (subOldByNew.has(j))
+                return fresh.get(j);
+            const f = fresh.get(j);
+            return f && f.isConnected ? f : null;
+        };
+        for (const j of pureAdded) {
+            const el = fresh.get(j);
+            let prev = null;
+            for (let k = j - 1; k >= 0 && !prev; k--)
+                prev = nodeAt(k);
+            let next = null;
+            for (let k = j + 1; k < units.length && !next; k++) {
+                const oi = diff.keep.get(k);
+                if (oi !== undefined)
+                    next = oldNodes[oi];
+                else if (subOldByNew.has(k))
+                    next = fresh.get(k);
+            }
+            const prevW = prev ? this.unitWrapperOf(prev) : null;
+            const nextW = next ? this.unitWrapperOf(next) : null;
+            if (prevW && nextW && prevW.parentElement !== nextW.parentElement)
+                return false;
+            if (prevW)
+                prevW.after(el);
+            else if (nextW)
+                nextW.before(el);
+            else
+                return false; // empty container — nowhere provably correct to insert
+            this.wireUnit(el, units[j]);
+        }
+        // Pure removals last, taking now-empty generated wrappers with them.
+        for (const i of pureRemoved) {
+            const wrapper = this.unitWrapperOf(oldNodes[i]);
+            wrapper.remove();
+        }
+        return true;
+    }
+    /** Wire a freshly rendered unit root (and its nested blocks) and stamp the unit's
+     *  content signature on its `[data-anchor]` element — the element the next
+     *  reconcile's DOM walk reads tokens from. */
+    wireUnit(root, unit) {
+        const anchorEl = DocxEditor.anchorElOf(root);
+        if (anchorEl && unit.sig)
+            anchorEl.setAttribute("data-render-sig", unit.sig);
+        if (anchorEl)
+            this.wireBlock(anchorEl);
+        root.querySelectorAll("[data-anchor]").forEach((b) => this.wireBlock(b));
+    }
+    /** Old-sequence diff state for one notes section. `null` requests remount (DOM not
+     *  stampable/consistent). */
+    notesDiff(sectionClass, units) {
+        const ol = this.editRoot.querySelector(`section.${sectionClass} > ol`);
+        const lis = ol ? Array.from(ol.children).filter((c) => c.tagName === "LI") : [];
+        if (units.length === 0 && lis.length === 0)
+            return { lis, diff: diffUnits([], []) };
+        // A document that gains its FIRST note has no section to patch — remount builds it.
+        if (!ol)
+            return null;
+        const tokens = [];
+        for (const li of lis) {
+            const unid = li.getAttribute("data-note-anchor");
+            if (!unid)
+                return null; // unstamped DOM (older mount) — remount restamps
+            const sig = li.getAttribute("data-render-sig");
+            tokens.push(sig ? `${unid}|${sig}` : unid);
+        }
+        return { lis, diff: diffUnits(tokens, units) };
+    }
+    /** Apply a notes-section diff: rebuild the `<ol>`'s li list, preserving kept nodes. */
+    applyNotesDiff(sectionClass, units, state, rendered) {
+        if (state.diff.added.length === 0 && state.diff.removed.length === 0)
+            return;
+        // Removing the LAST note removes the whole section — a full render emits no
+        // section for a document without notes, and equivalence with remount is the pin.
+        if (units.length === 0) {
+            this.editRoot.querySelector(`section.${sectionClass}`)?.remove();
+            return;
+        }
+        const ol = this.editRoot.querySelector(`section.${sectionClass} > ol`);
+        const prefix = sectionClass === "footnotes" ? "fn" : "en";
+        const nodes = [];
+        for (let j = 0; j < units.length; j++) {
+            const oi = state.diff.keep.get(j);
+            if (oi !== undefined) {
+                nodes.push(state.lis[oi]);
+                continue;
+            }
+            nodes.push(this.buildNoteLi(prefix, units[j], rendered[units[j].id]));
+        }
+        ol.replaceChildren(...nodes);
+    }
+    /** Build a notes-section `<li>` for a freshly rendered note — replicating the
+     *  converter's chrome (id/value are re-stamped by the renumber pass; the backref
+     *  goes inside the last paragraph, matching RenderFootnoteItem). */
+    buildNoteLi(prefix, unit, html) {
+        const li = document.createElement("li");
+        li.setAttribute("data-note-anchor", unidOf(unit.id));
+        if (unit.sig)
+            li.setAttribute("data-render-sig", unit.sig);
+        li.innerHTML = html;
+        const paras = li.querySelectorAll(":scope > p");
+        const last = paras[paras.length - 1];
+        if (last) {
+            const backref = document.createElement("a");
+            backref.setAttribute("class", `${prefix}-backref`);
+            backref.setAttribute("contenteditable", "false");
+            backref.textContent = "↩";
+            last.append(" ", backref);
+        }
+        li.querySelectorAll("[data-anchor]").forEach((b) => this.wireBlock(b));
+        return li;
+    }
+    /**
+     * Rewrite position-derived note chrome from the session's citation-ordered note
+     * list: the k-th marker in document order IS note k (ids ascend in reference
+     * order), so marker sup text, hrefs/ids, li ids/values and backref hrefs are all
+     * re-derived positionally. Pure attribute/text patching of generated chrome.
+     */
+    renumberNoteChrome(kind) {
+        const bridge = this.exports.DocxSessionBridge;
+        if (typeof bridge.ListNotes !== "function")
+            return;
+        const prefix = kind === "footnote" ? "fn" : "en";
+        let notes;
+        try {
+            notes = JSON.parse(bridge.ListNotes(this.handle, kind === "endnote"));
+        }
+        catch {
+            return;
+        }
+        if (!Array.isArray(notes))
+            return;
+        const markers = Array.from(this.editRoot.querySelectorAll(`a.${kind}-ref`)).filter((a) => !a.closest("section.footnotes, section.endnotes"));
+        markers.forEach((a, k) => {
+            const n = notes[k];
+            if (!n)
+                return;
+            a.setAttribute("href", `#${prefix}-${n.id}`);
+            a.id = `${prefix}-ref-${n.id}`;
+            if (kind === "footnote")
+                a.setAttribute("data-footnote-id", n.id);
+            const sup = a.querySelector("sup");
+            if (sup)
+                sup.textContent = String(n.ordinal);
+        });
+        // Match list items by their stamped note anchor, NOT position: the section can
+        // hold rendered-but-never-cited notes (Word's continuationNotice) that ListNotes
+        // — a citation walk — does not list; positional pairing would relabel them.
+        const byUnid = new Map(notes.map((n) => [unidOf(n.defAnchorId), n]));
+        const lis = this.editRoot.querySelectorAll(`section.${kind}s > ol > li`);
+        lis.forEach((li) => {
+            const unid = li.getAttribute("data-note-anchor");
+            const n = unid ? byUnid.get(unid) : undefined;
+            if (!n)
+                return;
+            li.id = `${prefix}-${n.id}`;
+            li.setAttribute("value", String(n.ordinal));
+            li.querySelectorAll(`a.${prefix}-backref`).forEach((b) => b.setAttribute("href", `#${prefix}-ref-${n.id}`));
+        });
+    }
+    /** After an incremental block swap, stale marker chrome in the swapped node (the
+     *  throwaway render numbers citations from 1) is repaired in place. */
+    maybeRenumberNotes(fresh) {
+        if (fresh.querySelector("a.footnote-ref"))
+            this.renumberNoteChrome("footnote");
+        if (fresh.querySelector("a.endnote-ref"))
+            this.renumberNoteChrome("endnote");
+    }
+    /** Stamp the DOM state the reconciler diffs against: container signatures on body
+     *  tables and `data-note-anchor` + signature on notes-section items. Called after
+     *  every full mount; reconcile stamps its own insertions. */
+    stampPlanState() {
+        const bridge = this.exports.DocxSessionBridge;
+        if (typeof bridge.ListBlocks !== "function")
+            return;
+        try {
+            const plan = JSON.parse(bridge.ListBlocks(this.handle));
+            if (plan.error)
+                return;
+            // Positional pairing: a fresh full mount renders exactly the plan's units in
+            // order (verified invariant). On any mismatch, leave unstamped — an unstamped
+            // unit just diffs as changed and re-renders once.
+            const nodes = this.bodyUnitNodes();
+            if (nodes.length === plan.body.length) {
+                nodes.forEach((el, k) => {
+                    if (plan.body[k].sig && el.getAttribute("data-anchor") === unidOf(plan.body[k].id))
+                        el.setAttribute("data-render-sig", plan.body[k].sig);
+                });
+            }
+            const stampNotes = (sectionClass, units) => {
+                const lis = this.editRoot.querySelectorAll(`section.${sectionClass} > ol > li`);
+                if (lis.length !== units.length)
+                    return; // inconsistent — leave unstamped (reconcile will remount)
+                lis.forEach((li, k) => {
+                    li.setAttribute("data-note-anchor", unidOf(units[k].id));
+                    if (units[k].sig)
+                        li.setAttribute("data-render-sig", units[k].sig);
+                });
+            };
+            stampNotes("footnotes", plan.footnotes);
+            stampNotes("endnotes", plan.endnotes);
+        }
+        catch {
+            /* stamping is best-effort; unstamped DOM just falls back to remount */
+        }
+    }
     /**
      * Full re-render from current session state (after undo/redo, and after list edits where
      * single-block rendering can't compute numbering). Optionally focus the editable block at
@@ -1520,6 +2299,9 @@ export class DocxEditor {
                 placeCaretAtOffset(target, caretAtEnd ? (target.textContent ?? "").length : 0);
             }
         }
+        // A remount rebuilds the body from the live session; re-resolve the section so undo/redo of a
+        // section-affecting edit (or a pagination toggle) leaves the bands describing the right one.
+        this.syncRegionToBody(this.activeBlock ?? undefined);
     }
 }
 //# sourceMappingURL=editor.js.map