@parhelia/core 0.1.12927 → 0.1.12931

package/dist/editor/page-viewer/PageViewerFrame.js

@@ -1,14 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { BRIDGE_DOM_UPDATED_EVENT, MiniMap } from "./MiniMap";
-import { useEditContext, useEditContextRef, useFieldsEditContext, useFieldsEditContextRef, } from "../client/editContext";
+import { resolveMiniMapVisibility, } from "./minimapVisibility";
+import { useCanvasSelection, useEditContext, useEditContextRef, useFieldsEditContext, useFieldsEditContextRef, } from "../client/editContext";
 import { useSlotContext } from "../views/editorSlotContext";
 import { useDebouncedCallback, useThrottledCallback } from "use-debounce";
 import { PageEditorChrome } from "../page-editor-chrome/PageEditorChrome";
 import { useBridgeInlineEditing, } from "../page-editor-chrome/useBridgeInlineEditing";
 import { getInlineAiAnchorFromBridgeToolbar, getVisibleBridgeToolbarRect, waitForVisibleBridgeToolbarRect, } from "../page-editor-chrome/bridgeInlineFormatToolbarLayout";
 import { IFRAME_OVERLAY_BRIDGE_DRAG_GESTURE_EVENT, IFRAME_OVERLAY_BRIDGE_GEOMETRY_EVENT, IFRAME_OVERLAY_BRIDGE_SCROLL_EVENT, IframeOverlayProvider, } from "../page-editor-chrome/overlay/IframeOverlayProvider";
-import { DEVICE_CHANGE_EVENT, useViewportChangeSignal, } from "./pageViewContext";
+import { CANVAS_REFRESH_COMPLETED_EVENT, DEVICE_CHANGE_EVENT, useViewportChangeSignal, } from "./pageViewContext";
 import uuid from "react-uuid";
 import { cn } from "../../lib/utils";
 import { normalizeMarkerId } from "../utils";
@@ -25,9 +26,12 @@ import { Spinner } from "../ui/Spinner";
 import { DeviceToolbar } from "./DeviceToolbar";
 import { FullscreenControls } from "../client/ui/FullscreenControls";
 import { toSitecoreDate } from "../utils/sitecoreDate";
+import { pickVersionAtDate } from "../utils/versionAtDate";
 import { BridgeClient } from "../bridge/BridgeClient";
+import { beginPerfTrace, isPerfTraceActive, isPerfTraceEnabled, perfTraceStep, } from "../perfTrace";
 import { getSuggestionDisplayValue } from "../reviews/suggestionDisplayValue";
 import { buildBridgeFieldPatchPayload, getBridgeFieldPatchValue, isBridgePatchableTextField, } from "./bridgeFieldPatch";
+import { logFieldValueDiagnostic, summarizeField, summarizeFieldDescriptor, summarizeFieldValue, } from "../fieldValueDiagnostics";
 import { createKeyboardEventFromBridgeInteraction } from "./bridgeKeyboardShortcuts";
 import { formatParentBridgeInjectionDiagnostic, injectParheliaBridgeFromParent, } from "./parentBridgeInjection";
 import { getTextCompletion, normalizeTextCompletion, } from "../services/textCompletionService";
@@ -39,6 +43,9 @@ const BRIDGE_INLINE_EDIT_RELEASE_EVENT = "parhelia:bridge-inline-edit-release";
 const INLINE_AI_CLOSE_EVENT = "inline-ai-close";
 const BRIDGE_INLINE_LINK_OPEN_EVENT = "bridge-inline-link-open";
 const SCROLL_INTO_VIEW_BRIDGE_SOURCE = "scroll-into-view";
+// How long a requested canvas refresh may suppress viewport reactions
+// (selection auto-scroll, scrollIntoView) before it is presumed lost.
+const CANVAS_REFRESH_IN_FLIGHT_MAX_MS = 15000;
 // Suggestions-mode cursor: a text I-beam (the click insertion point) badged with
 // the lucide PenLine icon from the "Suggestions mode" toolbar button. A white
 // halo keeps it visible on any page background; the hotspot is the I-beam centre.
@@ -602,6 +609,7 @@ export function PageViewerFrame(props) {
 function PageViewerFrameContent({ compareView, pageViewContext, editContext, className, slotCloseButton, }) {
     const fieldsContext = useFieldsEditContext();
     const slotContext = useSlotContext();
+    const canvasSelection = useCanvasSelection();
     const pathname = usePathname();
     const pageViewContextRef = useRef(undefined);
     useEffect(() => {
@@ -636,6 +644,42 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     const directOverlayScrollSyncRef = useRef(false);
     const lastBridgeHoverInteractionRef = useRef(undefined);
     const pendingRefreshScrollRef = useRef(undefined);
+    // When the pending refresh scroll was captured, and when the last explicit
+    // scrollBy command (minimap click/wheel) was issued. A capture is only safe
+    // to restore while no explicit command is newer than it: the capture
+    // describes where the canvas happened to be at refresh-request time, and
+    // blindly re-asserting it after the user commanded a scroll yanks the
+    // canvas away from where they sent it.
+    const pendingRefreshScrollCapturedAtRef = useRef(0);
+    const lastExplicitScrollCommandAtRef = useRef(0);
+    // Signature of the last canvas render actually requested (URL sans the
+    // per-request edit_rev nonce, plus the edit revision). When a re-run of the
+    // render effect produces the same signature — e.g. an edit<->suggestions
+    // mode toggle, which changes no host-rendered output — the refresh is
+    // skipped entirely: the bridge learns the mode via setEditorMode, and a
+    // needless refresh would drop scroll position and inline-edit state.
+    const lastRenderSignatureRef = useRef(undefined);
+    // Set when a canvas refresh (bridge patch or full reload) has been requested
+    // and its result has not landed yet. While in flight, bridgeGeometry still
+    // describes the PRE-refresh DOM — a moved component is still measured at its
+    // old position — so viewport-affecting reactions (selection auto-scroll,
+    // scrollIntoView) must wait for the refreshed geometry instead of scrolling
+    // toward stale rects. Timestamped so a refresh that never completes cannot
+    // suppress scrolling forever.
+    const canvasRefreshInFlightSinceRef = useRef(null);
+    // Set when refreshCompleted arrived with applied:"host-app": the page's own
+    // app accepted the refresh but its re-render lands later as DOM mutations.
+    // The in-flight window then stays open until the next structureUpdated.
+    const awaitingHostAppRefreshRenderRef = useRef(false);
+    const isCanvasRefreshInFlight = useCallback(() => {
+        const since = canvasRefreshInFlightSinceRef.current;
+        return (since !== null && Date.now() - since < CANVAS_REFRESH_IN_FLIGHT_MAX_MS);
+    }, []);
+    const completeCanvasRefresh = useCallback(() => {
+        awaitingHostAppRefreshRenderRef.current = false;
+        canvasRefreshInFlightSinceRef.current = null;
+        window.dispatchEvent(new CustomEvent(CANVAS_REFRESH_COMPLETED_EVENT));
+    }, []);
     const restorePendingRefreshScroll = useCallback((iframe, targetScroll, observedScroll) => {
         if (!targetScroll)
             return;
@@ -644,6 +688,15 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 pendingRefreshScrollRef.current = undefined;
             }
         };
+        if (lastExplicitScrollCommandAtRef.current >
+            pendingRefreshScrollCapturedAtRef.current) {
+            // The user commanded a scroll after this position was captured; the
+            // bridge is delivering that newer target. Restoring the stale capture
+            // would fight it (restoreIframeWindowScroll re-asserts for ~150
+            // frames and cancels in-flight smooth scrolls).
+            clearPendingTarget();
+            return;
+        }
         const currentScroll = getIframeWindowScroll(iframe) ??
             observedScroll ?? { x: 0, y: 0 };
         const deltaX = targetScroll.x - currentScroll.x;
@@ -689,6 +742,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     const [loadedIframeSrc, setLoadedIframeSrc] = useState();
     const [scroll, setScroll] = useState(0);
     const [showMiniMap, setShowMiniMap] = useState(false);
+    const miniMapVisibilityMemoryRef = useRef({});
     const [bridgeGeometryRevision, setBridgeGeometryRevision] = useState(0);
     const [bridgeDomRevision, setBridgeDomRevision] = useState(0);
     const bridgeGeometryRevisionRafRef = useRef(null);
@@ -775,16 +829,34 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         // Iframe blur is handled by the bridge inline-edit lifecycle now.
     }, []);
     const sendBeginInlineEdit = useCallback((payload) => {
-        return (bridgeClientRef.current?.sendCommand("beginInlineEdit", payload) ??
-            false);
+        const sent = bridgeClientRef.current?.sendCommand("beginInlineEdit", payload) ??
+            false;
+        logFieldValueDiagnostic("bridge-frame", "beginInlineEdit command", {
+            sent,
+            payload,
+        });
+        return sent;
     }, []);
     const sendCancelInlineEdit = useCallback((payload) => {
-        return (bridgeClientRef.current?.sendCommand("cancelInlineEdit", payload) ??
-            false);
+        const sent = bridgeClientRef.current?.sendCommand("cancelInlineEdit", payload) ??
+            false;
+        logFieldValueDiagnostic("bridge-frame", "cancelInlineEdit command", {
+            sent,
+            payload,
+        });
+        return sent;
     }, []);
     const sendApplyFieldPatchCommand = useCallback((payload) => {
-        return (bridgeClientRef.current?.sendCommand("applyFieldPatch", payload) ??
-            false);
+        const sent = bridgeClientRef.current?.sendCommand("applyFieldPatch", payload) ??
+            false;
+        logFieldValueDiagnostic("bridge-frame", "applyFieldPatch command", {
+            sent,
+            payload: {
+                ...payload,
+                value: summarizeFieldValue(payload.value),
+            },
+        });
+        return sent;
     }, []);
     const sendApplyRichTextCommand = useCallback((payload) => {
         return (bridgeClientRef.current?.sendCommand("applyRichTextCommand", payload) ??
@@ -833,6 +905,18 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         sendApplyFieldPatch: sendApplyFieldPatchCommand,
     });
     const beginTrackedBridgeInlineEdit = useCallback(async (interaction) => {
+        logFieldValueDiagnostic("bridge-frame", "begin tracked inline edit", {
+            previousActiveInlineEdit: activeBridgeInlineEditRef.current,
+            interaction: {
+                kind: interaction.kind,
+                elementKey: interaction.elementKey,
+                fieldId: interaction.fieldId,
+                item: interaction.item,
+                selectedText: summarizeFieldValue(interaction.selectedText),
+                selectionStartOffset: interaction.selectionStartOffset,
+                selectionEndOffset: interaction.selectionEndOffset,
+            },
+        });
         clearActiveBridgeInlineEdit();
         const started = await beginBridgeInlineEdit(interaction);
         if (started && interaction.elementKey && interaction.fieldId) {
@@ -857,6 +941,10 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             };
             setIsBridgeInlineEditing(true);
         }
+        logFieldValueDiagnostic("bridge-frame", "tracked inline edit result", {
+            started,
+            nextActiveInlineEdit: activeBridgeInlineEditRef.current,
+        });
         return started;
     }, [
         beginBridgeInlineEdit,
@@ -865,9 +953,17 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         editContextRef,
     ]);
     const endTrackedBridgeFieldFocus = useCallback(() => {
+        logFieldValueDiagnostic("bridge-frame", "ending tracked field focus", {
+            activeInlineEdit: activeBridgeInlineEditRef.current,
+        });
         clearActiveBridgeInlineEdit();
         endBridgeFieldFocus();
     }, [clearActiveBridgeInlineEdit, endBridgeFieldFocus]);
+    const beginTrackedBridgeInlineEditAfterSelection = useCallback((interaction) => {
+        window.setTimeout(() => {
+            void beginTrackedBridgeInlineEdit(interaction);
+        }, 0);
+    }, [beginTrackedBridgeInlineEdit]);
     useEffect(() => {
         const handleBridgeInlineEditRelease = (event) => {
             const detail = event
@@ -881,6 +977,10 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             if (activeEdit.item && !bridgeItemMatches(activeEdit.item, field.item)) {
                 return;
             }
+            logFieldValueDiagnostic("bridge-frame", "inline edit released by form", {
+                activeInlineEdit: activeEdit,
+                field: summarizeFieldDescriptor(field),
+            });
             clearActiveBridgeInlineEdit();
             bridgePatchSignatureRef.current.delete(`${activeEdit.elementKey}:${activeEdit.fieldId}`);
         };
@@ -932,12 +1032,33 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             },
             mode: showSuggestions ? "suggestions" : "baseline",
         });
-        return {
+        const result = {
             value: showSuggestions ? display.mergedValue : display.baselineValue,
             source: showSuggestions && display.hasSuggestions
                 ? "suggestion-preview"
                 : "real",
         };
+        logFieldValueDiagnostic("bridge-patch", "display value resolved", {
+            showSuggestions,
+            preferRepositoryValue,
+            field: summarizeField(field),
+            structureField: {
+                elementKey: structureField.elementKey,
+                fieldId: structureField.fieldId,
+                item: structureField.item,
+                textContent: summarizeFieldValue(structureField.textContent),
+                isRichText: structureField.isRichText,
+            },
+            itemDescriptor,
+            repositoryValue: summarizeFieldValue(repositoryValue),
+            result: {
+                ...result,
+                value: summarizeFieldValue(result.value),
+            },
+            modifiedFieldCount: fieldsContext?.modifiedFields?.length,
+            suggestedEditCount: editContext.suggestedEdits?.length,
+        });
+        return result;
     }, [
         editContext.mode,
         editContext.showSuggestedEdits,
@@ -972,10 +1093,28 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             source: patch.source ?? "",
             observedTextContent: observedTextContent ?? "",
         });
-        if (bridgePatchSignatureRef.current.get(cacheKey) === signature) {
+        const previousSignature = bridgePatchSignatureRef.current.get(cacheKey);
+        if (previousSignature === signature) {
+            logFieldValueDiagnostic("bridge-patch", "skipped duplicate send", {
+                cacheKey,
+                patch: {
+                    ...patch,
+                    value: summarizeFieldValue(patch.value),
+                },
+                observedTextContent: summarizeFieldValue(observedTextContent),
+            });
             return false;
         }
         bridgePatchSignatureRef.current.set(cacheKey, signature);
+        logFieldValueDiagnostic("bridge-patch", "sending patch", {
+            cacheKey,
+            patch: {
+                ...patch,
+                value: summarizeFieldValue(patch.value),
+            },
+            observedTextContent: summarizeFieldValue(observedTextContent),
+            previousSignature,
+        });
         bridge.sendCommand("applyFieldPatch", patch);
         return true;
     }, []);
@@ -1188,16 +1327,22 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     const requestBridgeTextCompletion = useCallback(async (interaction, force = false) => {
         const editor = editContextRef.current;
         if (!editor?.enableCompletions || editor.mode === "preview") {
+            console.debug("[Parhelia] text completion skipped", JSON.stringify({
+                enableCompletions: editor?.enableCompletions,
+                mode: editor?.mode,
+            }));
             clearBridgeTextCompletion();
             return;
         }
         const fieldDescriptor = await resolveBridgeFieldDescriptor(interaction);
         if (!fieldDescriptor) {
+            console.debug("[Parhelia] text completion skipped: no field descriptor", JSON.stringify({ elementKey: interaction.elementKey }));
             clearBridgeTextCompletion();
             return;
         }
         const field = await editor.itemsRepository.getField(fieldDescriptor);
         if (!field) {
+            console.debug("[Parhelia] text completion skipped: field not in repository", JSON.stringify(fieldDescriptor));
             clearBridgeTextCompletion();
             return;
         }
@@ -1212,24 +1357,15 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         if (!elementKey ||
             !hostFieldId ||
             !isBridgePatchableTextField(field, isRichText)) {
+            console.debug("[Parhelia] text completion skipped: not patchable", JSON.stringify({
+                elementKey,
+                hostFieldId,
+                fieldType: field.type,
+                isRichText,
+            }));
             clearBridgeTextCompletion();
             return;
         }
-        const selectedText = selectionMatches && typeof bridgeSelection?.text === "string"
-            ? bridgeSelection.text
-            : typeof interaction.selectedText === "string"
-                ? interaction.selectedText
-                : "";
-        const selectionStartOffset = selectionMatches && typeof bridgeSelection?.startOffset === "number"
-            ? bridgeSelection.startOffset
-            : typeof interaction.selectionStartOffset === "number"
-                ? interaction.selectionStartOffset
-                : undefined;
-        const selectionEndOffset = selectionMatches && typeof bridgeSelection?.endOffset === "number"
-            ? bridgeSelection.endOffset
-            : typeof interaction.selectionEndOffset === "number"
-                ? interaction.selectionEndOffset
-                : undefined;
         const liveSelectionStartOffset = typeof interaction.selectionStartOffset === "number"
             ? interaction.selectionStartOffset
             : undefined;
@@ -1242,6 +1378,19 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         const bridgeSelectionEndOffset = selectionMatches && typeof bridgeSelection?.endOffset === "number"
             ? bridgeSelection?.endOffset
             : undefined;
+        const selectedText = typeof interaction.selectedText === "string"
+            ? interaction.selectedText
+            : selectionMatches && typeof bridgeSelection?.text === "string"
+                ? bridgeSelection.text
+                : "";
+        const selectionStartOffset = liveSelectionStartOffset ??
+            (selectionMatches && typeof bridgeSelection?.startOffset === "number"
+                ? bridgeSelection.startOffset
+                : undefined);
+        const selectionEndOffset = liveSelectionEndOffset ??
+            (selectionMatches && typeof bridgeSelection?.endOffset === "number"
+                ? bridgeSelection.endOffset
+                : undefined);
         const activeInlineEdit = activeBridgeInlineEditRef.current;
         const activeInlineEditMatches = !!(activeInlineEdit &&
             activeInlineEdit.elementKey === elementKey &&
@@ -1267,7 +1416,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 !hasLiveInteractionOffsets ||
                 (bridgeSelectionStartOffset === liveSelectionStartOffset &&
                     bridgeSelectionEndOffset === liveSelectionEndOffset);
-            const metadataMatchesLiveOffsets = !selectionSnapshotMatchesLiveOffsets ||
+            const metadataMatchesLiveOffsets = selectionSnapshotMatchesLiveOffsets ||
                 ((contextBefore?.length ?? 0) === interaction.selectionStartOffset &&
                     (contextBefore?.length ?? 0) + selectedText.length ===
                         interaction.selectionEndOffset);
@@ -1378,6 +1527,12 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                     return;
                 }
             }
+            // Escape leaves insert mode, same as in the editor window itself
+            if (interaction.key === "Escape" &&
+                editContextRef.current?.insertMode) {
+                editContextRef.current.setInsertMode(false);
+                return;
+            }
             if (isBridgeTextCompletionApplyShortcut(interaction)) {
                 if (bridgeTextCompletionRef.current) {
                     applyBridgeTextCompletion();
@@ -1517,9 +1672,11 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         if (!editor)
             return;
         const selectFromBridgeInteraction = (ids) => {
-            if (!bridgeComponentSelectionsMatch(editor.selection, ids)) {
+            const unchanged = bridgeComponentSelectionsMatch(editor.getSelection(), ids);
+            if (!unchanged) {
                 suppressNextSelectionScrollRef.current = true;
             }
+            perfTraceStep("frame:select-dispatched", { ids, unchanged });
             editor.select(ids);
         };
         let effectiveInteraction = interaction;
@@ -1581,7 +1738,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 selectFromBridgeInteraction([]);
             if (isEditableFieldClick) {
                 clearSelectedRangeForEditableClick();
-                await beginTrackedBridgeInlineEdit(effectiveInteraction);
+                beginTrackedBridgeInlineEditAfterSelection(effectiveInteraction);
             }
             else if (interaction.kind === "click") {
                 closeInlineAiIfOpen();
@@ -1589,7 +1746,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             }
             return;
         }
-        const currentSelection = editor.selection || [];
+        const currentSelection = editor.getSelection();
         if (interaction.kind === "contextMenu") {
             if (pageViewContextRef.current) {
                 pageViewContextRef.current.bridgeInteraction = effectiveInteraction;
@@ -1719,7 +1876,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         selectFromBridgeInteraction([componentId]);
         if (isEditableFieldClick) {
             clearSelectedRangeForEditableClick();
-            await beginTrackedBridgeInlineEdit(effectiveInteraction);
+            beginTrackedBridgeInlineEditAfterSelection(effectiveInteraction);
         }
         else {
             closeInlineAiIfOpen();
@@ -1728,6 +1885,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     }, [
         applyBridgeTextCompletion,
         beginTrackedBridgeInlineEdit,
+        beginTrackedBridgeInlineEditAfterSelection,
         clearBridgeTextCompletion,
         endTrackedBridgeFieldFocus,
         requestBridgeTextCompletion,
@@ -1849,9 +2007,12 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                             suggestionsCursorActive: !activeBridgeInlineEditRef.current &&
                                 (editContextRef.current?.mode === "suggestions" ||
                                     !!editContextRef.current?.showSuggestedEdits),
-                            selectedComponentIds: editContextRef.current?.selection ?? [],
+                            selectedComponentIds: editContextRef.current?.getSelection() ?? [],
                             featureFlags: {
                                 crossOriginBridge: true,
+                                // Lets the host emit its own perf logs + interaction perf
+                                // timestamps without needing a flag in the iframe's origin.
+                                perfTrace: isPerfTraceEnabled(),
                             },
                             version: bridge.getDiagnostics().editorVersion,
                             acknowledgedCapabilities: bridge.getAcknowledgedCapabilities(),
@@ -1864,12 +2025,31 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                         }
                         break;
                     case "structureUpdated":
+                        if (isPerfTraceActive()) {
+                            perfTraceStep("frame:structure-updated-received", {
+                                components: event.payload.structure.components.length,
+                                fields: event.payload.structure.fields.length,
+                                transportMs: Date.now() - event.timestamp,
+                            });
+                        }
                         pageViewContext.setBridgeStructure(event.payload.structure);
+                        if (awaitingHostAppRefreshRenderRef.current) {
+                            // First structure change after a host-app refresh: the page's
+                            // own re-render has reached the DOM — the refresh is now truly
+                            // complete.
+                            completeCanvasRefresh();
+                        }
                         break;
                     case "pageSkeletonUpdated":
                         pageViewContext.setPageSkeleton(event.payload.pageSkeleton);
                         break;
                     case "geometryUpdated": {
+                        if (isPerfTraceActive()) {
+                            perfTraceStep("frame:geometry-updated-received", {
+                                targets: event.payload.geometry.targets.length,
+                                transportMs: Date.now() - event.timestamp,
+                            });
+                        }
                         latestBridgeScrollRef.current = event.payload.geometry.scroll;
                         pageViewContext.bridgeGeometry = event.payload.geometry;
                         pageViewContext.setBridgeGeometry(event.payload.geometry);
@@ -1893,11 +2073,22 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                         window.dispatchEvent(new CustomEvent(BRIDGE_DOM_UPDATED_EVENT));
                         break;
                     case "refreshStarted":
+                        logFieldValueDiagnostic("bridge-frame", "refresh started", {
+                            revision: event.payload.revision,
+                            activeInlineEdit: activeBridgeInlineEditRef.current,
+                            patchSignatureCount: bridgePatchSignatureRef.current.size,
+                        });
                         clearBridgeTextCompletion();
                         clearBridgePatchSignatures();
                         clearActiveBridgeInlineEdit();
                         break;
                     case "refreshCompleted":
+                        logFieldValueDiagnostic("bridge-frame", "refresh completed", {
+                            activeInlineEdit: activeBridgeInlineEditRef.current,
+                            hasStructure: !!event.payload.structure,
+                            hasGeometry: !!event.payload.geometry,
+                            structureFieldCount: event.payload.structure?.fields.length,
+                        });
                         // Runtime refresh replaces host DOM without a new bridge ready event.
                         // Field patches sent during the refresh window may have been cached
                         // against the previous DOM generation, so force the refreshed host to
@@ -1934,6 +2125,18 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                             };
                             restorePendingRefreshScroll(iframe, targetScroll, observedScroll);
                         }
+                        if (event.payload.applied === "host-app") {
+                            // The page's own app (e.g. a Next.js rendering host) accepted
+                            // the refresh, but its re-render lands later as ordinary DOM
+                            // mutations. Completing now would reopen viewport reactions
+                            // (selection auto-scroll, scrollIntoView, the inserting
+                            // indicator) while geometry still describes the pre-edit DOM —
+                            // wait for the mutation-driven structureUpdated instead.
+                            awaitingHostAppRefreshRenderRef.current = true;
+                        }
+                        else {
+                            completeCanvasRefresh();
+                        }
                         setShowSpinner(false);
                         break;
                     case "selectionChanged":
@@ -1944,11 +2147,32 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                         if (event.payload.elementKey && event.payload.fieldId) {
                             setIsBridgeInlineEditing(true);
                         }
+                        logFieldValueDiagnostic("bridge-frame", "fieldValueChanged event", {
+                            elementKey: event.payload.elementKey,
+                            fieldId: event.payload.fieldId,
+                            item: event.payload.item,
+                            isRichText: event.payload.isRichText,
+                            value: summarizeFieldValue(event.payload.value),
+                            activeInlineEdit: activeBridgeInlineEditRef.current,
+                        });
                         handleBridgeFieldValueChanged(event.payload);
                         break;
                     case "inlineEditEnded":
+                        logFieldValueDiagnostic("bridge-frame", "inlineEditEnded event", {
+                            reason: event.payload.reason,
+                            elementKey: event.payload.elementKey,
+                            fieldId: event.payload.fieldId,
+                            item: event.payload.item,
+                            isRichText: event.payload.isRichText,
+                            value: summarizeFieldValue(event.payload.value),
+                            activeInlineEdit: activeBridgeInlineEditRef.current,
+                        });
                         handleBridgeInlineEditEnded(event.payload);
                         clearActiveBridgeInlineEdit();
+                        logFieldValueDiagnostic("bridge-frame", "active inline edit cleared after end", {
+                            fieldId: event.payload.fieldId,
+                            reason: event.payload.reason,
+                        });
                         break;
                     case "interaction":
                         if (event.payload.kind === "hover") {
@@ -1960,6 +2184,24 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                         else {
                             lastBridgeHoverInteractionRef.current = undefined;
                         }
+                        if (isPerfTraceEnabled() &&
+                            (event.payload.kind === "click" ||
+                                event.payload.kind === "doubleClick" ||
+                                event.payload.kind === "contextMenu")) {
+                            // Backdate to the host's DOM-event timestamp when available so
+                            // host-side dispatch (hit-test + deferred-click debounce) is
+                            // part of the waterfall; the envelope timestamp is when the
+                            // host posted the message.
+                            const eventAt = event.payload.perf?.eventAt;
+                            beginPerfTrace(`select-${event.payload.kind}`, {
+                                componentId: event.payload.componentId,
+                                fieldId: event.payload.fieldId,
+                                hostDispatchMs: eventAt !== undefined
+                                    ? event.timestamp - eventAt
+                                    : "n/a (host without perf tracing)",
+                                transportMs: Date.now() - event.timestamp,
+                            }, eventAt ?? event.timestamp);
+                        }
                         pageViewContext.setBridgeInteraction(event.payload);
                         void handleBridgeInteraction(event.payload, iframe);
                         break;
@@ -2032,6 +2274,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         scheduleBridgeGeometryRevision,
         shouldTrackMinimapScroll,
         restorePendingRefreshScroll,
+        completeCanvasRefresh,
     ]);
     useEffect(() => {
         const repository = editContext.itemsRepository;
@@ -2245,7 +2488,11 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         };
         pageViewContext.requestBridgeGeometry = requestBridgeGeometry;
         const requestBridgeScrollBy = (payload) => {
-            return bridgeClientRef.current?.sendCommand("scrollBy", payload) ?? false;
+            const accepted = bridgeClientRef.current?.sendCommand("scrollBy", payload) ?? false;
+            if (accepted) {
+                lastExplicitScrollCommandAtRef.current = Date.now();
+            }
+            return accepted;
         };
         const requestBridgeRichTextCommand = (payload) => {
             return (bridgeClientRef.current?.sendCommand("applyRichTextCommand", payload) ??
@@ -2331,24 +2578,24 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         const bridgeDom = pageViewContextRef.current?.bridgeDom;
         const contentHeight = bridgeDom?.scrollHeight ??
             getBridgeGeometryDocumentSize(bridgeGeometry)?.height;
+        const contentWidth = bridgeDom?.viewport.width ?? bridgeGeometry?.viewport.width;
         const clientHeight = iframe.clientHeight;
         if (!contentHeight || !clientHeight)
             return;
-        const upperThreshold = clientHeight + 100; // show minimap if content exceeds this height
         // Check if minimap is enabled in settings and user controls
         const minimapEnabled = editContext.parheliaSettings?.showMinimap !== false &&
             editContext.showMinimap;
         if (!minimapEnabled) {
+            miniMapVisibilityMemoryRef.current = {};
             if (showMiniMap) {
                 setShowMiniMap(false);
             }
             return;
         }
-        if (showMiniMap) {
-            return;
-        }
-        if (contentHeight > upperThreshold) {
-            setShowMiniMap(true);
+        const resolution = resolveMiniMapVisibility(showMiniMap, { contentHeight, contentWidth, clientHeight }, miniMapVisibilityMemoryRef.current);
+        miniMapVisibilityMemoryRef.current = resolution.memory;
+        if (resolution.visible !== showMiniMap) {
+            setShowMiniMap(resolution.visible);
         }
     }, 100);
     useEffect(() => {
@@ -2369,6 +2616,13 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             editContextRef.current?.setSelectedRange(undefined);
         }
     }, [editContext.mode]);
+    // Version that is valid at the active preview date (based on the versions'
+    // publishing restrictions). Derived outside the refresh effect so the effect
+    // re-runs on the resolved version number, not on itemVersions' identity.
+    const previewDateVersion = editContext.mode === "preview" && editContext.previewDate
+        ? pickVersionAtDate(editContext.itemVersions, editContext.previewDate)
+            ?.version
+        : undefined;
     useEffect(() => {
         if (!pageItemDescriptor ||
             !pageViewContext.editUrl ||
@@ -2387,7 +2641,23 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             renderUrl.searchParams.set("parhelia_session", editContext.sessionId);
         }
         if (editContext.mode === "preview" && editContext.previewDate) {
-            renderUrl.searchParams.delete("sc_version");
+            // Pin the version that is valid at the preview date. The render URL can
+            // carry the version pin as `sc_version`, `version`, or both; leaving
+            // either behind keeps the page pinned to the previously selected
+            // version, so every pin present must be rewritten. Only update params
+            // that exist: proxied host URLs must not gain sc_* params (they break
+            // Sitecore's httpRequestBegin pipeline — see applyParheliaRenderContext).
+            // sc_date stays on the URL for hosts that resolve datasources by date.
+            if (previewDateVersion != null) {
+                if (renderUrl.searchParams.has("sc_version"))
+                    renderUrl.searchParams.set("sc_version", String(previewDateVersion));
+                if (renderUrl.searchParams.has("version"))
+                    renderUrl.searchParams.set("version", String(previewDateVersion));
+            }
+            else {
+                renderUrl.searchParams.delete("sc_version");
+                renderUrl.searchParams.delete("version");
+            }
             renderUrl.searchParams.set("sc_date", toSitecoreDate(editContext.previewDate));
         }
         // Layout-mode marker. Only set when editing shared layout, paired with the
@@ -2406,21 +2676,44 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         const currentIframeOrigin = getUrlOrigin(currentIframeUrl);
         const renderUrlIsCrossOrigin = renderUrl.origin !== window.location.origin;
         const iframeOriginChanged = !!(currentIframeOrigin && currentIframeOrigin !== renderUrl.origin);
+        // Proxied host URLs carry the version pin as `version` (sc_* params are
+        // stripped), so consider both param names when detecting a change.
+        const getUrlVersionPin = (url) => url.searchParams.get("sc_version") ?? url.searchParams.get("version");
         const currentVersion = currentIframeUrl
-            ? new URL(currentIframeUrl).searchParams.get("sc_version")
+            ? getUrlVersionPin(new URL(currentIframeUrl))
             : null;
-        const newVersion = renderUrl.searchParams.get("sc_version");
+        const newVersion = getUrlVersionPin(renderUrl);
         const versionChanged = (currentVersion !== null || newVersion !== null) &&
             currentVersion !== newVersion;
         const initialLoad = currentItemDescriptor?.id !== pageItemDescriptor.id ||
             currentItemDescriptor?.language !== pageItemDescriptor.language ||
             currentItemDescriptor?.version !== pageItemDescriptor.version;
         const shouldUseIframeSrcReload = initialLoad || pageViewContext.fullscreen || iframeOriginChanged;
+        const signatureUrl = new URL(renderUrl.toString());
+        signatureUrl.searchParams.delete("edit_rev");
+        const renderSignature = `${signatureUrl.toString()}|rev:${editContext.revision}`;
+        // Only skip when a live bridge confirms the last refresh actually reached
+        // the host. Before the bridge is connected, re-runs must keep going: the
+        // retry/fallback-reload path below is what recovers a canvas whose first
+        // load raced the bridge injection.
+        if (!shouldUseIframeSrcReload &&
+            !versionChanged &&
+            lastRenderSignatureRef.current === renderSignature &&
+            bridgeClientRef.current?.supportsCapability("refresh")) {
+            setCurrentItemDescriptor(pageItemDescriptor);
+            return;
+        }
         function runFallbackRefresh() {
+            lastRenderSignatureRef.current = renderSignature;
             pageViewContext.setIframeSupportsRefresh(false);
-            pendingRefreshScrollRef.current ??=
-                getIframeWindowScroll(iframeRef.current) ??
-                    latestBridgeScrollRef.current;
+            if (!pendingRefreshScrollRef.current) {
+                pendingRefreshScrollRef.current =
+                    getIframeWindowScroll(iframeRef.current) ??
+                        latestBridgeScrollRef.current;
+                pendingRefreshScrollCapturedAtRef.current = Date.now();
+            }
+            canvasRefreshInFlightSinceRef.current = Date.now();
+            awaitingHostAppRefreshRenderRef.current = false;
             setShowSpinner(true);
             console.log(initialLoad
                 ? "Initial load - setting iframe src"
@@ -2433,9 +2726,11 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             setIframeSrc(renderUrl.toString());
         }
         function runBridgeRefresh() {
+            lastRenderSignatureRef.current = renderSignature;
             pendingRefreshScrollRef.current =
                 getIframeWindowScroll(iframeRef.current) ??
                     latestBridgeScrollRef.current;
+            pendingRefreshScrollCapturedAtRef.current = Date.now();
             const bridge = bridgeClientRef.current;
             if (!bridge?.supportsCapability("refresh")) {
                 runFallbackRefresh();
@@ -2443,6 +2738,8 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             }
             console.log("Bridge - requesting iframe refresh");
             pageViewContext.setIframeSupportsRefresh(true);
+            canvasRefreshInFlightSinceRef.current = Date.now();
+            awaitingHostAppRefreshRenderRef.current = false;
             const accepted = bridge.sendCommand("refresh", {
                 url: renderUrl.toString(),
                 revision: editContext.revision,
@@ -2450,6 +2747,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             });
             if (!accepted) {
                 pendingRefreshScrollRef.current = undefined;
+                canvasRefreshInFlightSinceRef.current = null;
                 pageViewContext.setIframeSupportsRefresh(false);
                 runFallbackRefresh();
             }
@@ -2481,13 +2779,24 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         pageViewContext.fullscreen,
         editContext.mode,
         editContext.previewDate,
+        previewDateVersion,
         editContext.sessionId,
         editContext.layoutMode,
     ]);
     useEffect(() => {
         if (fieldsContext?.focusedField) {
-            if (editContext.selection.length > 0 &&
-                fieldsContext.focusedField.item.id !== editContext.selection[0])
+            // A refresh is being applied: the field's rect still describes the
+            // pre-edit DOM (after a move, its old position — where the drag
+            // started), so scrolling now would yank the canvas to a stale spot.
+            // This fires on the post-operation auto-focus of the moved/added
+            // component; a genuine user focus during a refresh loses one
+            // auto-scroll, which is the lesser evil.
+            if (isCanvasRefreshInFlight())
+                return;
+            // Event-time read: this effect is keyed on focusedField, not selection.
+            const currentSelection = editContext.getSelection();
+            if (currentSelection.length > 0 &&
+                fieldsContext.focusedField.item.id !== currentSelection[0])
                 return;
             const bounds = findBridgeFieldDocumentBounds(pageViewContextRef.current?.bridgeGeometry, fieldsContext.focusedField);
             const activePageViewContext = pageViewContextRef.current;
@@ -2495,7 +2804,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 scrollBridgeBoundsIntoView(activePageViewContext, bounds, latestBridgeScrollRef.current);
             }
         }
-    }, [fieldsContext?.focusedField]);
+    }, [fieldsContext?.focusedField, isCanvasRefreshInFlight]);
     // Drive the selection-scroll suppression window from the drag lifecycle.
     // Declared BEFORE the selection-scroll effect so it runs first in the same
     // commit (when a drop changes both dragObject and selection at once).
@@ -2512,7 +2821,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         }
     }, [editContext.dragObject]);
     useEffect(() => {
-        const selectionKey = editContext.selection.join("|");
+        const selectionKey = canvasSelection.join("|");
         const selectionChanged = selectionKey !== lastScrolledSelectionKeyRef.current;
         lastScrolledSelectionKeyRef.current = selectionKey;
         // The effect also re-runs when focusedField changes (e.g. a field blurs
@@ -2525,24 +2834,43 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             suppressNextSelectionScrollRef.current = false;
             return;
         }
+        // Programmatic selections (the drop target's parent, the post-operation
+        // focus of a moved/added component) arm this suppression at their source:
+        // their targets may still measure at pre-edit geometry, and unlike user
+        // clicks they carry no intent to see the component. Deterministic — no
+        // time window to lose against a slow operation or frozen host.
+        if (editContext.consumeNextSelectionAutoScrollSuppression?.())
+            return;
         // Suppressed during a drag and briefly after it ends. The drag owns
         // scrolling, and the drop's re-selection must not jump the page away from
         // where the user dropped (toward stale pre-move geometry).
         if (Date.now() < suppressSelectionScrollUntilRef.current)
             return;
-        if (!fieldsContext?.focusedField && editContext.selection.length > 0) {
-            const lastSelectedComponent = getComponentById(editContext.selection[editContext.selection.length - 1], pageViewContextRef.current.page);
+        // Suppressed while a refresh is applying: geometry still measures the
+        // pre-refresh DOM (a just-moved component still sits at its old rect), so
+        // scrolling now would target a stale position. The refresh restore owns
+        // the viewport until the refreshed geometry lands.
+        if (isCanvasRefreshInFlight())
+            return;
+        if (!fieldsContext?.focusedField && canvasSelection.length > 0) {
+            const lastSelectedComponent = getComponentById(canvasSelection[canvasSelection.length - 1], pageViewContextRef.current.page);
             if (lastSelectedComponent) {
                 editContext.setScrollIntoView(lastSelectedComponent.id);
             }
         }
-    }, [editContext.selection, fieldsContext?.focusedField]);
+    }, [canvasSelection, fieldsContext?.focusedField, isCanvasRefreshInFlight]);
     useEffect(() => {
         if (!editContext.scrollIntoView)
             return;
         const activePageViewContext = pageViewContextRef.current;
         if (!activePageViewContext)
             return;
+        // Defer (without consuming the request) while a refresh is applying:
+        // resolving now would measure the target against pre-refresh geometry and
+        // scroll to a stale rect. The effect re-runs when the refreshed geometry
+        // arrives (bridgeGeometry dependency) and resolves against fresh bounds.
+        if (isCanvasRefreshInFlight())
+            return;
         const scrollTarget = editContext.scrollIntoView;
         const requestState = scrollIntoViewRequestRef.current;
         const signature = getScrollIntoViewSignature(scrollTarget);
@@ -2577,6 +2905,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         editContext.scrollIntoView,
         pageViewContext.page,
         pageViewContext.bridgeGeometry,
+        isCanvasRefreshInFlight,
     ]);
     useEffect(() => {
         const handleMessage = (message) => {
@@ -2651,10 +2980,16 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         };
     }, [iframeElement]);
     useEffect(() => {
-        bridgeClientRef.current?.sendCommand("setSelection", {
-            componentIds: editContext.selection,
+        const sent = bridgeClientRef.current?.sendCommand("setSelection", {
+            componentIds: canvasSelection,
         });
-    }, [editContext.selection]);
+        if (isPerfTraceActive()) {
+            perfTraceStep("frame:setSelection-command-sent", {
+                ids: canvasSelection,
+                sent: sent ?? false,
+            });
+        }
+    }, [canvasSelection]);
     useEffect(() => {
         const bridge = bridgeClientRef.current;
         bridge?.sendCommand("setPreviewMode", {
@@ -2787,6 +3122,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                                         if (pendingRefreshScrollRef.current) {
                                             restorePendingRefreshScroll(iframeRef.current, pendingRefreshScrollRef.current);
                                         }
+                                        completeCanvasRefresh();
                                     }
                                 } }), iframeElement && (_jsx(IframeOverlayProvider, { iframe: iframeElement, mode: "scrolling", scrollScale: 1, visualScale: 1, invalidationKey: `${zoom}:${bridgeGeometryRevision}`, deferredInvalidationMs: ZOOM_TRANSITION_MS + 50, bleed: { top: 2, bottom: 2, left: 2 }, children: _jsx(PageEditorChrome, { iframe: iframeElement, compareView: compareView, pageViewContext: pageViewContext, onBridgeRichTextCommand: sendApplyRichTextCommand }) })), pageViewContext.deviceHeight && pageViewContext.device && (_jsx("div", { className: "bg-neutral-grey-5 relative z-40 h-full w-full" }))] }), shouldRenderMiniMap && (_jsx(MiniMap, { compareView: compareView, scroll: scroll, mainViewIframeRef: iframeRef, pageViewContext: pageViewContext })), showSpinner && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bg-neutral-grey-5/50 absolute top-0 left-0 h-full w-full" }), _jsx("div", { className: "absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 transform", children: _jsx(Spinner, {}) })] }))] }), _jsx(FieldActionsOverlay, { ref: fieldActionsOverlay, generatorButtons: contextMenuFieldButtons, onActionClick: handleActionClick, onParameterizedActionExecute: handleParameterizedActionExecute, currentOverlay: editContext?.currentOverlay, fieldId: contextMenuField?.fieldId || "", setCurrentOverlay: editContext?.setCurrentOverlay || (() => { }), preSelectedAction: preSelectedAction })] }));
 }