docxodus 9.2.0 → 9.4.0

package/dist/editor.js

@@ -18,8 +18,54 @@
  */
 import { paginateHtml } from "./pagination.js";
 import { HeaderFooterRegion } from "./editor-headerfooter.js";
+import { draggable, dropTargetForElements, monitorForElements, } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
+import { autoScrollForElements, autoScrollWindowForElements, } from "@atlaskit/pragmatic-drag-and-drop-auto-scroll/element";
+import { TrackedChangeMode } from "./types.js";
 import { diffUnits, needsRemount, unidOf } from "./editor-reconcile.js";
 const EDITABLE_TAGS = new Set(["P", "H1", "H2", "H3", "H4", "H5", "H6"]);
+const BLOCK_DRAG_TYPE = "docxodus-block";
+const blockDragStyledDocuments = new WeakSet();
+function ensureBlockDragStyles(doc) {
+    if (blockDragStyledDocuments.has(doc))
+        return;
+    blockDragStyledDocuments.add(doc);
+    const style = doc.createElement("style");
+    style.dataset.docxodusBlockDrag = "true";
+    style.textContent = `
+.docx-block-handle {
+  position: fixed; z-index: 2147483000; display: none; width: 26px; height: 28px;
+  align-items: center; justify-content: center; padding: 0; border: 1px solid #d0d5dd;
+  border-radius: 6px; background: #fff; color: #667085; box-shadow: 0 1px 3px rgba(16,24,40,.12);
+  cursor: grab; font: 700 17px/1 system-ui, sans-serif; user-select: none; touch-action: none;
+}
+.docx-block-handle:hover, .docx-block-handle:focus-visible { color: #344054; border-color: #98a2b3; outline: none; }
+.docx-block-handle[aria-pressed="true"] { color: #175cd3; border-color: #84adff; background: #eff8ff; }
+.docx-block-handle.docx-block-dragging { cursor: grabbing; opacity: .78; }
+.docx-block-drop-indicator {
+  position: fixed; z-index: 2147482999; display: none; height: 3px; pointer-events: none;
+  border-radius: 999px; background: #2e90fa; box-shadow: 0 0 0 1px rgba(255,255,255,.85);
+}
+.docx-block-move-menu {
+  position: fixed; z-index: 2147483001; display: none; min-width: 150px; padding: 5px;
+  border: 1px solid #d0d5dd; border-radius: 8px; background: #fff;
+  box-shadow: 0 8px 24px rgba(16,24,40,.18); font: 13px/1.35 system-ui, sans-serif;
+}
+.docx-block-move-menu button { display: block; width: 100%; padding: 7px 9px; border: 0; border-radius: 5px; background: transparent; color: #344054; text-align: left; }
+.docx-block-move-menu button:hover, .docx-block-move-menu button:focus-visible { background: #f2f4f7; outline: none; }
+.docx-block-move-menu button:disabled { color: #98a2b3; background: transparent; }
+.docx-block-move-flash { animation: docx-block-move-flash 800ms ease-out; }
+@keyframes docx-block-move-flash { from { box-shadow: 0 0 0 3px rgba(46,144,250,.55); } to { box-shadow: none; } }
+.docx-block-live-region { position: fixed; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+`;
+    (doc.head ?? doc.documentElement).appendChild(style);
+}
+function trackedChangeWireName(mode) {
+    if (mode === TrackedChangeMode.RenderInline)
+        return "render_inline";
+    if (mode === TrackedChangeMode.StripDeletions)
+        return "strip_deletions";
+    return "accept";
+}
 function fontWeightIsBold(w) {
     if (w === "bold" || w === "bolder")
         return true;
@@ -480,7 +526,7 @@ function selectionHasFormat(key, fallback) {
     }
 }
 /** Build the full ConvertDocxToHtmlComplete arg list (stampAnchors = last arg). */
-function completeArgs(bytes, cssPrefix, fabricate, paginated, scale) {
+function completeArgs(bytes, cssPrefix, fabricate, paginated, scale, renderTrackedChanges) {
     return [
         bytes, "Document", cssPrefix, fabricate, "", -1, "comment-",
         /* paginationMode */ paginated ? 1 : 0, /* paginationScale */ scale, "page-",
@@ -489,7 +535,7 @@ function completeArgs(bytes, cssPrefix, fabricate, paginated, scale) {
         // 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,
+        renderTrackedChanges, true, true, false, null, /* stampAnchors */ true,
     ];
 }
 export class DocxEditor {
@@ -506,6 +552,27 @@ export class DocxEditor {
          * structural edit (split/merge/format) is lost. While this flag is set, commitBlock no-ops.
          */
         this.replacing = false;
+        /** Editor-owned block-move chrome. It is deliberately outside the rendered unit tree. */
+        this.blockDragHandle = null;
+        this.blockDropIndicator = null;
+        this.blockMoveMenu = null;
+        this.blockMoveLive = null;
+        this.blockDragSource = null;
+        this.blockDragCleanup = [];
+        this.blockDragTargetCleanup = [];
+        this.blockDragging = false;
+        this.blockDragPointerDown = false;
+        /** Anchors the current drag source may legally move next to, per the engine's own rules.
+         *  Null when the bridge predates ValidMoveTargets — then every block is offered, as before. */
+        this.blockMoveTargets = null;
+        /** Memoized `ValidMoveTargets` answers, keyed by source anchor and dropped whenever an edit
+         *  lands. The legal-target set is a property of the document, so hovering back and forth over
+         *  the same blocks between edits must not re-ask the engine. */
+        this.blockMoveTargetCache = new Map();
+        /** Cancels the pending idle prefetch of the hovered block's targets — see `showBlockHandle`. */
+        this.blockMoveTargetPrefetch = null;
+        /** Why the last move was refused, verbatim from the engine — diagnostics, not announcement copy. */
+        this.lastMoveError = null;
         /**
          * The last real (non-collapsed) text selection inside an editable block. A toolbar control that
          * must take focus to be used — the font-size combobox — blurs the block and collapses the live
@@ -724,7 +791,11 @@ export class DocxEditor {
             paginated: options.paginated ?? false,
             scale: options.scale ?? 1,
             headerFooter: options.headerFooter ?? false,
+            blockDrag: options.blockDrag ?? false,
+            trackedChanges: options.trackedChanges ?? TrackedChangeMode.Accept,
+            revisionAuthor: options.revisionAuthor ?? "docxodus",
             onEdit: options.onEdit,
+            onMove: options.onMove,
         };
         // 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
@@ -732,17 +803,22 @@ export class DocxEditor {
         // 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 handle = exports.DocxSessionBridge.OpenSession(bytes, JSON.stringify({
+            emitMarkdownPatch: false,
+            trackedChanges: trackedChangeWireName(opts.trackedChanges),
+            revisionAuthor: opts.revisionAuthor,
+        }));
         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));
+        const fullHtml = exports.DocumentConverter.ConvertDocxToHtmlComplete(...completeArgs(bytes, opts.cssPrefix, opts.fabricateClasses, opts.paginated, opts.scale, opts.trackedChanges === TrackedChangeMode.RenderInline));
         if (opts.paginated)
             editor.mountPaginated(fullHtml);
         else
             editor.mountHtml(fullHtml);
         editor.syncRegionToBody();
+        editor.setupBlockDrag();
         return editor;
     }
     /**
@@ -770,6 +846,7 @@ export class DocxEditor {
             document.removeEventListener("mouseup", this.onMouseUp, true);
         }
         this.clearDragSelection();
+        this.teardownBlockDrag();
         this.exports.DocxSessionBridge.CloseSession(this.handle);
     }
     /**
@@ -798,6 +875,522 @@ export class DocxEditor {
     get sessionHandle() {
         return this.handle;
     }
+    /** Move one top-level body block relative to another and repaint from the live session. */
+    moveBlock(sourceAnchorId, targetAnchorId, position) {
+        this.assertOpen();
+        const bridge = this.exports.DocxSessionBridge;
+        if (typeof bridge.MoveBlock !== "function")
+            return false;
+        const res = this.parseEdit(bridge.MoveBlock(this.handle, sourceAnchorId, targetAnchorId, position));
+        if (!res.success) {
+            // The engine's message names an OOXML construct ("a section-break paragraph"); the live
+            // region is read aloud, so announce the outcome and keep the raw reason for debugging.
+            this.lastMoveError = res.error?.message ?? null;
+            this.announceBlockMove("This block cannot be moved there.");
+            return false;
+        }
+        if ((res.created?.length ?? 0) === 0 &&
+            (res.modified?.length ?? 0) === 0 &&
+            (res.removed?.length ?? 0) === 0) {
+            this.announceBlockMove("The block is already in that position.");
+            return true;
+        }
+        const destination = res.created?.[0] ?? res.modified?.[0];
+        // Both modes reconcile. A direct move relocates the existing element, so the reconciler moves
+        // the exact DOM node it already has. Review rendering additionally rewrites the SOURCE in
+        // place — it becomes the move-from half — and that is visible to the diff because the plan
+        // signs every unit with a content hash, so the source diffs as an in-place substitution.
+        // This used to remount, which on a real charter is seconds for a one-block change.
+        this.reconcile();
+        const moved = destination
+            ? this.bodyUnitNodes().find((el) => el.getAttribute("data-anchor") === destination.unid)
+            : null;
+        if (moved) {
+            moved.classList.add("docx-block-move-flash");
+            moved.addEventListener("animationend", () => moved.classList.remove("docx-block-move-flash"), {
+                once: true,
+            });
+            const focusTarget = EDITABLE_TAGS.has(moved.tagName)
+                ? moved
+                : moved.querySelector('[data-anchor][contenteditable="true"]');
+            if (focusTarget) {
+                this.activeBlock = focusTarget;
+                focusTarget.focus({ preventScroll: true });
+            }
+        }
+        this.options.onMove?.({
+            sourceAnchorId,
+            destinationAnchorId: destination?.id ?? sourceAnchorId,
+        });
+        this.announceBlockMove("Block moved.");
+        return true;
+    }
+    /** Resolve any rendered descendant to its top-level body move unit (tables stay whole). */
+    blockUnitOf(target) {
+        const node = target instanceof Node ? target : null;
+        const el = node?.nodeType === Node.ELEMENT_NODE
+            ? node
+            : node?.parentElement;
+        if (!el || !this.editRoot.contains(el))
+            return null;
+        // Climb rather than scan: this runs on every pointer move over the document, and listing
+        // every anchored node to find the one containing the pointer is linear in the document.
+        let unit = null;
+        for (let candidate = el.closest("[data-anchor]"); candidate && this.editRoot.contains(candidate); candidate = candidate.parentElement?.closest("[data-anchor]") ?? null) {
+            unit = candidate;
+        }
+        if (!unit || unit.closest("section.footnotes, section.endnotes"))
+            return null;
+        return unit;
+    }
+    isMovableBlockUnit(unit) {
+        if (!unit || !this.anchorIdOf(unit))
+            return false;
+        // A source representation of an existing tracked move/deletion is evidence, not a new
+        // editable block. Its accepted counterpart remains draggable.
+        if (unit.matches("[class$='row-del'], [class*='row-del ']") ||
+            unit.querySelector("tr[class$='row-del'], tr[class*='row-del '], del[class$='move-from'], del[class*='move-from ']"))
+            return false;
+        return unit.tagName === "TABLE" || EDITABLE_TAGS.has(unit.tagName);
+    }
+    currentBlockDragSource() {
+        if (this.isMovableBlockUnit(this.blockDragSource) && this.blockDragSource.isConnected)
+            return this.blockDragSource;
+        const fromActive = this.blockUnitOf(this.activeBlock);
+        if (this.isMovableBlockUnit(fromActive)) {
+            this.blockDragSource = fromActive;
+            return fromActive;
+        }
+        return null;
+    }
+    showBlockHandle(unit) {
+        const handle = this.blockDragHandle;
+        if (!handle || !this.isMovableBlockUnit(unit))
+            return;
+        const changed = unit !== this.blockDragSource;
+        this.blockDragSource = unit;
+        // A block the engine will not move anywhere — one owning a section break, or already carrying
+        // revision markup a tracked move would have to re-wrap — gets no handle rather than a handle
+        // that always fails. Asking costs an engine round trip, so hovering only ever CONSUMES a
+        // cached answer and schedules the ask for idle time; the drag start and the menu ask for
+        // real. Merely moving the pointer across the document must not run document-scale work.
+        const known = this.blockMoveTargetsFor(unit, { cachedOnly: true });
+        if (known?.size === 0) {
+            handle.style.display = "none";
+            return;
+        }
+        if (changed && known === undefined)
+            this.prefetchBlockMoveTargets(unit);
+        const rect = unit.getBoundingClientRect();
+        handle.style.display = "flex";
+        handle.style.left = `${Math.max(4, rect.left - 32)}px`;
+        handle.style.top = `${Math.max(4, rect.top + (unit.tagName === "TABLE" ? 6 : Math.max(0, (rect.height - 28) / 2)))}px`;
+        const preview = (unit.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 48);
+        handle.setAttribute("aria-label", preview ? `Move block: ${preview}` : "Move block");
+        // Drop targets are registered when a drag actually begins (and once at mount), not on
+        // hover: re-registering one listener per body block every time the pointer crosses a
+        // paragraph boundary is work no drop can use.
+    }
+    hideBlockHandle() {
+        if (this.blockDragging || this.blockMoveMenu?.style.display === "block")
+            return;
+        if (this.blockDragHandle)
+            this.blockDragHandle.style.display = "none";
+    }
+    positionBlockHandle() {
+        const source = this.currentBlockDragSource();
+        if (source && this.blockDragHandle?.style.display !== "none")
+            this.showBlockHandle(source);
+    }
+    showDropIndicator(target, position) {
+        const indicator = this.blockDropIndicator;
+        if (!indicator)
+            return;
+        const rect = this.unitWrapperOf(target).getBoundingClientRect();
+        indicator.style.display = "block";
+        indicator.style.left = `${rect.left}px`;
+        indicator.style.top = `${position === "before" ? rect.top - 1 : rect.bottom - 1}px`;
+        indicator.style.width = `${Math.max(24, rect.width)}px`;
+    }
+    hideDropIndicator() {
+        if (this.blockDropIndicator)
+            this.blockDropIndicator.style.display = "none";
+    }
+    announceBlockMove(message) {
+        const live = this.blockMoveLive;
+        if (!live)
+            return;
+        live.textContent = "";
+        this.container.ownerDocument.defaultView?.setTimeout(() => { live.textContent = message; }, 0);
+    }
+    /**
+     * Ask the engine which anchors the current source may move next to. One call per drag source,
+     * so the UI offers only drops MoveBlock will accept — a document with section breaks is
+     * partitioned into regions, and drawing an indicator across one only to fail the drop was the
+     * behaviour this replaces. Null (no bridge support) keeps the previous offer-everything path.
+     */
+    refreshBlockMoveTargets(source) {
+        this.blockMoveTargets = source ? this.blockMoveTargetsFor(source) ?? null : null;
+    }
+    /**
+     * This block's legal destinations, from the memo when it is there. Returns `undefined` — not
+     * `null` — for "not asked yet", so a caller can tell an unknown answer from the engine's
+     * "no bridge support, offer everything" one.
+     */
+    blockMoveTargetsFor(source, options = {}) {
+        const bridge = this.exports.DocxSessionBridge;
+        const sourceId = this.anchorIdOf(source);
+        if (!sourceId || typeof bridge.ValidMoveTargets !== "function")
+            return null;
+        if (this.blockMoveTargetCache.has(sourceId))
+            return this.blockMoveTargetCache.get(sourceId);
+        if (options.cachedOnly)
+            return undefined;
+        let targets;
+        try {
+            const parsed = JSON.parse(bridge.ValidMoveTargets(this.handle, sourceId));
+            targets = new Map(parsed.map((t) => [t.anchorId, { before: t.before, after: t.after }]));
+        }
+        catch {
+            targets = null;
+        }
+        this.blockMoveTargetCache.set(sourceId, targets);
+        return targets;
+    }
+    /**
+     * Ask for the hovered block's destinations off the interaction path, and hide the handle if
+     * the answer comes back empty and that block is still the one under the pointer. The handle
+     * therefore appears immediately on hover and withdraws a beat later on the rare immovable
+     * block, instead of every hover paying for the query up front.
+     */
+    prefetchBlockMoveTargets(source) {
+        const view = this.container.ownerDocument.defaultView;
+        if (!view)
+            return;
+        this.blockMoveTargetPrefetch?.();
+        const run = () => {
+            this.blockMoveTargetPrefetch = null;
+            // The pointer has moved on (or the DOM was repainted) — the answer is no longer wanted.
+            if (this.closed || !source.isConnected || this.blockDragSource !== source)
+                return;
+            if (this.blockMoveTargetsFor(source)?.size === 0 && this.blockDragHandle)
+                this.blockDragHandle.style.display = "none";
+        };
+        const idle = view;
+        if (idle.requestIdleCallback && idle.cancelIdleCallback) {
+            const id = idle.requestIdleCallback(run, { timeout: 500 });
+            this.blockMoveTargetPrefetch = () => idle.cancelIdleCallback(id);
+        }
+        else {
+            const id = view.setTimeout(run, 0);
+            this.blockMoveTargetPrefetch = () => view.clearTimeout(id);
+        }
+    }
+    /**
+     * Whether `unit` is a legal destination for the current drag source — for a SPECIFIC side when
+     * one is given. A cross-block range or a section break between the blocks can make one side
+     * legal and the other not, so "this target is reachable" is not enough to pick a position.
+     */
+    isValidMoveTarget(unit, position) {
+        if (!this.blockMoveTargets)
+            return true; // no bridge support: engine stays the only gate
+        const id = this.anchorIdOf(unit);
+        const sides = id ? this.blockMoveTargets.get(id) : undefined;
+        if (!sides)
+            return false;
+        return position ? sides[position] : sides.before || sides.after;
+    }
+    /**
+     * The side of `unit` a drop at `clientY` should land on: the half the pointer is in, snapped to
+     * the other side when only that one is legal. Snapping rather than refusing keeps a reachable
+     * target usable — the illegal side is usually illegal only because a section break or a
+     * cross-block range sits between the two blocks on that side.
+     */
+    dropPositionFor(unit, clientY) {
+        const rect = unit.getBoundingClientRect();
+        const preferred = clientY < rect.top + rect.height / 2 ? "before" : "after";
+        if (this.isValidMoveTarget(unit, preferred))
+            return preferred;
+        const other = preferred === "before" ? "after" : "before";
+        return this.isValidMoveTarget(unit, other) ? other : preferred;
+    }
+    refreshBlockDropTargets() {
+        for (const cleanup of this.blockDragTargetCleanup.splice(0))
+            cleanup();
+        if (!this.blockDragHandle || this.options.paginated)
+            return;
+        for (const unit of this.bodyUnitNodes().filter((el) => this.isMovableBlockUnit(el))) {
+            this.blockDragTargetCleanup.push(dropTargetForElements({
+                element: unit,
+                // A target the engine would refuse is not a drop target at all, so Pragmatic never
+                // fires onDragEnter for it and no indicator is drawn over it.
+                canDrop: ({ source }) => source.data.type === BLOCK_DRAG_TYPE && source.data.sourceAnchorId !== this.anchorIdOf(unit) &&
+                    this.isValidMoveTarget(unit),
+                getData: ({ input }) => ({
+                    type: BLOCK_DRAG_TYPE,
+                    targetAnchorId: this.anchorIdOf(unit),
+                    position: this.dropPositionFor(unit, input.clientY),
+                    targetElement: unit,
+                }),
+                onDragEnter: ({ self }) => {
+                    const pos = self.data.position === "after" ? "after" : "before";
+                    this.showDropIndicator(unit, pos);
+                },
+                onDrag: ({ self }) => {
+                    const pos = self.data.position === "after" ? "after" : "before";
+                    this.showDropIndicator(unit, pos);
+                },
+                onDragLeave: () => this.hideDropIndicator(),
+            }));
+        }
+    }
+    closeBlockMoveMenu(restoreFocus = false) {
+        if (!this.blockMoveMenu || !this.blockDragHandle)
+            return;
+        this.blockMoveMenu.style.display = "none";
+        this.blockDragHandle.setAttribute("aria-expanded", "false");
+        this.blockDragHandle.setAttribute("aria-pressed", "false");
+        if (restoreFocus)
+            this.blockDragHandle.focus({ preventScroll: true });
+    }
+    openBlockMoveMenu() {
+        const menu = this.blockMoveMenu;
+        const handle = this.blockDragHandle;
+        const source = this.currentBlockDragSource();
+        if (!menu || !handle || !source)
+            return;
+        this.refreshBlockMoveTargets(source);
+        menu.querySelectorAll("button[data-move]").forEach((button) => {
+            button.disabled = !this.blockMoveDestination(source, button.dataset.move ?? "");
+        });
+        const rect = handle.getBoundingClientRect();
+        menu.style.display = "block";
+        menu.style.left = `${Math.max(4, rect.right + 6)}px`;
+        menu.style.top = `${Math.max(4, rect.top)}px`;
+        handle.setAttribute("aria-expanded", "true");
+        handle.setAttribute("aria-pressed", "true");
+        menu.querySelector("button:not(:disabled)")?.focus({ preventScroll: true });
+    }
+    /**
+     * Resolve a move-menu action to the block it should land against, considering only destinations
+     * the engine accepts. "Top"/"bottom" therefore mean the ends of the source's own movable region
+     * — on a document with section breaks that is the section, not the document, which is what makes
+     * the commands work at all there instead of always failing.
+     */
+    blockMoveDestination(source, action) {
+        const units = this.bodyUnitNodes().filter((el) => this.isMovableBlockUnit(el));
+        const index = units.indexOf(source);
+        if (index < 0)
+            return null;
+        // Only pairs the engine accepts: a target can be reachable on one side and refused on the
+        // other, so the SIDE is part of what makes a candidate valid.
+        const position = action === "up" || action === "top" ? "before" : "after";
+        const side = position === "before" ? units.slice(0, index) : units.slice(index + 1);
+        const candidates = side.filter((el) => this.isValidMoveTarget(el, position));
+        if (candidates.length === 0)
+            return null;
+        if (action === "up")
+            return { target: candidates[candidates.length - 1], position };
+        if (action === "down")
+            return { target: candidates[0], position };
+        if (action === "top")
+            return { target: candidates[0], position };
+        if (action === "bottom")
+            return { target: candidates[candidates.length - 1], position };
+        return null;
+    }
+    runBlockMoveMenuAction(action) {
+        const source = this.currentBlockDragSource();
+        if (!source)
+            return;
+        const destination = this.blockMoveDestination(source, action);
+        this.closeBlockMoveMenu();
+        if (!destination)
+            return;
+        const sourceId = this.anchorIdOf(source);
+        const targetId = this.anchorIdOf(destination.target);
+        if (sourceId && targetId)
+            this.moveBlock(sourceId, targetId, destination.position);
+    }
+    /** The nearest ancestor that actually scrolls the document flow, for drag autoscroll. */
+    scrollContainer() {
+        const view = this.container.ownerDocument.defaultView;
+        for (let el = this.editRoot; el; el = el.parentElement) {
+            const overflowY = view?.getComputedStyle(el).overflowY ?? "visible";
+            if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight)
+                return el;
+        }
+        return null;
+    }
+    /** Mount one floating handle; PDD owns pointer dragging while the menu owns keyboard moves. */
+    setupBlockDrag() {
+        if (!this.options.blockDrag || this.options.paginated || this.closed || this.blockDragHandle)
+            return;
+        const doc = this.container.ownerDocument;
+        ensureBlockDragStyles(doc);
+        const handle = doc.createElement("div");
+        handle.className = "docx-block-handle";
+        handle.textContent = "⠿";
+        handle.tabIndex = 0;
+        handle.setAttribute("role", "button");
+        handle.setAttribute("contenteditable", "false");
+        handle.setAttribute("aria-haspopup", "menu");
+        handle.setAttribute("aria-expanded", "false");
+        handle.setAttribute("aria-pressed", "false");
+        const indicator = doc.createElement("div");
+        indicator.className = "docx-block-drop-indicator";
+        const menu = doc.createElement("div");
+        menu.className = "docx-block-move-menu";
+        menu.setAttribute("role", "menu");
+        menu.innerHTML = `
+      <button type="button" role="menuitem" data-move="up">Move up</button>
+      <button type="button" role="menuitem" data-move="down">Move down</button>
+      <button type="button" role="menuitem" data-move="top">Move to top</button>
+      <button type="button" role="menuitem" data-move="bottom">Move to bottom</button>`;
+        const live = doc.createElement("div");
+        live.className = "docx-block-live-region";
+        live.setAttribute("role", "status");
+        live.setAttribute("aria-live", "polite");
+        this.container.append(handle, indicator, menu, live);
+        this.blockDragHandle = handle;
+        this.blockDropIndicator = indicator;
+        this.blockMoveMenu = menu;
+        this.blockMoveLive = live;
+        const onPointerMove = (event) => {
+            // Keep the floating draggable stationary between pointerdown and native dragstart.
+            // Repositioning it under the pointer during the browser's drag threshold cancels
+            // drag initiation before PDD can receive dragstart.
+            if (this.blockDragging || this.blockDragPointerDown)
+                return;
+            const unit = this.blockUnitOf(event.target);
+            if (this.isMovableBlockUnit(unit))
+                this.showBlockHandle(unit);
+        };
+        const onFocusIn = (event) => {
+            const unit = this.blockUnitOf(event.target);
+            if (this.isMovableBlockUnit(unit))
+                this.showBlockHandle(unit);
+        };
+        const onPointerLeave = (event) => {
+            const next = event.relatedTarget instanceof Node ? event.relatedTarget : null;
+            if (next && (handle.contains(next) || menu.contains(next)))
+                return;
+            this.hideBlockHandle();
+        };
+        const onViewportChange = () => this.positionBlockHandle();
+        this.container.addEventListener("pointermove", onPointerMove);
+        this.container.addEventListener("focusin", onFocusIn);
+        this.container.addEventListener("pointerleave", onPointerLeave);
+        doc.addEventListener("scroll", onViewportChange, true);
+        doc.defaultView?.addEventListener("resize", onViewportChange);
+        this.blockDragCleanup.push(() => this.container.removeEventListener("pointermove", onPointerMove), () => this.container.removeEventListener("focusin", onFocusIn), () => this.container.removeEventListener("pointerleave", onPointerLeave), () => doc.removeEventListener("scroll", onViewportChange, true), () => doc.defaultView?.removeEventListener("resize", onViewportChange));
+        const onHandleClick = () => {
+            if (menu.style.display === "block")
+                this.closeBlockMoveMenu();
+            else
+                this.openBlockMoveMenu();
+        };
+        const onHandlePointerDown = () => { this.blockDragPointerDown = true; };
+        const onPointerUp = () => { this.blockDragPointerDown = false; };
+        const onHandleKeydown = (event) => {
+            if (event.key !== "Enter" && event.key !== " ")
+                return;
+            event.preventDefault();
+            onHandleClick();
+        };
+        const onMenuClick = (event) => {
+            const button = event.target?.closest("button[data-move]");
+            if (button && !button.disabled)
+                this.runBlockMoveMenuAction(button.dataset.move ?? "");
+        };
+        const onMenuKeydown = (event) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                this.closeBlockMoveMenu(true);
+            }
+        };
+        handle.addEventListener("click", onHandleClick);
+        handle.addEventListener("pointerdown", onHandlePointerDown);
+        handle.addEventListener("keydown", onHandleKeydown);
+        menu.addEventListener("click", onMenuClick);
+        menu.addEventListener("keydown", onMenuKeydown);
+        doc.addEventListener("pointerup", onPointerUp, true);
+        doc.addEventListener("pointercancel", onPointerUp, true);
+        this.blockDragCleanup.push(() => handle.removeEventListener("click", onHandleClick), () => handle.removeEventListener("pointerdown", onHandlePointerDown), () => handle.removeEventListener("keydown", onHandleKeydown), () => menu.removeEventListener("click", onMenuClick), () => menu.removeEventListener("keydown", onMenuKeydown), () => doc.removeEventListener("pointerup", onPointerUp, true), () => doc.removeEventListener("pointercancel", onPointerUp, true));
+        this.blockDragCleanup.push(draggable({
+            element: handle,
+            canDrag: () => !!this.currentBlockDragSource(),
+            getInitialData: () => {
+                const source = this.currentBlockDragSource();
+                return { type: BLOCK_DRAG_TYPE, sourceAnchorId: source ? this.anchorIdOf(source) : undefined };
+            },
+            onDragStart: () => {
+                this.blockDragging = true;
+                handle.classList.add("docx-block-dragging");
+                this.closeBlockMoveMenu();
+                this.refreshBlockMoveTargets(this.currentBlockDragSource());
+                this.refreshBlockDropTargets();
+            },
+            onDrop: () => {
+                this.blockDragging = false;
+                this.blockDragPointerDown = false;
+                handle.classList.remove("docx-block-dragging");
+                this.hideDropIndicator();
+            },
+        }));
+        this.blockDragCleanup.push(monitorForElements({
+            canMonitor: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
+            onDrop: ({ source, location }) => {
+                this.hideDropIndicator();
+                const drop = location.current.dropTargets[0]?.data;
+                const sourceId = source.data.sourceAnchorId;
+                const targetId = drop?.targetAnchorId;
+                const position = drop?.position === "after" ? "after" : "before";
+                if (typeof sourceId === "string" && typeof targetId === "string")
+                    this.moveBlock(sourceId, targetId, position);
+                else
+                    // Released outside any valid target. Say so — a silent no-op reads as a broken drag.
+                    this.announceBlockMove("Move cancelled — the block was not dropped on a valid position.");
+            },
+        }));
+        // Register on the element that actually scrolls. editRoot is the document flow — in the
+        // ribbon surface the scroller is an ancestor of it, and registering the flow made Pragmatic
+        // log "attached to an element that appears not to be scrollable" on every document open
+        // while doing nothing.
+        const scroller = this.scrollContainer();
+        if (scroller) {
+            this.blockDragCleanup.push(autoScrollForElements({
+                element: scroller,
+                canScroll: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
+                getAllowedAxis: () => "vertical",
+            }));
+        }
+        this.blockDragCleanup.push(autoScrollWindowForElements({
+            canScroll: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
+            getAllowedAxis: () => "vertical",
+        }));
+        this.refreshBlockDropTargets();
+    }
+    teardownBlockDrag() {
+        this.blockMoveTargetPrefetch?.();
+        this.blockMoveTargetPrefetch = null;
+        this.blockMoveTargetCache.clear();
+        for (const cleanup of this.blockDragTargetCleanup.splice(0))
+            cleanup();
+        for (const cleanup of this.blockDragCleanup.splice(0))
+            cleanup();
+        this.blockDragHandle?.remove();
+        this.blockDropIndicator?.remove();
+        this.blockMoveMenu?.remove();
+        this.blockMoveLive?.remove();
+        this.blockDragHandle = null;
+        this.blockDropIndicator = null;
+        this.blockMoveMenu = null;
+        this.blockMoveLive = null;
+        this.blockDragSource = null;
+        this.blockDragging = false;
+        this.blockDragPointerDown = false;
+    }
     // ─── internals ───────────────────────────────────────────────────────
     assertOpen() {
         if (this.closed)
@@ -946,11 +1539,16 @@ export class DocxEditor {
     wireBlock(el) {
         if (!EDITABLE_TAGS.has(el.tagName))
             return;
+        if (el.closest("tr[class$='row-del'], tr[class*='row-del ']") ||
+            el.querySelector(":scope > del[class$='move-from'], :scope > del[class*='move-from ']")) {
+            el.setAttribute("contenteditable", "false");
+            return;
+        }
         const unid = el.getAttribute("data-anchor");
         // Only blocks the markdown projection addresses are editable via the text path. This INCLUDES
-        // 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.
+        // table-cell paragraphs (the projection indexes them), so cell text IS editable. Table-aware
+        // key handling keeps structural edits safe while still providing Word-style cell navigation
+        // (see onKeydown). Anything the projection does not index (unstamped content) stays read-only.
         // 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))
@@ -1042,7 +1640,7 @@ export class DocxEditor {
         }
         // Plain block: re-render ONLY this block from the live session for canonical HTML. Swapping the
         // just-blurred node here is safe (verified — focus stays on the newly-clicked block).
-        const html = this.exports.DocxSessionBridge.RenderBlockHtml(this.handle, newAnchor, this.options.cssPrefix, this.options.fabricateClasses);
+        const html = this.renderBlockHtml(newAnchor);
         if (html.charCodeAt(0) !== 0x7b /* not an error object */) {
             const fresh = new DOMParser().parseFromString(html, "text/html").body.firstElementChild;
             const inBand = this.isBandBlock(el);
@@ -1089,19 +1687,18 @@ export class DocxEditor {
                 return;
             }
         }
-        // Inside a table cell, structural ops that change the TABLE GRID (cross-cell merge,
-        // list-nest, focus-jumping Tab) stay INERT — the single-block model can't give them
-        // whole-table context. Tab is swallowed (no focus escape / literal tab); Backspace at
-        // the cell's start does not merge across the cell boundary (mid-text Backspace still
-        // deletes normally). Enter, however, splits the cell paragraph into two paragraphs
-        // WITHIN the same cell — the engine keeps the new w:p in the w:tc, the grid is
-        // unchanged, so it's safe (it's how a cell holds stacked lines: value over a smaller
-        // label, multi-line addresses). (GAP3.)
+        // Inside a table cell, Backspace at the cell's start does not merge across the cell
+        // boundary (mid-text Backspace still deletes normally). Enter splits the cell paragraph
+        // WITHIN the same cell — the engine keeps the new w:p in the w:tc, so the grid is unchanged.
+        // Tab navigation is handled explicitly below; at the final cell it uses the existing safe
+        // whole-table row insertion path to match Word's add-a-row behavior.
         const inTableCell = !!el.closest("table");
-        // Tab / Shift+Tab on a list item nests / un-nests it (changes list level).
-        if (ev.key === "Tab") {
+        // Plain Tab / Shift+Tab moves between table cells. Outside tables it retains list
+        // nest/un-nest behavior. Modified Tab chords remain available to the browser/platform.
+        if (ev.key === "Tab" && !ev.ctrlKey && !ev.metaKey && !ev.altKey && !ev.isComposing) {
             if (inTableCell) {
                 ev.preventDefault();
+                this.navigateTableCell(el, ev.shiftKey);
                 return;
             }
             if (isListBlock(el)) {
@@ -1136,6 +1733,50 @@ export class DocxEditor {
             }
         }
     }
+    /** Editable cells in visual document order, excluding cells from any nested table. */
+    tableCellsFor(el) {
+        const cell = el.closest("td, th");
+        const table = cell?.closest("table");
+        if (!cell || !table)
+            return null;
+        const cells = Array.from(table.querySelectorAll("td, th"))
+            .filter((candidate) => candidate.closest("table") === table);
+        const index = cells.indexOf(cell);
+        return index >= 0 ? { cells, index } : null;
+    }
+    /** First addressable paragraph in a cell, fenced against nested-table descendants. */
+    editableInCell(cell) {
+        return Array.from(cell.querySelectorAll('[data-anchor][contenteditable="true"]')).find((block) => block.closest("td, th") === cell) ?? null;
+    }
+    /** Word-style cell navigation: Shift+Tab goes back, Tab goes forward, and Tab at the
+     *  final cell appends a row before entering its first cell. The first cell is a hard
+     *  boundary for Shift+Tab so focus never leaks out of the editor table. */
+    navigateTableCell(el, backwards) {
+        const state = this.tableCellsFor(el);
+        if (!state)
+            return;
+        const adjacent = state.cells[state.index + (backwards ? -1 : 1)];
+        if (adjacent) {
+            const target = this.editableInCell(adjacent);
+            if (target)
+                placeCaretAtOffset(target, 0);
+            return;
+        }
+        if (backwards)
+            return;
+        // The current block may contain uncommitted typing. insertTableRow flushes it before the
+        // structural edit, then reconcile/remount restores focus by block index. Resolve the new
+        // adjacent cell from that fresh DOM rather than retaining a node from the replaced table.
+        this.activeBlock = el;
+        this.insertTableRow("below");
+        const fresh = this.activeBlock ? this.tableCellsFor(this.activeBlock) : null;
+        if (!fresh)
+            return;
+        const target = fresh.cells[fresh.index + 1];
+        const block = target ? this.editableInCell(target) : null;
+        if (block)
+            placeCaretAtOffset(block, 0);
+    }
     /** Shift+Enter: insert an intra-paragraph line break at the caret. Delegates to the
      *  native `insertLineBreak` command, which inserts a <br> AND positions the caret
      *  after it correctly (handling the browser's bogus trailing-<br> rule) so typing
@@ -1309,11 +1950,27 @@ export class DocxEditor {
     }
     /** Render a block by anchor and parse it into a detached element (null on error). */
     renderInto(anchorId) {
-        const html = this.exports.DocxSessionBridge.RenderBlockHtml(this.handle, anchorId, this.options.cssPrefix, this.options.fabricateClasses);
+        const html = this.renderBlockHtml(anchorId);
         if (html.charCodeAt(0) === 0x7b /* error object */)
             return null;
         return new DOMParser().parseFromString(html, "text/html").body.firstElementChild;
     }
+    get renderTrackedChanges() {
+        return this.options.trackedChanges === TrackedChangeMode.RenderInline;
+    }
+    renderBlockHtml(anchorId) {
+        const bridge = this.exports.DocxSessionBridge;
+        if (typeof bridge.RenderBlockHtmlForReview === "function") {
+            return bridge.RenderBlockHtmlForReview(this.handle, anchorId, this.options.cssPrefix, this.options.fabricateClasses, this.renderTrackedChanges);
+        }
+        return bridge.RenderBlockHtml(this.handle, anchorId, this.options.cssPrefix, this.options.fabricateClasses);
+    }
+    renderPlanJson() {
+        const bridge = this.exports.DocxSessionBridge;
+        return typeof bridge.ListRenderedBlocks === "function"
+            ? bridge.ListRenderedBlocks(this.handle, this.renderTrackedChanges)
+            : bridge.ListBlocks(this.handle);
+    }
     /** Render two blocks in ONE batched bridge call when the bundle carries RenderBlocksHtml —
      *  the per-render shell/converter setup is paid once instead of twice, which matters on the
      *  Enter path (split renders both halves synchronously under the keystroke). Falls back to
@@ -1323,7 +1980,11 @@ export class DocxEditor {
         const bridge = this.exports.DocxSessionBridge;
         if (typeof bridge.RenderBlocksHtml === "function") {
             try {
-                const map = JSON.parse(bridge.RenderBlocksHtml(this.handle, JSON.stringify([a, b]), this.options.cssPrefix, this.options.fabricateClasses));
+                const idsJson = JSON.stringify([a, b]);
+                const json = typeof bridge.RenderBlocksHtmlForReview === "function"
+                    ? bridge.RenderBlocksHtmlForReview(this.handle, idsJson, this.options.cssPrefix, this.options.fabricateClasses, this.renderTrackedChanges)
+                    : bridge.RenderBlocksHtml(this.handle, idsJson, this.options.cssPrefix, this.options.fabricateClasses);
+                const map = JSON.parse(json);
                 if (!map.error) {
                     const parse = (h) => h
                         ? new DOMParser().parseFromString(h, "text/html").body
@@ -1349,12 +2010,24 @@ export class DocxEditor {
     }
     parseEdit(json) {
         try {
-            return JSON.parse(json);
+            const result = JSON.parse(json);
+            if (result.success)
+                this.invalidateBlockMoveTargets();
+            return result;
         }
         catch {
             return { success: false };
         }
     }
+    /**
+     * Drop the memoized `ValidMoveTargets` answers. Which blocks a block may move next to is a
+     * fact about the DOCUMENT, so it survives hovering but not editing — and the two places a
+     * document changes are `parseEdit` (every mutation that returns an `EditResult`) and
+     * undo/redo, which return a bare boolean and so cannot go through it.
+     */
+    invalidateBlockMoveTargets() {
+        this.blockMoveTargetCache.clear();
+    }
     // ─── M5: formatting commands (ribbon) ────────────────────────────────
     // ─── Multi-block selection helpers (format a whole stack of paragraphs at once) ──────
     /**
@@ -1942,15 +2615,19 @@ export class DocxEditor {
     undo() {
         if (this.closed)
             return;
-        if (this.exports.DocxSessionBridge.Undo(this.handle))
-            this.reconcile();
+        if (!this.exports.DocxSessionBridge.Undo(this.handle))
+            return;
+        this.invalidateBlockMoveTargets();
+        this.reconcile();
     }
     /** 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.reconcile();
+        if (!this.exports.DocxSessionBridge.Redo(this.handle))
+            return;
+        this.invalidateBlockMoveTargets();
+        this.reconcile();
     }
     // ─── Header/footer region commands (no-ops unless `headerFooter` is on) ───────────────
     /**
@@ -2058,6 +2735,11 @@ export class DocxEditor {
      */
     renderFullHtml() {
         const bridge = this.exports.DocxSessionBridge;
+        if (typeof bridge.RenderHtmlForReview === "function") {
+            const html = bridge.RenderHtmlForReview(this.handle, this.options.cssPrefix, this.options.fabricateClasses, this.options.paginated, this.options.scale, this.renderTrackedChanges);
+            if (html.charCodeAt(0) !== 0x7b)
+                return html;
+        }
         if (typeof bridge.RenderHtml === "function") {
             const html = bridge.RenderHtml(this.handle, this.options.cssPrefix, this.options.fabricateClasses, this.options.paginated, this.options.scale);
             if (html.charCodeAt(0) !== 0x7b /* not an error object */)
@@ -2070,7 +2752,7 @@ export class DocxEditor {
         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));
+        return this.exports.DocumentConverter.ConvertDocxToHtmlComplete(...completeArgs(bytes, this.options.cssPrefix, this.options.fabricateClasses, this.options.paginated, this.options.scale, this.renderTrackedChanges));
     }
     /** Editable BODY blocks in document order (band blocks are enumerated by `ownerRoot`). */
     editableList() {
@@ -2169,28 +2851,39 @@ export class DocxEditor {
         // 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));
+        const plan = JSON.parse(this.renderPlanJson());
         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)");
+        if (needsRemount(bodyDiff, plan.body, oldKinds)) {
+            // Name the shape, not just the verdict: "churn" and "a list item moved in or out" are very
+            // different findings when a repaint unexpectedly costs a whole-document render.
+            return this.bail(`needsRemount (li change or churn): +${bodyDiff.added.length} -${bodyDiff.removed.length} ` +
+                `~${bodyDiff.substituted.length} moved=${bodyDiff.moved.length} of ${plan.body.length}`);
+        }
         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 movedBodyNew = new Set(bodyDiff.moved.map((m) => m.newIndex));
+        const addedBodyIds = bodyDiff.added
+            .filter((j) => !movedBodyNew.has(j))
+            .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));
+            const idsJson = JSON.stringify(allIds);
+            const renderedJson = typeof bridge.RenderBlocksHtmlForReview === "function"
+                ? bridge.RenderBlocksHtmlForReview(this.handle, idsJson, this.options.cssPrefix, this.options.fabricateClasses, this.renderTrackedChanges)
+                : bridge.RenderBlocksHtml(this.handle, idsJson, this.options.cssPrefix, this.options.fabricateClasses);
+            rendered = JSON.parse(renderedJson);
             if (rendered.error)
                 return this.bail(`render error: ${rendered.error}`);
             for (const id of allIds)
@@ -2209,7 +2902,7 @@ export class DocxEditor {
             return el;
         };
         const freshBody = new Map();
-        for (const j of bodyDiff.added) {
+        for (const j of bodyDiff.added.filter((j) => !movedBodyNew.has(j))) {
             const el = parse(rendered[plan.body[j].id]);
             if (!el)
                 return this.bail(`unparseable render: ${plan.body[j].id}`);
@@ -2267,16 +2960,6 @@ export class DocxEditor {
      *  bail-reason string (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 "kept order violation";
-            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.
@@ -2307,31 +2990,34 @@ export class DocxEditor {
             }
             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 movedOldByNew = new Map(diff.moved.map((m) => [m.newIndex, m.oldIndex]));
+        const movedNew = new Set(diff.moved.map((m) => m.newIndex));
+        const movedOld = new Set(diff.moved.map((m) => m.oldIndex));
+        const pureAdded = diff.added.filter((j) => !subOldByNew.has(j) && !movedNew.has(j));
+        const pureRemoved = diff.removed.filter((i) => !diff.substituted.some((s) => s.oldIndex === i) && !movedOld.has(i));
         const nodeAt = (j) => {
             const oi = diff.keep.get(j);
             if (oi !== undefined)
                 return oldNodes[oi];
+            const movedOi = movedOldByNew.get(j);
+            if (movedOi !== undefined)
+                return oldNodes[movedOi];
             if (subOldByNew.has(j))
                 return fresh.get(j);
             const f = fresh.get(j);
             return f && f.isConnected ? f : null;
         };
+        // Preserve the established incremental insertion path: body render output may
+        // legitimately use several wrapper parents (for example border groups), so it is
+        // not valid to normalize the whole body against one common parent.
         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);
-            }
+            for (let k = j + 1; k < units.length && !next; k++)
+                next = nodeAt(k);
             const prevW = prev ? this.unitWrapperOf(prev) : null;
             const nextW = next ? this.unitWrapperOf(next) : null;
             if (prevW && nextW && prevW.parentElement !== nextW.parentElement)
@@ -2341,13 +3027,43 @@ export class DocxEditor {
             else if (nextW)
                 nextW.before(el);
             else
-                return "insert with no anchored neighbor"; // empty container — nowhere provably correct
+                return "insert with no anchored neighbor";
             this.wireUnit(el, units[j]);
         }
-        // Pure removals last, taking now-empty generated wrappers with them.
+        // Pure removals take their now-empty generated wrappers with them. Exact-token
+        // move sources remain live even though the LCS also reports them as removed.
         for (const i of pureRemoved) {
-            const wrapper = this.unitWrapperOf(oldNodes[i]);
-            wrapper.remove();
+            this.unitWrapperOf(oldNodes[i]).remove();
+        }
+        // A block move changes one exact-token unit's slot. Move only that existing
+        // wrapper beside its final neighbor; this preserves identity without disturbing
+        // unrelated nodes or assuming every rendered unit shares one DOM parent.
+        for (const { newIndex } of [...diff.moved].sort((a, b) => a.newIndex - b.newIndex)) {
+            const moving = nodeAt(newIndex);
+            if (!moving?.isConnected)
+                return "move source is not connected";
+            const movingW = this.unitWrapperOf(moving);
+            let prevW = null;
+            for (let k = newIndex - 1; k >= 0 && !prevW; k--) {
+                const n = nodeAt(k);
+                if (n?.isConnected)
+                    prevW = this.unitWrapperOf(n);
+            }
+            let nextW = null;
+            for (let k = newIndex + 1; k < units.length && !nextW; k++) {
+                const n = nodeAt(k);
+                if (n?.isConnected)
+                    nextW = this.unitWrapperOf(n);
+            }
+            if (prevW && prevW !== movingW && prevW.parentElement === movingW.parentElement) {
+                prevW.after(movingW);
+            }
+            else if (nextW && nextW !== movingW && nextW.parentElement === movingW.parentElement) {
+                nextW.before(movingW);
+            }
+            else {
+                return "move neighbors in different parents";
+            }
         }
         return true;
     }
@@ -2490,7 +3206,7 @@ export class DocxEditor {
         if (typeof bridge.ListBlocks !== "function")
             return;
         try {
-            const plan = JSON.parse(bridge.ListBlocks(this.handle));
+            const plan = JSON.parse(this.renderPlanJson());
             if (plan.error)
                 return;
             // Positional pairing: a fresh full mount renders exactly the plan's units in
@@ -2527,6 +3243,7 @@ export class DocxEditor {
      * block's content-hashed unid changes across the save/reproject a remount performs.
      */
     remount(focusIndex = -1, caretAtEnd = false) {
+        this.teardownBlockDrag();
         this.refreshAnchorMap();
         const fullHtml = this.renderFullHtml();
         this.activeBlock = null;
@@ -2545,6 +3262,7 @@ export class DocxEditor {
         // 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);
+        this.setupBlockDrag();
     }
 }
 //# sourceMappingURL=editor.js.map