docxodus 8.0.0 → 9.0.0

package/dist/editor.js

@@ -18,6 +18,7 @@
  */
 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")
@@ -31,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 ?? "";
@@ -112,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;
     }
@@ -425,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,
     ];
 }
@@ -453,6 +474,9 @@ export class DocxEditor {
         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)
@@ -508,15 +532,21 @@ export class DocxEditor {
     /**
      * 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.
+     * 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) {
+    refreshAfter(block, focusIndex, caretAtEnd = false, forceRemount = false) {
         const band = this.region?.bandOf(block);
         if (band) {
             this.region.refresh(this.region.whichOf(band));
             return;
         }
-        this.remount(focusIndex, caretAtEnd);
+        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 = {}) {
@@ -529,11 +559,13 @@ export class DocxEditor {
             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)
@@ -601,7 +633,14 @@ export class DocxEditor {
      * 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)) {
@@ -669,6 +708,7 @@ export class DocxEditor {
             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.
@@ -680,6 +720,7 @@ export class DocxEditor {
         this.editRoot = flow;
         if (this.options.editable)
             this.wireBlocks(flow);
+        this.stampPlanState();
         this.dockBands(flow);
     }
     /** Paginated mount: flow blocks into page boxes via pagination.ts, wire the page clones. */
@@ -733,9 +774,11 @@ export class DocxEditor {
         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);
@@ -834,6 +877,8 @@ export class DocxEditor {
                 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 });
@@ -1399,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.refreshAfter(block, 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
@@ -1494,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.refreshAfter(block, 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) {
@@ -1528,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.refreshAfter(block, 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`;
@@ -1564,6 +1610,48 @@ export class DocxEditor {
             return;
         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;
         if (this.closed || !block)
@@ -1588,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.refreshAfter(block, idx, false);
+            this.refreshAfter(block, idx, false, true);
             return;
         }
         this.swapBlock(block, unid, res.modified?.[0])?.focus();
@@ -1615,24 +1703,24 @@ export class DocxEditor {
         if (!res.success)
             return;
         if (this.affectsList(res)) {
-            this.refreshAfter(block, 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) ───────────────
     /**
@@ -1667,6 +1755,31 @@ export class DocxEditor {
         // 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() {
         const block = this.activeBlock ?? this.editRoot;
@@ -1701,6 +1814,8 @@ export class DocxEditor {
             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;
     }
@@ -1718,7 +1833,13 @@ 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 BODY blocks in document order (band blocks are enumerated by `ownerRoot`). */
@@ -1736,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