@parhelia/core 0.1.12926 → 0.1.12928

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

@@ -1,14 +1,14 @@
 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 { 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";
@@ -26,8 +26,10 @@ import { DeviceToolbar } from "./DeviceToolbar";
 import { FullscreenControls } from "../client/ui/FullscreenControls";
 import { toSitecoreDate } from "../utils/sitecoreDate";
 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 +41,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 +607,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 +642,27 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     const directOverlayScrollSyncRef = useRef(false);
     const lastBridgeHoverInteractionRef = useRef(undefined);
     const pendingRefreshScrollRef = 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 +671,17 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 pendingRefreshScrollRef.current = undefined;
             }
         };
+        const currentScroll = getIframeWindowScroll(iframe) ??
+            observedScroll ?? { x: 0, y: 0 };
+        const deltaX = targetScroll.x - currentScroll.x;
+        const deltaY = targetScroll.y - currentScroll.y;
+        // Already at the target: re-asserting the position would be a no-op
+        // except that scrollTo cancels any in-flight smooth scroll (e.g. a
+        // minimap navigation issued while the refresh was still running).
+        if (Math.abs(deltaX) <= 1 && Math.abs(deltaY) <= 1) {
+            clearPendingTarget();
+            return;
+        }
         const restoreStarted = restoreIframeWindowScroll(iframe, targetScroll, {
             maxAttempts: 150,
             onSettled: clearPendingTarget,
@@ -652,17 +690,11 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         if (!restoreStarted) {
             clearPendingTarget();
         }
-        const currentScroll = observedScroll ??
-            getIframeWindowScroll(iframe) ?? { x: 0, y: 0 };
-        const deltaX = targetScroll.x - currentScroll.x;
-        const deltaY = targetScroll.y - currentScroll.y;
-        if (Math.abs(deltaX) > 1 || Math.abs(deltaY) > 1) {
-            bridgeClientRef.current?.sendCommand("scrollBy", {
-                x: deltaX,
-                y: deltaY,
-                behavior: "instant",
-            });
-        }
+        bridgeClientRef.current?.sendCommand("scrollBy", {
+            x: deltaX,
+            y: deltaY,
+            behavior: "instant",
+        });
     }, []);
     const suppressNextSelectionScrollRef = useRef(false);
     // Timestamp (ms) until which selection auto-scroll is suppressed. Held open for
@@ -770,16 +802,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) ??
@@ -828,6 +878,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) {
@@ -852,6 +914,10 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             };
             setIsBridgeInlineEditing(true);
         }
+        logFieldValueDiagnostic("bridge-frame", "tracked inline edit result", {
+            started,
+            nextActiveInlineEdit: activeBridgeInlineEditRef.current,
+        });
         return started;
     }, [
         beginBridgeInlineEdit,
@@ -860,9 +926,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
@@ -876,6 +950,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}`);
         };
@@ -927,12 +1005,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,
@@ -967,10 +1066,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;
     }, []);
@@ -1512,9 +1629,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;
@@ -1576,7 +1695,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                 selectFromBridgeInteraction([]);
             if (isEditableFieldClick) {
                 clearSelectedRangeForEditableClick();
-                await beginTrackedBridgeInlineEdit(effectiveInteraction);
+                beginTrackedBridgeInlineEditAfterSelection(effectiveInteraction);
             }
             else if (interaction.kind === "click") {
                 closeInlineAiIfOpen();
@@ -1584,7 +1703,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;
@@ -1714,7 +1833,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         selectFromBridgeInteraction([componentId]);
         if (isEditableFieldClick) {
             clearSelectedRangeForEditableClick();
-            await beginTrackedBridgeInlineEdit(effectiveInteraction);
+            beginTrackedBridgeInlineEditAfterSelection(effectiveInteraction);
         }
         else {
             closeInlineAiIfOpen();
@@ -1723,6 +1842,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     }, [
         applyBridgeTextCompletion,
         beginTrackedBridgeInlineEdit,
+        beginTrackedBridgeInlineEditAfterSelection,
         clearBridgeTextCompletion,
         endTrackedBridgeFieldFocus,
         requestBridgeTextCompletion,
@@ -1844,9 +1964,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(),
@@ -1859,12 +1982,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);
@@ -1888,11 +2030,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
@@ -1915,7 +2068,13 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
                                 scrollHandlerRef.current(event.payload.geometry.scroll.y);
                             }
                         }
-                        if (pendingRefreshScrollRef.current) {
+                        if (event.payload.scrollIntentApplied) {
+                            // The host already replayed a scroll issued during the refresh
+                            // (e.g. a minimap navigation) — restoring the pre-refresh
+                            // position now would clobber that newer intent.
+                            pendingRefreshScrollRef.current = undefined;
+                        }
+                        else if (pendingRefreshScrollRef.current) {
                             const targetScroll = pendingRefreshScrollRef.current;
                             const observedScroll = event.payload.geometry?.scroll ?? {
                                 x: 0,
@@ -1923,6 +2082,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":
@@ -1933,11 +2104,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") {
@@ -1949,6 +2141,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;
@@ -2021,6 +2231,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         scheduleBridgeGeometryRevision,
         shouldTrackMinimapScroll,
         restorePendingRefreshScroll,
+        completeCanvasRefresh,
     ]);
     useEffect(() => {
         const repository = editContext.itemsRepository;
@@ -2410,6 +2621,8 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             pendingRefreshScrollRef.current ??=
                 getIframeWindowScroll(iframeRef.current) ??
                     latestBridgeScrollRef.current;
+            canvasRefreshInFlightSinceRef.current = Date.now();
+            awaitingHostAppRefreshRenderRef.current = false;
             setShowSpinner(true);
             console.log(initialLoad
                 ? "Initial load - setting iframe src"
@@ -2432,6 +2645,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,
@@ -2439,6 +2654,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
             });
             if (!accepted) {
                 pendingRefreshScrollRef.current = undefined;
+                canvasRefreshInFlightSinceRef.current = null;
                 pageViewContext.setIframeSupportsRefresh(false);
                 runFallbackRefresh();
             }
@@ -2475,8 +2691,18 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
     ]);
     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;
@@ -2484,7 +2710,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).
@@ -2501,7 +2727,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
@@ -2514,24 +2740,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);
@@ -2566,6 +2811,7 @@ function PageViewerFrameContent({ compareView, pageViewContext, editContext, cla
         editContext.scrollIntoView,
         pageViewContext.page,
         pageViewContext.bridgeGeometry,
+        isCanvasRefreshInFlight,
     ]);
     useEffect(() => {
         const handleMessage = (message) => {
@@ -2640,10 +2886,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", {
@@ -2776,6 +3028,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 })] }));
 }