docxodus 9.3.0 → 9.5.0

package/dist/editor.js

@@ -17,14 +17,24 @@
  * full fidelity, and save() is lossless for them.
  */
 import { paginateHtml } from "./pagination.js";
+import { DocumentViewport } from "./viewport.js";
 import { HeaderFooterRegion } from "./editor-headerfooter.js";
 import { draggable, dropTargetForElements, monitorForElements, } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
+import { setCustomNativeDragPreview } from "@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview";
+import { pointerOutsideOfPreview } from "@atlaskit/pragmatic-drag-and-drop/element/pointer-outside-of-preview";
 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();
+/** One-line description of a block, for the handle's label and the drag preview chip. */
+function blockPreviewText(unit) {
+    if (unit.tagName === "TABLE")
+        return "Table";
+    const text = (unit.textContent ?? "").trim().replace(/\s+/g, " ");
+    return text.length > 48 ? `${text.slice(0, 48)}…` : text;
+}
 function ensureBlockDragStyles(doc) {
     if (blockDragStyledDocuments.has(doc))
         return;
@@ -40,10 +50,28 @@ function ensureBlockDragStyles(doc) {
 }
 .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-handle.docx-block-dragging { cursor: grabbing; opacity: .35; }
+/* The block being carried. Dimming it is the "a drag is happening" signal that survives the
+   pointer being anywhere on screen — the drop line only says where, not what. */
+.docx-block-drag-source { opacity: .38; transition: opacity 120ms ease-out; }
+/* Positioned by transform so tracking the pointer costs no layout. Flipping display none→block
+   restarts the fade — one cheap entry animation per appearance, none while it tracks. */
 .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);
+  position: fixed; top: 0; left: 0; z-index: 2147482999; display: none; height: 0;
+  pointer-events: none; border-top: 2px solid #2e90fa;
+  filter: drop-shadow(0 1px 2px rgba(46,144,250,.5));
+  animation: docx-block-drop-in 110ms ease-out;
+}
+.docx-block-drop-indicator::before {
+  content: ""; position: absolute; top: -5px; left: -2px; width: 8px; height: 8px;
+  border-radius: 50%; background: #2e90fa;
+}
+@keyframes docx-block-drop-in { from { opacity: 0; } to { opacity: 1; } }
+.docx-block-drag-preview {
+  max-width: 320px; padding: 6px 10px; border: 1px solid #b2ddff; border-radius: 6px;
+  background: #eff8ff; color: #175cd3; box-shadow: 0 6px 16px rgba(16,24,40,.18);
+  font: 500 13px/1.35 system-ui, sans-serif; white-space: nowrap; overflow: hidden;
+  text-overflow: ellipsis;
 }
 .docx-block-move-menu {
   position: fixed; z-index: 2147483001; display: none; min-width: 150px; padding: 5px;
@@ -559,12 +587,22 @@ export class DocxEditor {
         this.blockMoveLive = null;
         this.blockDragSource = null;
         this.blockDragCleanup = [];
-        this.blockDragTargetCleanup = [];
+        /** Block boxes measured at drag start — see `BlockDropZone`. Empty when no drag is in flight. */
+        this.dropZones = [];
+        /** Combined scroll offset when `dropZones` was measured, and the scroller measured against. */
+        this.dropZoneOrigin = 0;
+        this.dropZoneScroller = null;
         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;
         /**
@@ -697,6 +735,11 @@ export class DocxEditor {
         this.handle = handle;
         this.options = options;
         this.editRoot = container;
+        this.viewport = new DocumentViewport(container, {
+            columnWidth: options.columnWidth,
+            fitToWidth: options.fitToWidth,
+            scale: options.scale,
+        });
         if (typeof document !== "undefined") {
             document.addEventListener("selectionchange", this.onSelectionChange);
             document.addEventListener("mousedown", this.onMouseDown, true);
@@ -784,6 +827,8 @@ export class DocxEditor {
             editable: options.editable ?? true,
             paginated: options.paginated ?? false,
             scale: options.scale ?? 1,
+            columnWidth: options.columnWidth ?? "section",
+            fitToWidth: options.fitToWidth ?? true,
             headerFooter: options.headerFooter ?? false,
             blockDrag: options.blockDrag ?? false,
             trackedChanges: options.trackedChanges ?? TrackedChangeMode.Accept,
@@ -841,6 +886,7 @@ export class DocxEditor {
         }
         this.clearDragSelection();
         this.teardownBlockDrag();
+        this.viewport.dispose();
         this.exports.DocxSessionBridge.CloseSession(this.handle);
     }
     /**
@@ -859,6 +905,14 @@ export class DocxEditor {
     get root() {
         return this.container;
     }
+    /**
+     * The zoom the viewport is currently applying (1 = 100%). Below 1 the page is wider than the
+     * host and has been scaled to fit rather than reflowed — the honest thing to show a user who
+     * is wondering why a phone shows the whole page.
+     */
+    get zoom() {
+        return this.viewport.scale;
+    }
     /**
      * The live `DocxSession` handle backing this editor — the model of record.
      *
@@ -890,13 +944,12 @@ export class DocxEditor {
             return true;
         }
         const destination = res.created?.[0] ?? res.modified?.[0];
-        // Review rendering creates a visible move-from and move-to pair. A full remount keeps
-        // their revision wrappers and table-row styling canonical; direct moves use the ordered
-        // incremental reconciler and retain the exact existing DOM node.
-        if (this.renderTrackedChanges)
-            this.remount();
-        else
-            this.reconcile();
+        // 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;
@@ -928,7 +981,15 @@ export class DocxEditor {
             : node?.parentElement;
         if (!el || !this.editRoot.contains(el))
             return null;
-        return this.bodyUnitNodes().find((unit) => unit === el || unit.contains(el)) ?? 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))
@@ -956,23 +1017,24 @@ export class DocxEditor {
             return;
         const changed = unit !== this.blockDragSource;
         this.blockDragSource = unit;
-        if (changed)
-            this.refreshBlockMoveTargets(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.
-        if (this.blockMoveTargets?.size === 0) {
+        // 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);
+        const preview = blockPreviewText(unit);
         handle.setAttribute("aria-label", preview ? `Move block: ${preview}` : "Move block");
-        if (changed)
-            this.refreshBlockDropTargets();
     }
     hideBlockHandle() {
         if (this.blockDragging || this.blockMoveMenu?.style.display === "block")
@@ -985,15 +1047,42 @@ export class DocxEditor {
         if (source && this.blockDragHandle?.style.display !== "none")
             this.showBlockHandle(source);
     }
-    showDropIndicator(target, position) {
+    /** Draw the drop line on `zone`'s requested edge, or take it away when there is no target. */
+    paintDropIndicator(data) {
         const indicator = this.blockDropIndicator;
+        const zone = data.zone;
         if (!indicator)
             return;
-        const rect = this.unitWrapperOf(target).getBoundingClientRect();
+        if (!zone) {
+            this.hideDropIndicator();
+            return;
+        }
+        const y = Math.round(this.dropEdgeY(zone, data.position === "after" ? "after" : "before")
+            + this.dropZoneShift()) - 1;
+        // Position before revealing, so the entry fade never plays at a stale spot.
+        indicator.style.transform = `translate3d(${Math.round(zone.left)}px, ${y}px, 0)`;
+        indicator.style.width = `${Math.max(24, Math.round(zone.width))}px`;
         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`;
+    }
+    /**
+     * Where to draw the line for an insertion on `position` of `zone` — the MIDDLE of the gap to
+     * the neighbour on that side, not the zone's own border-box edge. A paragraph's `w:spacing`
+     * becomes a CSS margin, which sits outside the box, so drawing on the edge underlines the
+     * block's last line instead of reading as a gap between two blocks. Falls back to the raw edge
+     * at the ends of the flow, and degrades to the same value when blocks are contiguous.
+     */
+    dropEdgeY(zone, position) {
+        const neighbour = this.dropZones[zone.index + (position === "after" ? 1 : -1)];
+        // At the ends of the flow there is nothing to bisect against, so half the block's own
+        // margin stands in for half the gap — the same position, one contributor instead of two.
+        if (!neighbour) {
+            return position === "after"
+                ? zone.bottom + zone.marginAfter / 2
+                : zone.top - zone.marginBefore / 2;
+        }
+        return position === "after"
+            ? (zone.bottom + neighbour.top) / 2
+            : (neighbour.bottom + zone.top) / 2;
     }
     hideDropIndicator() {
         if (this.blockDropIndicator)
@@ -1013,18 +1102,60 @@ export class DocxEditor {
      * 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 = source ? this.anchorIdOf(source) : null;
-        if (!sourceId || typeof bridge.ValidMoveTargets !== "function") {
-            this.blockMoveTargets = null;
-            return;
-        }
+        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 targets = JSON.parse(bridge.ValidMoveTargets(this.handle, sourceId));
-            this.blockMoveTargets = new Map(targets.map((t) => [t.anchorId, { before: t.before, after: t.after }]));
+            const parsed = JSON.parse(bridge.ValidMoveTargets(this.handle, sourceId));
+            targets = new Map(parsed.map((t) => [t.anchorId, { before: t.before, after: t.after }]));
         }
         catch {
-            this.blockMoveTargets = null;
+            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);
         }
     }
     /**
@@ -1041,49 +1172,74 @@ export class DocxEditor {
             return false;
         return position ? sides[position] : sides.before || sides.after;
     }
+    /** Measure every movable block once, at drag start. See `BlockDropZone`. */
+    captureDropZones() {
+        const view = this.container.ownerDocument.defaultView;
+        this.dropZoneScroller = this.scrollContainer();
+        this.dropZoneOrigin = this.scrollOffsetSum();
+        this.dropZones = [];
+        const boxes = [];
+        for (const unit of this.bodyUnitNodes()) {
+            const anchorId = this.isMovableBlockUnit(unit) ? this.anchorIdOf(unit) : null;
+            if (!anchorId)
+                continue;
+            const box = this.unitWrapperOf(unit);
+            const rect = box.getBoundingClientRect();
+            boxes.push(box);
+            this.dropZones.push({
+                unit, anchorId, index: this.dropZones.length,
+                top: rect.top, bottom: rect.bottom, left: rect.left, width: rect.width,
+                marginBefore: 0, marginAfter: 0,
+            });
+        }
+        // Only the flow's two ends ever consult a margin, so only they are worth a style read.
+        const ends = new Set([0, this.dropZones.length - 1].filter((i) => i >= 0 && i < boxes.length));
+        for (const i of ends) {
+            const style = view?.getComputedStyle(boxes[i]);
+            this.dropZones[i].marginBefore = parseFloat(style?.marginTop ?? "0") || 0;
+            this.dropZones[i].marginAfter = parseFloat(style?.marginBottom ?? "0") || 0;
+        }
+    }
+    scrollOffsetSum() {
+        const view = this.container.ownerDocument.defaultView;
+        return (view?.scrollY ?? 0) + (this.dropZoneScroller?.scrollTop ?? 0);
+    }
+    /** How far the measured boxes have travelled since capture, from scrolling (drag autoscroll). */
+    dropZoneShift() {
+        return this.dropZoneOrigin - this.scrollOffsetSum();
+    }
     /**
-     * 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.
+     * Where a drop at `clientY` lands, or null when nothing there is legal.
+     *
+     * Resolution is by VERTICAL GEOMETRY over the measured blocks, not by which element the pointer
+     * is over: the drag handle floats in the page margin, so a drag straight down the gutter — the
+     * natural gesture — never crosses a paragraph box, and element hit testing gave those drags no
+     * indicator and no drop at all. The nearest block by vertical distance is the target; the half
+     * the pointer is in picks the side, snapped to the other side when only that one is legal
+     * (a section break or a cross-block range usually makes exactly one side illegal). When neither
+     * side is legal — the pointer is in a region this block cannot reach — there is no drop, and
+     * nothing is drawn.
      */
-    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(),
-            }));
+    resolveDropAt(clientY) {
+        const y = clientY - this.dropZoneShift();
+        let best = null;
+        let bestGap = Infinity;
+        for (const zone of this.dropZones) {
+            const gap = y < zone.top ? zone.top - y : y > zone.bottom ? y - zone.bottom : 0;
+            if (gap < bestGap) {
+                best = zone;
+                bestGap = gap;
+            }
+            if (gap === 0)
+                break; // inside this block; zones are in document order and never overlap
         }
+        if (!best || best.unit === this.blockDragSource)
+            return null;
+        const preferred = y < (best.top + best.bottom) / 2 ? "before" : "after";
+        if (this.isValidMoveTarget(best.unit, preferred))
+            return { zone: best, position: preferred };
+        const other = preferred === "before" ? "after" : "before";
+        return this.isValidMoveTarget(best.unit, other) ? { zone: best, position: other } : null;
     }
     closeBlockMoveMenu(restoreFocus = false) {
         if (!this.blockMoveMenu || !this.blockDragHandle)
@@ -1126,11 +1282,8 @@ export class DocxEditor {
         // 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 candidates = units
-            .filter((el) => el !== source && this.isValidMoveTarget(el, position))
-            .filter((el) => (position === "before"
-            ? units.indexOf(el) < index
-            : units.indexOf(el) > index));
+        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")
@@ -1268,20 +1421,59 @@ export class DocxEditor {
                 const source = this.currentBlockDragSource();
                 return { type: BLOCK_DRAG_TYPE, sourceAnchorId: source ? this.anchorIdOf(source) : undefined };
             },
+            // The browser would otherwise ghost the 26px grip, which says nothing about what is moving.
+            onGenerateDragPreview: ({ nativeSetDragImage }) => {
+                const source = this.currentBlockDragSource();
+                setCustomNativeDragPreview({
+                    nativeSetDragImage,
+                    getOffset: pointerOutsideOfPreview({ x: "14px", y: "10px" }),
+                    render: ({ container }) => {
+                        const chip = doc.createElement("div");
+                        chip.className = "docx-block-drag-preview";
+                        chip.textContent = (source && blockPreviewText(source)) || "Move block";
+                        container.appendChild(chip);
+                        return () => chip.remove();
+                    },
+                });
+            },
             onDragStart: () => {
+                const source = this.currentBlockDragSource();
                 this.blockDragging = true;
                 handle.classList.add("docx-block-dragging");
+                // After the preview snapshot, so the chip is not dimmed too.
+                source?.classList.add("docx-block-drag-source");
                 this.closeBlockMoveMenu();
-                this.refreshBlockMoveTargets(this.currentBlockDragSource());
-                this.refreshBlockDropTargets();
+                this.refreshBlockMoveTargets(source);
+                this.captureDropZones();
             },
             onDrop: () => {
                 this.blockDragging = false;
                 this.blockDragPointerDown = false;
+                this.dropZones = [];
                 handle.classList.remove("docx-block-dragging");
+                // Cleared by selector rather than from a captured reference: a completed move may have
+                // re-rendered the block, and the node that carries the class outlives either handle on it.
+                doc.querySelectorAll(".docx-block-drag-source")
+                    .forEach((el) => el.classList.remove("docx-block-drag-source"));
                 this.hideDropIndicator();
             },
         }));
+        // ONE drop target for the whole flow. Which block a drop belongs to is decided by
+        // `resolveDropAt` from the pointer's vertical position, so the gutter the handle is dragged
+        // down counts as being over the document — see that method.
+        this.blockDragCleanup.push(dropTargetForElements({
+            element: this.editRoot,
+            canDrop: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
+            getData: ({ input }) => {
+                const hit = this.resolveDropAt(input.clientY);
+                return hit
+                    ? { type: BLOCK_DRAG_TYPE, targetAnchorId: hit.zone.anchorId, position: hit.position, zone: hit.zone }
+                    : { type: BLOCK_DRAG_TYPE };
+            },
+            onDragEnter: ({ self }) => this.paintDropIndicator(self.data),
+            onDrag: ({ self }) => this.paintDropIndicator(self.data),
+            onDragLeave: () => this.hideDropIndicator(),
+        }));
         this.blockDragCleanup.push(monitorForElements({
             canMonitor: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
             onDrop: ({ source, location }) => {
@@ -1313,11 +1505,13 @@ export class DocxEditor {
             canScroll: ({ source }) => source.data.type === BLOCK_DRAG_TYPE,
             getAllowedAxis: () => "vertical",
         }));
-        this.refreshBlockDropTargets();
     }
     teardownBlockDrag() {
-        for (const cleanup of this.blockDragTargetCleanup.splice(0))
-            cleanup();
+        this.blockMoveTargetPrefetch?.();
+        this.blockMoveTargetPrefetch = null;
+        this.blockMoveTargetCache.clear();
+        this.dropZones = [];
+        this.dropZoneScroller = null;
         for (const cleanup of this.blockDragCleanup.splice(0))
             cleanup();
         this.blockDragHandle?.remove();
@@ -1413,21 +1607,19 @@ export class DocxEditor {
         bodyRoot.after(this.region.footerBand);
         this.region.refreshAll();
     }
-    /** Continuous (non-paginated) mount: inject the converter's styles + body, wire blocks. */
+    /**
+     * Continuous (non-paginated) mount: inject the converter's styles + body, wire blocks.
+     *
+     * The body always gets its own `.docx-body-flow` wrapper — not only when bands are docked.
+     * It is the sheet: the element the viewport gives page geometry to and zooms, and the one
+     * the bands dock around. Without it the container would have to be both the scrolling host
+     * and the scaled page, which are different boxes.
+     */
     mountHtml(fullHtml) {
         const parsed = new DOMParser().parseFromString(fullHtml, "text/html");
         const styles = Array.from(parsed.querySelectorAll("style"))
             .map((s) => s.outerHTML)
             .join("");
-        if (!this.region) {
-            this.container.innerHTML = styles + parsed.body.innerHTML;
-            this.editRoot = this.container;
-            if (this.options.editable)
-                this.wireBlocks(this.container);
-            this.stampPlanState();
-            return;
-        }
-        // With bands docked, the body flow needs its own wrapper to be the edit root.
         this.container.innerHTML = styles;
         const flow = document.createElement("div");
         flow.className = "docx-body-flow";
@@ -1437,7 +1629,9 @@ export class DocxEditor {
         if (this.options.editable)
             this.wireBlocks(flow);
         this.stampPlanState();
-        this.dockBands(flow);
+        if (this.region)
+            this.dockBands(flow);
+        this.viewport.attach(flow, true);
     }
     /** Paginated mount: flow blocks into page boxes via pagination.ts, wire the page clones. */
     mountPaginated(fullHtml) {
@@ -1473,6 +1667,9 @@ export class DocxEditor {
         // around the page stack, so there is still exactly one addressable node per story paragraph.
         if (this.region)
             this.dockBands(target);
+        // Page boxes already carry the section's dimensions, so the viewport contributes only the
+        // fit zoom — a full page is far wider than a phone, and clipping it is not an option.
+        this.viewport.attach(pageRoot, false);
     }
     wireBlocks(root) {
         root.querySelectorAll("[data-anchor]").forEach((el) => this.wireBlock(el));
@@ -1951,12 +2148,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) ──────
     /**
@@ -2544,15 +2753,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) ───────────────
     /**
@@ -2783,8 +2996,12 @@ export class DocxEditor {
         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)