@parhelia/core 0.4.12825 → 0.4.12871

package/dist/editor/client/EditorShell.js

@@ -1,5 +1,6 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRepositoryItemRefresh } from "./hooks/useRepositoryItemRefresh";
 import React, { useState, useEffect, useLayoutEffect, useRef, useCallback, useMemo, startTransition, } from "react";
 import { toast } from "sonner";
 import { isPerfTraceActive, perfTracePaintStep, perfTraceStep, } from "../perfTrace";
@@ -20,8 +21,10 @@ import { onSocketReconnect as onAgentSocketReconnect } from "../services/agentSu
 import { useEditorWebSocket } from "./hooks/useEditorWebSocket";
 import { useClientInfoRegistration } from "./hooks/useClientInfoRegistration";
 import { getEditorRealtime } from "./realtime/realtimeTransport";
-import { createEditorSocketDiagnostics, } from "./socketDiagnostics";
+import { createEditorSocketDiagnostics } from "./socketDiagnostics";
+import { createValueStore, useValueStore } from "./valueStore";
 import { localStorageService } from "../services/localStorageService";
+import { loadPersistedClipboard, persistClipboard, readClipboardFromStorageEvent, } from "./clipboardStorage";
 import { useSocketMessageHandler } from "./hooks/useSocketMessageHandler";
 import "react-json-view-lite/dist/index.css";
 import { MediaSelector, } from "../media-selector/MediaSelector";
@@ -41,6 +44,7 @@ import { filterRemovedComments } from "../reviews/commentState";
 import { post } from "../services/serviceHelper";
 import { CONTENT_TREE_SIDEBAR_ID } from "../sidebar/contentTreeConstants";
 import { PageViewerFrame } from "../page-viewer/PageViewerFrame";
+import { isRenderingOnCanvas } from "../page-viewer/renderingChanges";
 import { useItemsRepository } from "./itemsRepository";
 import { logFieldValueDiagnostic, summarizeFieldDescriptor, } from "../fieldValueDiagnostics";
 import { Spinner } from "../ui/Spinner";
@@ -56,13 +60,14 @@ import { buildBridgeInsertTextCommand } from "../ai/bridgeInlineTextReplace";
 import { GuidanceOverlay } from "../ai/GuidanceOverlay";
 import { AgentDialogHandler } from "../ai/dialogs";
 import { setActiveAgentConversation } from "../ai/useActiveAgentConversation";
-import { CANVAS_REFRESH_COMPLETED_EVENT, usePageViewContext, } from "../page-viewer/pageViewContext";
+import { CANVAS_REFRESH_COMPLETED_EVENT, usePageViewContext, usePageViewState, usePageViewStates, } from "../page-viewer/pageViewContext";
 import { QuickItemSwitcher } from "../QuickItemSwitcher";
 import { useEditorSlotContext, } from "../views/editorSlotContext";
 import { getComments, getAvailableCommentTags, } from "../services/reviewsService";
 import { useReviews } from "../reviews/useReviews";
 import { closeActiveCommentPopover, COMMENT_POPOVER_OVERLAY_ID, } from "../reviews/CommentPopover";
 import { isSuggestedEditRemoved } from "../reviews/suggestedEditState";
+import { useLeftoverReviewIdCleanup } from "../reviews/reviewUrlScope";
 import { COMMENT_TRANSIENT_ELEMENT_KEY, COMMENT_TRANSIENT_SELECTION_RECT, } from "../reviews/commentTransientSelection";
 import uuid from "react-uuid";
 import { flushSync } from "react-dom";
@@ -188,16 +193,28 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [selectedForInsertion, setSelectedForInsertion] = useState("");
     const [refreshCompletedFlag, setRefreshCompletedFlag] = useState(false);
     const [isRefreshing, setIsRefreshing] = useState(false);
-    // Token incremented by editor slots when their page model finishes building.
-    // Forces the isRefreshingEffect to re-evaluate with the fresh page from the mutable slot ref.
-    const [pageModelReadyToken, setPageModelReadyToken] = useState(0);
-    const notifyPageModelReady = useCallback(() => setPageModelReadyToken((c) => c + 1), []);
     const [dragObject, setDragObject] = useState();
     // Pointer gestures can start and end between React's commit and passive-effect
     // phases. Keep the event-time payload synchronous so a bridge listener from
     // the preceding render cannot observe a stale `dragObject` closure at drop.
     const dragObjectRef = useRef(undefined);
-    const [clipboard, setClipboard] = useState(null);
+    // The clipboard outlives page switches and reloads (and syncs across tabs) so a
+    // component copied on one page can be pasted on another.
+    const [clipboard, setClipboard] = useState(() => loadPersistedClipboard());
+    useEffect(() => {
+        persistClipboard(clipboard);
+    }, [clipboard]);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const handleStorage = (event) => {
+            const next = readClipboardFromStorageEvent(event);
+            if (next !== undefined)
+                setClipboard(next);
+        };
+        window.addEventListener("storage", handleStorage);
+        return () => window.removeEventListener("storage", handleStorage);
+    }, []);
     // media selection handled by useMediaSelector hook
     const [scrollIntoView, setScrollIntoView] = useState();
     const confirmationDialogRef = useRef(null);
@@ -236,11 +253,32 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [item, setItem] = useState();
     const [focusedField, setFocusedField] = useState();
     const focusedFieldRef = useRef(undefined);
-    const [selectedRange, setSelectedRange] = useState();
+    // A store, not state: a text selection is republished on every step of a
+    // canvas drag or Shift+Arrow, and a change of the EditContext value
+    // re-renders every consumer in the editor (~300 ms on a large page).
+    // Components that render from it subscribe with useSelectedRange().
+    const [selectedRangeStore] = useState(() => createValueStore(undefined));
     const lastTextSelectionRangeRef = useRef(undefined);
+    // Caret-only form positions change on every focus, click and typing pause,
+    // but are only read when something inserts at the caret, so they are not
+    // published at all. Whichever of the two was recorded last wins.
+    const caretRangeRef = useRef(undefined);
+    const setSelectedRange = useCallback((next) => {
+        caretRangeRef.current = undefined;
+        selectedRangeStore.set(next);
+        const published = selectedRangeStore.get();
+        if (isUsableTextSelectionRange(published)) {
+            lastTextSelectionRangeRef.current = published;
+        }
+    }, [selectedRangeStore]);
+    const setCaretRange = useCallback((range) => {
+        caretRangeRef.current = range;
+        selectedRangeStore.set(undefined);
+    }, [selectedRangeStore]);
     const [validating, setValidating] = useState(false);
     const [inserting, setInserting] = useState();
     const [removingComponentIds, setRemovingComponentIds] = useState([]);
+    const [recentConversion, setRecentConversion] = useState();
     const insertingSequenceRef = useRef(0);
     // Armed by selectWithoutAutoScroll for programmatic selections (drop
     // target's parent, post-operation focus): the canvas selection-scroll
@@ -314,7 +352,11 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [activeFieldActions, setActiveFieldActions] = useState([]);
     const fieldEditorPopupRef = React.useRef(null);
     const [validationResult, setValidationResult] = useState();
-    const [editHistory, setEditHistory] = useState([]);
+    // A store, not state: every operation update (save progress, completion,
+    // other sessions' edits) replaces the list. Components that render it
+    // subscribe with useEditHistory(); handlers read editContext.editHistory.
+    const [editHistoryStore] = useState(() => createValueStore([]));
+    const setEditHistory = editHistoryStore.set;
     const [historyMode, setHistoryMode] = useState("global");
     const [showOnlyMyChanges, setShowOnlyMyChanges] = useState(true);
     const [filterByCurrentLanguage, setFilterByCurrentLanguage] = useState(true);
@@ -339,7 +381,9 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             ];
         });
     }, []);
-    const [activeSessions, setActiveSessions] = useState(() => {
+    // A store, not EditContext state: presence broadcasts replace the list
+    // whenever any session focuses or locks a field.
+    const [activeSessionsStore] = useState(() => createValueStore((() => {
         try {
             const existing = globalThis.__alpacaActiveSessions;
             return Array.isArray(existing) ? existing : [];
@@ -347,8 +391,20 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         catch {
             return [];
         }
-    });
-    const [remoteCarets, setRemoteCarets] = useState({});
+    })()));
+    const activeSessions = useValueStore(activeSessionsStore);
+    const setActiveSessions = activeSessionsStore.set;
+    const sessionUser = activeSessions.find((x) => x.sessionId === sessionId)?.user ||
+        userInfo.user;
+    // Presence broadcasts rebuild the session list, and with it this object,
+    // whenever anyone focuses or locks a field. Keep one identity per distinct
+    // value so they do not rebuild the EditContext value.
+    const sessionUserKey = JSON.stringify(sessionUser);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const user = useMemo(() => sessionUser, [sessionUserKey]);
+    // A store, not state: carets move on every keystroke of every session.
+    const [remoteCaretsStore] = useState(() => createValueStore({}));
+    const setRemoteCarets = remoteCaretsStore.set;
     // Block editing until the server acknowledges our client-info for the current item
     const [isClientInfoAcknowledged, setIsClientInfoAcknowledged] = useState(false);
     if (typeof window !== "undefined")
@@ -512,7 +568,10 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [componentDesignerComponent, setComponentDesignerComponent] = useState();
     const [componentDesignerRendering, setComponentDesignerRendering] = useState();
     const [insertMode, setInsertMode] = useState(false);
-    const [ignoreBlur, setIgnoreBlur] = useState(false);
+    // A ref, not state: it flips true and back within 20ms of every field click,
+    // and as state each flip changed setFocusedFieldWithLock's identity and with
+    // it the FieldsEditContext value.
+    const ignoreBlurRef = useRef(false);
     // Timestamp of the most recent pointer-down on a User Manual "Show me" control.
     // Used by the field-blur guard so clicking a field-gated Show me button keeps
     // the focused field (and thus the `.focused-field` anchor + field actions).
@@ -676,7 +735,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [showVersionDiffHighlighting, setShowVersionDiffHighlighting] = useState(false);
     const [agentChangeHighlighting, setAgentChangeHighlighting] = useState(null);
     const [availableCommentTags, setAvailableCommentTags] = useState([]);
-    const [showComments, setShowComments] = useState(() => {
+    const [showComments, setShowCommentsRaw] = useState(() => {
         // ?showFeedback=true|false overrides the persisted preference, e.g. the
         // sandbox register redirect lands users with the feedback panel closed.
         const showFeedbackParam = searchParams.get("showFeedback");
@@ -685,9 +744,27 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
         return localStorageService.getOrSetItem("editor.showComments", true);
     });
+    const showCommentsRef = useRef(showComments);
+    showCommentsRef.current = showComments;
     useEffect(() => {
         localStorageService.setItem("editor.showComments", showComments);
     }, [showComments]);
+    // The mobile comments panel (the comment list below the canvas on a phone)
+    // is opt-in per session: it starts closed whatever the persisted preference
+    // says, and follows every on/off transition made on the phone. The reveal
+    // helper is defined with the other mobile panel state further down; the
+    // ref lets the setter (declared here, used by mode changes above) reach it.
+    const [mobileCommentsPanelOpen, setMobileCommentsPanelOpen] = useState(false);
+    const revealMobileCommentsPanelRef = useRef(() => { });
+    const setShowComments = useCallback((value) => {
+        const next = typeof value === "function" ? value(showCommentsRef.current) : value;
+        showCommentsRef.current = next;
+        setShowCommentsRaw(next);
+        if (next)
+            revealMobileCommentsPanelRef.current();
+        else
+            setMobileCommentsPanelOpen(false);
+    }, []);
     const [showResolvedComments, setShowResolvedComments] = useState(() => {
         return localStorageService.getOrSetItem("editor.showResolvedComments", false);
     });
@@ -897,6 +974,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const [editorFormHintSeen, setEditorFormHintSeenState] = useState(userPreferences.editorFormHintSeen ?? false);
     const [editorFormHintVisible, setEditorFormHintVisible] = useState(false);
     const editorFormToggleButtonRef = useRef(null);
+    const [componentInsertionHintSeen, setComponentInsertionHintSeenState] = useState(userPreferences.componentInsertionHintSeen ?? false);
     const [showMinimap, setShowMinimap] = useState(userPreferences.showMinimap ?? true);
     const effectiveShowMinimap = minimapEnabledInSettings && showMinimap;
     const [showHelpTerminal, setShowHelpTerminal] = useState(false);
@@ -929,7 +1007,9 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
     }, [setQuotaInfo]);
     const [webSocketMessages, setWebSocketMessages] = useState([]);
-    const [socketDiagnostics, setSocketDiagnostics] = useState(() => createEditorSocketDiagnostics(sessionId));
+    // A store, not state: it changes on every socket message.
+    const [socketDiagnosticsStore] = useState(() => createValueStore(createEditorSocketDiagnostics(sessionId)));
+    const setSocketDiagnostics = socketDiagnosticsStore.set;
     const [favorites, setFavorites] = useState([]);
     // Quick item switcher state
     const [quickSwitcherVisible, setQuickSwitcherVisible] = useState(false);
@@ -1005,12 +1085,14 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                 focusedField.item.id !== lastTextSelection.itemId)) {
             lastTextSelectionRangeRef.current = undefined;
         }
-    }, [focusedField]);
-    useEffect(() => {
-        if (isUsableTextSelectionRange(selectedRange)) {
-            lastTextSelectionRangeRef.current = selectedRange;
+        const caretRange = caretRangeRef.current;
+        if (focusedField &&
+            caretRange &&
+            (focusedField.fieldId !== caretRange.fieldId ||
+                focusedField.item.id !== caretRange.itemId)) {
+            caretRangeRef.current = undefined;
         }
-    }, [selectedRange]);
+    }, [focusedField]);
     // Track the current page item descriptor for itemsRepository
     const [currentPageItem, setCurrentPageItem] = useState();
     // Create itemsRepository with current page item (will be updated when page loads)
@@ -1107,18 +1189,18 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     useEffect(() => {
         activePageViewContextRef.current = activePageViewContext;
     }, [activePageViewContext]);
+    const page = usePageViewState(activePageViewContext, (state) => state.page);
+    const activeIframeSupportsRefresh = usePageViewState(activePageViewContext, (state) => state.iframeSupportsRefresh);
     // Keep the active PageViewContext's fullscreen flag in sync with the shell fullscreen mode.
     useEffect(() => {
-        if (activePageViewContext.fullscreen !== fullscreen) {
-            activePageViewContext.setFullscreen(fullscreen);
-        }
+        activePageViewContext.setFullscreen(fullscreen);
     }, [activePageViewContext, fullscreen]);
     // Update currentPageItem when pageViewContext.page is available
     useEffect(() => {
-        if (activePageViewContext.page?.item.descriptor) {
-            setCurrentPageItem(activePageViewContext.page.item.descriptor);
+        if (page?.item.descriptor) {
+            setCurrentPageItem(page.item.descriptor);
         }
-    }, [activePageViewContext.page?.item.descriptor]);
+    }, [page?.item.descriptor]);
     // Track which items are rendered/used by the current page for targeted refresh
     const pageItemsSetRef = useRef(new Set());
     const makeItemKey = useCallback((d) => `${d.id}-${d.language}-${d.version}`.toLowerCase(), []);
@@ -1132,20 +1214,20 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             component.items?.forEach((i) => newSet.add(makeItemKey(i)));
             component.placeholders?.forEach((ph) => ph.components?.forEach(collect));
         };
-        if (activePageViewContext?.page) {
+        if (page) {
             // Include the page item itself
-            const pageDescriptor = activePageViewContext.page.item.descriptor;
+            const pageDescriptor = page.item.descriptor;
             newSet.add(makeItemKey(pageDescriptor));
-            collect(activePageViewContext.page.rootComponent);
+            collect(page.rootComponent);
         }
         pageItemsSetRef.current = newSet;
-    }, [activePageViewContext.page?.editRevision]);
+    }, [page?.editRevision]);
     const isItemUsedInCurrentPage = useCallback((item) => pageItemsSetRef.current.has(makeItemKey(item)), [makeItemKey]);
     const socketMessageListeners = useRef(new Set());
     const [socketConnectionVersion, setSocketConnectionVersion] = useState(0);
     useEffect(() => {
         setSocketDiagnostics(createEditorSocketDiagnostics(sessionId));
-    }, [sessionId]);
+    }, [sessionId, setSocketDiagnostics]);
     const addSocketMessageListener = useCallback((callback) => {
         socketMessageListeners.current.add(callback);
         return () => socketMessageListeners.current.delete(callback);
@@ -1184,7 +1266,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             }
             catch { }
         };
-    }, [addSocketMessageListener, sessionId]);
+    }, [addSocketMessageListener, sessionId, setRemoteCarets]);
     useEffect(() => {
         const activeSessionIds = new Set(activeSessions.map((s) => s.sessionId));
         setRemoteCarets((current) => {
@@ -1200,7 +1282,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             });
             return changed ? next : current;
         });
-    }, [activeSessions]);
+    }, [activeSessions, setRemoteCarets]);
     // Listen for batch completion notifications
     useEffect(() => {
         const removeListener = addSocketMessageListener((message) => {
@@ -1294,6 +1376,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         // Only clear selection range if we specifically switched to a DIFFERENT field.
         // If focusedField is undefined (e.g. lost focus to a dialog), keep the previous selection context
         // so the AI tool can still act on it.
+        const selectedRange = selectedRangeStore.get();
         if (focusedField &&
             selectedRange &&
             (focusedField.fieldId !== selectedRange.fieldId ||
@@ -1323,7 +1406,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     }, [currentWorkspace]);
     const sendClientInfoImmediate = useCallback(async () => {
         const itemAtSend = currentItemRef.current;
-        const pageAtSend = activePageViewContextRef.current?.page?.item;
+        const pageAtSend = activePageViewContextRef.current?.getState().page?.item;
         const clientInfoMessage = {
             type: "client-info",
             sessionId: sessionId,
@@ -1543,6 +1626,19 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             setOpenSidebars([]);
         }
     }, [isMobile, mobilePanelDismissToken]);
+    // Bring the comments panel to the front: the form panel and the sidebars
+    // cover it (precedence form > sidebars > comments), so opening it closes
+    // them. Closing the form records the dismiss token for the current
+    // selection, so the form does not bounce back until the next canvas tap.
+    const revealMobileCommentsPanel = useCallback(() => {
+        if (!isMobile)
+            return;
+        setMobileCommentsPanelOpen(true);
+        handleSetMobileEditorPanelOpen(false);
+        openSidebarsRef.current = [];
+        setOpenSidebars([]);
+    }, [isMobile, handleSetMobileEditorPanelOpen]);
+    revealMobileCommentsPanelRef.current = revealMobileCommentsPanel;
     const handleSetShowMinimap = useCallback((value) => {
         const newValue = typeof value === "function" ? value(showMinimap) : value;
         setShowMinimap(newValue);
@@ -1588,6 +1684,14 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         setEditorFormHintSeenState(true);
         setUserPreferences({ editorFormHintSeen: true });
     }, [setUserPreferences]);
+    const markComponentInsertionHintSeen = useCallback(() => {
+        setComponentInsertionHintSeenState((prev) => {
+            if (prev)
+                return prev;
+            setUserPreferences({ componentInsertionHintSeen: true });
+            return true;
+        });
+    }, [setUserPreferences]);
     const showEditorFormHint = useCallback(() => {
         setEditorFormHintVisible(true);
     }, []);
@@ -1667,8 +1771,6 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         setUserPreferences({ pinnedSidebars: newPinnedSidebars });
     }, [setUserPreferences]);
     // messageHandler is defined after loadItem/loadHistory declarations to avoid temporal dead zones
-    const user = activeSessions.find((x) => x.sessionId === sessionId)?.user ||
-        userInfo.user;
     // Self-heal if our session disappears (e.g., after HMR). Skip when concurrent user limit
     // is showing so we don't spam recovery attempts when the connection was rejected.
     const missingSessionRecoveryTimerRef = useRef(null);
@@ -1946,7 +2048,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         if (selection.length)
             setSelectedForInsertion("");
         // Does the current focused field belong to the current item?
-        const currentItem = selection.length > 0 ? selection[0] : activePageViewContext.page?.item.id;
+        const currentItem = selection.length > 0 ? selection[0] : page?.item.id;
         if (currentItem && focusedField?.item.id !== currentItem) {
             setFocusedField(undefined);
         }
@@ -2038,7 +2140,8 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         setRefreshCompletedFlag(!refreshCompletedFlag);
         setInserting(undefined);
         setRemovingComponentIds([]);
-    }, [currentItemDescriptor, activePageViewContext.page?.item.id]);
+        setRecentConversion(undefined);
+    }, [currentItemDescriptor, page?.item.id]);
     useEffect(() => {
         // When the item changes, reset acknowledgment. Registration below sends
         // immediately and keeps retrying until active-sessions confirms it.
@@ -2068,6 +2171,15 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
         catch { }
     }, [activeSessions, sessionId]);
+    // Reviewers from a review link stay in their review; everyone else loses a
+    // reviewId that no longer applies once they browse to other pages.
+    useLeftoverReviewIdCleanup(item
+        ? {
+            id: item.descriptor.id,
+            language: item.descriptor.language,
+            idPath: item.idPath,
+        }
+        : undefined, !userInfo.user?.isLimitedPreviewUser);
     const loadComments = useCallback(async () => {
         const requestId = ++commentsLoadRequestRef.current;
         if (!currentItemDescriptor)
@@ -2142,7 +2254,6 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const refreshFavorites = useCallback(async (opts) => {
         await loadFavorites();
     }, [loadFavorites]);
-    const page = activePageViewContext.page;
     const currentHistoryScope = useMemo(() => {
         const currentItem = item?.descriptor;
         const currentLanguage = item?.descriptor?.language || currentItemDescriptor?.language;
@@ -2249,21 +2360,16 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
     }, []);
     useEffect(() => {
-        // Read fresh page from the mutable slot context ref chain.
-        // The slot context uses a stable ref that is mutated in-place (see editorSlotContext.ts),
-        // so `page` from the render scope may be stale when the slot's page model completes.
-        // pageModelReadyToken triggers this effect to re-evaluate with the latest page.
-        const freshPage = activePageViewContext.page ?? page;
         const isLoading = !!item &&
             item.hasLayout &&
-            (!freshPage || (freshPage?.editRevision ?? "") != (revision ?? ""));
+            (!page || (page?.editRevision ?? "") != (revision ?? ""));
         const newIsRefreshing = isLoading && viewName === "editor";
         setIsRefreshing(newIsRefreshing);
         if (!isLoading) {
             setInserting(undefined);
             setRemovingComponentIds([]);
         }
-    }, [page, viewName, revision, pageModelReadyToken]);
+    }, [page, viewName, revision]);
     // moved below to ensure requestRefresh is declared first
     const loadHistory = useDebouncedCallback(async () => {
         if (!sessionId)
@@ -2941,24 +3047,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         showHelpTerminal,
         selectedHelpSectionId,
     ]);
-    useEffect(() => {
-        async function load() {
-            if (!currentItemDescriptor)
-                return;
-            // Capture the item ID at the start of this async operation
-            const descriptorIdAtStart = currentItemDescriptor.id;
-            const item = await itemsRepository.getItem(currentItemDescriptor);
-            // Check if the current item has changed during the async operation
-            // If so, skip this update to avoid overwriting with stale data
-            if (currentItemDescriptorRef.current?.id !== descriptorIdAtStart) {
-                return;
-            }
-            setItem(item);
-            if (!item)
-                return;
-        }
-        load();
-    }, [itemsRepository.revision]);
+    useRepositoryItemRefresh(itemsRepository, currentItemDescriptor, currentItemDescriptorRef, setItem);
     const addToBrowseHistory = useCallback((item) => {
         const historyEntry = {
             path: item.path || "unknown",
@@ -3300,7 +3389,10 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         lockedField,
         itemsRepository,
         user,
-        editHistory,
+        get editHistory() {
+            return editHistoryStore.get();
+        },
+        editHistoryStore,
         setEditHistory,
         showOnlyMyChanges,
         historyMode,
@@ -3509,6 +3601,17 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     const onOperationExecuted = useCallback((op) => {
         // Update the history through the single merge path.
         updateOperationInHistory(op);
+        // The "Converted from" badge lasts until the next edit.
+        setRecentConversion((current) => current &&
+            current.operationId.replace(/[{}]/g, "").toLowerCase() !==
+                op.id.replace(/[{}]/g, "").toLowerCase()
+            ? undefined
+            : current);
+        // The palette's how-to hint is for users who have never inserted a
+        // component; the first local insertion retires it.
+        if (op.type === "add-component") {
+            markComponentInsertionHintSeen();
+        }
         if (item?.id === op.mainItem?.id &&
             item?.language === op.mainItem?.language &&
             item?.version === op.mainItem?.version) {
@@ -3517,29 +3620,34 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         // Note: We intentionally do NOT call refreshHistory() here.
         // The websocket handler + merge logic above keeps the history up to date without
         // causing a race where stale server data arrives before the server has processed a redo.
-    }, [item, setInsertMode, updateOperationInHistory]);
-    const ui = {
+    }, [
+        item,
+        setInsertMode,
+        updateOperationInHistory,
+        markComponentInsertionHintSeen,
+    ]);
+    // Memoized: `ui` is a dependency of most operation callbacks, and through
+    // them of `operations` and the EditContext value. A fresh object per shell
+    // render rebuilt all three on every render (each field click), re-rendering
+    // every EditContext consumer.
+    const ui = useMemo(() => ({
         showErrorToast,
         confirmationDialogRef,
         onOperationExecuted,
-    };
+    }), [showErrorToast, onOperationExecuted]);
     // moved to useMediaSelector
     // Workbox/validation scope spans every open slot (each slot's page tree plus
     // its item), so opening a validation result in a second slot keeps the page's
-    // list intact regardless of which slot is active. The slot contexts are
-    // mutable refs; re-reads happen because notifyPageModelReady bumps the
-    // pageModelReadyToken state whenever a slot's page model finishes building.
-    const registeredSlotScopes = editorSlots.flatMap((slot) => {
+    // list intact regardless of which slot is active.
+    const registeredSlotContexts = editorSlots.flatMap((slot) => {
         const slotContext = slotContexts.get(slot.slotId);
-        if (!slotContext)
-            return [];
-        return [
-            {
-                page: slotContext.primaryPageViewContext.page,
-                itemDescriptor: slotContext.itemDescriptor,
-            },
-        ];
+        return slotContext ? [slotContext] : [];
     });
+    const registeredSlotPages = usePageViewStates(registeredSlotContexts.map((slotContext) => slotContext.primaryPageViewContext), (state) => state.page);
+    const registeredSlotScopes = registeredSlotContexts.map((slotContext, index) => ({
+        page: registeredSlotPages[index],
+        itemDescriptor: slotContext.itemDescriptor,
+    }));
     const workboxScopeSlots = registeredSlotScopes.length
         ? registeredSlotScopes
         : [{ page, itemDescriptor: currentItemDescriptor }];
@@ -3586,7 +3694,18 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             updateExecutingOperationProgressRef.current?.(operationId, progress, statusMessage);
         },
         refreshWorkbox,
-        canvasHasChromeSuppressedTargets: () => !!activePageViewContextRef.current?.bridgeGeometry?.targets.some((target) => target.decorationsSuppressed),
+        canvasHasChromeSuppressedTargets: () => !!activePageViewContextRef.current?.getState().bridgeGeometry?.targets.some((target) => target.decorationsSuppressed),
+        isRenderingOnCanvas: (itemId, fieldIds) => {
+            const page = currentItemRef.current;
+            return isRenderingOnCanvas({
+                itemId,
+                fieldIds,
+                iframe: activePageViewContextRef.current?.getState().editorIframe,
+                page: page?.id && page.language && typeof page.version === "number"
+                    ? { id: page.id, language: page.language, version: page.version }
+                    : undefined,
+            });
+        },
     });
     // Concurrent user limit error state
     const [concurrentUserLimitError, setConcurrentUserLimitError] = useState(null);
@@ -3686,7 +3805,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
         // Routes over whichever transport is active (WebSocket preferred, SSE fallback).
         getEditorRealtime().send(message);
-    }, [sessionId]);
+    }, [sessionId, setRemoteCarets]);
     // URL update helper - defined early so it can be used by workspace/sidebar functions
     const updateUrl = useCallback((params) => {
         // Use the actual browser pathname (including any basePath like /parhelia)
@@ -4188,7 +4307,10 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     ]);
     // Replace selected text with new content (for inline AI editing)
     const replaceSelectedText = useCallback(async (newText, selectionOverride) => {
-        const rangeToReplace = selectionOverride ?? selectedRange ?? lastTextSelectionRangeRef.current;
+        const rangeToReplace = selectionOverride ??
+            selectedRangeStore.get() ??
+            caretRangeRef.current ??
+            lastTextSelectionRangeRef.current;
         try {
             // If we have selected text and a replaceText callback, use it
             if (rangeToReplace?.text && rangeToReplace.replaceText) {
@@ -4217,7 +4339,9 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                 lastTextSelectionRangeRef.current = undefined;
                 return;
             }
-            const fieldToReplace = focusedField ??
+            // Read the focused field through the ref so this callback (part of
+            // editContext) keeps its identity across field clicks.
+            const fieldToReplace = focusedFieldRef.current ??
                 (rangeToReplace?.fieldId &&
                     rangeToReplace.itemId &&
                     rangeToReplace.language &&
@@ -4279,14 +4403,15 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             console.error("Failed to replace/insert text:", error);
         }
     }, [
-        selectedRange,
-        focusedField,
+        selectedRangeStore,
+        setSelectedRange,
         itemsRepository,
         operations,
         getActiveSlotContext,
     ]);
     // Insert text at cursor position (for when there's no selection)
     const insertTextAtCursor = useCallback(async (newText) => {
+        const focusedField = focusedFieldRef.current;
         if (!focusedField)
             return;
         try {
@@ -4320,8 +4445,9 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                 }
             }
             // If we have a selectedRange with position info, use it
-            if (!insertPosition && selectedRange?.startOffset !== undefined) {
-                insertPosition = selectedRange.startOffset;
+            const publishedRange = selectedRangeStore.get() ?? caretRangeRef.current;
+            if (!insertPosition && publishedRange?.startOffset !== undefined) {
+                insertPosition = publishedRange.startOffset;
             }
             // Fallback: use field value length (append)
             const { fieldId, item } = focusedField;
@@ -4345,8 +4471,8 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             console.error("Failed to insert text at cursor:", error);
         }
     }, [
-        focusedField,
-        selectedRange,
+        selectedRangeStore,
+        setSelectedRange,
         itemsRepository,
         operations,
         getActiveSlotContext,
@@ -4360,14 +4486,31 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
     // Shared focused field setter with lock handling (used in both contexts)
     const setFocusedFieldWithLock = useCallback(async (field, requestLock) => {
         if (field) {
-            setIgnoreBlur(true);
+            ignoreBlurRef.current = true;
             setTimeout(() => {
-                setIgnoreBlur(false);
+                ignoreBlurRef.current = false;
             }, 20);
             // Selection follows the user's click independently of the asynchronous
             // edit lock. Lock ownership controls whether editing may proceed, but a
             // slow or rejected lock must not leave the form on the previous field.
-            setFocusedField({ ...field });
+            //
+            // Every click inside a field re-enters here (the field wrapper captures
+            // clicks and focus), so a click on a field action such as Copy in the
+            // already focused field must not publish a new descriptor object:
+            // every consumer keyed on focusedField would re-run for a field that
+            // did not change. The lock is still ensured below (a no-op when held).
+            const current = focusedFieldRef.current;
+            const alreadyFocused = !!current &&
+                current.fieldId === field.fieldId &&
+                current.item.id === field.item.id &&
+                current.item.language === field.item.language &&
+                current.item.version === field.item.version;
+            if (!alreadyFocused) {
+                // Mirror the state synchronously so a second call in the same
+                // event (before the focusedField effect refreshes the ref) sees it.
+                focusedFieldRef.current = field;
+                setFocusedField({ ...field });
+            }
             if (requestLock) {
                 const lockResult = (await operations.ensureLock(field)) || false;
                 if (!lockResult) {
@@ -4399,14 +4542,17 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                 lastAgentTerminalInteractionAt: agentTerminalInteractionAtRef.current,
                 now: Date.now(),
             });
-            if (!ignoreBlur && !focusMovedToShowMe && !focusMovedToAgentTerminal) {
+            if (!ignoreBlurRef.current &&
+                !focusMovedToShowMe &&
+                !focusMovedToAgentTerminal) {
+                focusedFieldRef.current = undefined;
                 setFocusedField(undefined);
                 setLockedField(undefined); // Clear client-side lock state
                 releaseFieldLocks(sessionId);
             }
         }
         return true;
-    }, [operations, ignoreBlur, sessionId, lockedField]);
+    }, [operations, sessionId]);
     const quickSwitcherEntries = useMemo(() => {
         const entries = [];
         const seen = new Set();
@@ -4829,9 +4975,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         if (!isInitialLoad)
             return;
         const isFullscreen = searchParams.get("fullscreen") === "true";
-        if (isFullscreen !== activePageViewContext.fullscreen) {
-            activePageViewContext.setFullscreen(isFullscreen);
-        }
+        activePageViewContext.setFullscreen(isFullscreen);
     }, [searchParams, isInitialLoad, activePageViewContext]);
     useEffect(() => {
         if (typeof window === "undefined") {
@@ -4844,7 +4988,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         }
         window.__parheliaViewportTestApi = {
             setZoom: (zoom) => activePageViewContext.setZoom(zoom),
-            getZoom: () => activePageViewContext.zoom,
+            getZoom: () => activePageViewContext.getState().zoom,
         };
         return () => {
             delete window.__parheliaViewportTestApi;
@@ -4979,8 +5123,6 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             },
             scrollIntoView,
             setScrollIntoView,
-            focusedField,
-            setFocusedField: setFocusedFieldWithLock,
             getComponentCommands: async (components, providerContext) => {
                 return await getComponentCommands(components, editContext, providerContext);
             },
@@ -5160,7 +5302,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                         ];
                     });
                     try {
-                        await executeFieldServerAction(fieldDescriptor.item, fieldDescriptor.fieldId, item.descriptor, actionButton.action, editContext.sessionId, selectedRange?.text || "", parameters || {}, (data) => {
+                        await executeFieldServerAction(fieldDescriptor.item, fieldDescriptor.fieldId, item.descriptor, actionButton.action, editContext.sessionId, selectedRangeStore.get()?.text || "", parameters || {}, (data) => {
                             // Update progress message if available
                             if (data?.responseText) {
                                 op.message = data.responseText;
@@ -5265,10 +5407,16 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             },
             inserting,
             removingComponentIds,
+            recentConversion,
+            setRecentConversion,
             validating,
             validationResult,
             loadItem,
-            editHistory: editHistory,
+            // Live read for handlers; components subscribe with useEditHistory().
+            get editHistory() {
+                return editHistoryStore.get();
+            },
+            editHistoryStore,
             historyMode,
             setHistoryMode,
             showOnlyMyChanges,
@@ -5284,8 +5432,12 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             canLoadMoreHistory,
             isHistoryLoadingMore,
             loadMoreHistory,
-            activeSessions,
-            remoteCarets,
+            // Live read for handlers; components subscribe with useActiveSessions().
+            get activeSessions() {
+                return activeSessionsStore.get();
+            },
+            activeSessionsStore,
+            remoteCaretsStore,
             unlockField: async () => {
                 setLockedField(undefined); // Clear client-side lock state
                 await releaseFieldLocks(sessionId);
@@ -5340,11 +5492,15 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             currentOverlay,
             contextMenuSource,
             setCurrentOverlay,
-            lockedField,
             timings,
             setTimings,
-            selectedRange,
+            // Live read: selections and carets never rebuild this object.
+            get selectedRange() {
+                return selectedRangeStore.get() ?? caretRangeRef.current;
+            },
+            selectedRangeStore,
             setSelectedRange,
+            setCaretRange,
             replaceSelectedText,
             insertTextAtCursor,
             confirm: (props) => {
@@ -5367,7 +5523,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             addSocketMessageListener,
             sendSocketMessage,
             socketConnectionVersion,
-            socketDiagnostics,
+            socketDiagnosticsStore,
             currentItemDescriptor,
             editorSlots,
             activeSlotId,
@@ -5381,8 +5537,6 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             setActiveSlot,
             revision,
             fullReloadToken,
-            notifyPageModelReady,
-            pageModelReadyToken,
             selectedComment,
             setSelectedComment,
             selectedSuggestedEdit,
@@ -5413,12 +5567,19 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                 }
                 // Snapshot selection context up-front so switching views doesn't change what we comment on.
                 const hintedFieldSnapshot = options?.field;
-                const focusedFieldSnapshot = focusedFieldRef.current;
+                // A picked target (field or whole item) is what the comment is about;
+                // the focused field and selections elsewhere must not override it.
+                const hasExplicitTarget = !!options?.field || !!options?.itemId;
+                const focusedFieldSnapshot = hasExplicitTarget
+                    ? undefined
+                    : focusedFieldRef.current;
+                const selectedRange = selectedRangeStore.get();
                 const selectedRangeCandidate = isUsableTextSelectionRange(selectedRange)
                     ? selectedRange
                     : lastTextSelectionRangeRef.current;
-                const selectedRangeSnapshot = !hintedFieldSnapshot ||
-                    selectionRangeMatchesField(selectedRangeCandidate, hintedFieldSnapshot)
+                const selectedRangeSnapshot = (hintedFieldSnapshot
+                    ? selectionRangeMatchesField(selectedRangeCandidate, hintedFieldSnapshot)
+                    : !hasExplicitTarget)
                     ? selectedRangeCandidate
                     : undefined;
                 const selectedRangeFieldSnapshot = isUsableTextSelectionRange(selectedRangeSnapshot)
@@ -5437,6 +5598,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                     hintedFieldSnapshot ??
                     focusedFieldSnapshot;
                 const itemId = commentFieldSnapshot?.item.id ||
+                    options?.itemId ||
                     (selection.length > 0 ? selection[0] : undefined) ||
                     descriptor.id;
                 if (!itemId)
@@ -5541,6 +5703,8 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             showEditorFormHint,
             dismissEditorFormHint,
             editorFormToggleButtonRef,
+            componentInsertionHintSeen,
+            markComponentInsertionHintSeen,
             showMinimap: effectiveShowMinimap,
             setShowMinimap: handleSetShowMinimap,
             showHelpTerminal,
@@ -5566,6 +5730,9 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
             isMobile,
             mobileEditorPanelOpen,
             setMobileEditorPanelOpen: handleSetMobileEditorPanelOpen,
+            mobileCommentsPanelOpen,
+            setMobileCommentsPanelOpen,
+            revealMobileCommentsPanel,
             openDialog,
             webSocketMessages,
             clearWebSocketMessages: () => setWebSocketMessages([]),
@@ -5634,8 +5801,6 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         media.mediaSelectorMode,
         media.selectedMediaIdPath,
         scrollIntoView,
-        focusedField,
-        setFocusedFieldWithLock,
         activeFieldActions,
         currentWorkspace,
         previousWorkspaceId,
@@ -5661,9 +5826,10 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         insertMode,
         currentOverlay,
         contextMenuSource,
-        lockedField,
         timings,
-        selectedRange,
+        selectedRangeStore,
+        setSelectedRange,
+        setCaretRange,
         replaceSelectedText,
         insertTextAtCursor,
         browseHistory,
@@ -5674,11 +5840,10 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         sendSocketMessage,
         socketConnectionVersion,
         removingComponentIds,
+        recentConversion,
         currentItemDescriptor,
         revision,
         fullReloadToken,
-        notifyPageModelReady,
-        pageModelReadyToken,
         selectedComment,
         selectedSuggestedEdit,
         comments,
@@ -5709,8 +5874,8 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         quickSwitcherSelectedIndex,
         handleQuickSwitcherSelect,
         webSocketMessages,
-        socketDiagnostics,
-        remoteCarets,
+        socketDiagnosticsStore,
+        remoteCaretsStore,
         factoriesRef,
         user,
         statusMessage,
@@ -5728,6 +5893,8 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         isMobile,
         mobileEditorPanelOpen,
         handleSetMobileEditorPanelOpen,
+        mobileCommentsPanelOpen,
+        revealMobileCommentsPanel,
         showComponentNavigator,
         isComponentNavigatorOpenForSlot,
         setComponentNavigatorOpenForSlot,
@@ -5767,6 +5934,46 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         executeCommand,
         showInfoToast,
         showErrorToast,
+        // Values below were missing and only looked fresh while this object was
+        // rebuilt on every shell render or socket message.
+        inserting,
+        editHistoryStore,
+        historyMode,
+        showOnlyMyChanges,
+        filterByCurrentLanguage,
+        sidebarStacks,
+        fullscreen,
+        mode,
+        showSuggestedEdits,
+        showSuggestedEditsDiff,
+        showSelectedSuggestionOnPage,
+        showVersionDiffHighlighting,
+        agentChangeHighlighting,
+        componentInsertionHintSeen,
+        selectWithoutAutoScroll,
+        consumeNextSelectionAutoScrollSuppression,
+        consumeNextFocusedFieldAutoScrollSuppression,
+        loadItem,
+        refreshHistory,
+        stackSidebar,
+        moveSidebarToColumn,
+        unstackSidebar,
+        reorderSidebarInStack,
+        setCompareMode,
+        registerSlotContext,
+        unregisterSlotContext,
+        getActiveSlotContext,
+        getActiveSlotId,
+        closeEditorSlot,
+        setActiveSlot,
+        setShowComments,
+        setSuggestedEdits,
+        getCurrentSuggestedEdits,
+        markComponentInsertionHintSeen,
+        handleSetShowHelpTerminal,
+        handleSetShowAgentsWorkspaceEditor,
+        handleSetShowLayoutComponents,
+        activeSessionsStore,
     ]);
     // CRITICAL: Assign editContext to ref synchronously (not via useEffect)
     // This ensures editContextRef.current always has the latest value when executeCommand is called
@@ -5787,6 +5994,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         addRecentEdit,
         focusedField,
         setFocusedField: setFocusedFieldWithLock,
+        lockedField,
         unlockField: async () => {
             setLockedField(undefined); // Clear client-side lock state
             await releaseFieldLocks(sessionId);
@@ -5797,6 +6005,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
         addRecentEdit,
         focusedField,
         setFocusedFieldWithLock,
+        lockedField,
         sessionId,
     ]);
     // Debug: Track editContext changes
@@ -6056,7 +6265,7 @@ export function EditorShell({ configuration, className, item: loadItemDescriptor
                         startTour();
                     }
                     : undefined, replayEnabled: canStartTour })), _jsx(FeatureGate, { feature: LicenseFeatures.AI, children: _jsx(GuidanceOverlay, {}) }), _jsx(FeatureGate, { feature: LicenseFeatures.AI, children: _jsx(AgentDialogHandler, {}) })] }));
-    const showRefreshSpinner = editContext.isRefreshing && !activePageViewContext.iframeSupportsRefresh;
+    const showRefreshSpinner = editContext.isRefreshing && !activeIframeSupportsRefresh;
     return (_jsx(LicenseProvider, { initialLicenseStatus: initialLicenseStatus, initialStatusLoaded: initialLicenseStatusLoaded, children: _jsx("div", { className: `editor h-full w-full`, children: _jsx(OperationsContextProvider, { value: operationsContext.context, children: _jsx(FieldsEditContextProvider, { value: fieldsEditContext, children: _jsx(EditContextProvider, { value: editContext, children: _jsxs(SelectionContextProvider, { value: selectionContextValue, children: [_jsx(DevModeIndicator, {}), startupChecks.state === "loading" && _jsx(EditorLoadingOverlay, {}), showRefreshSpinner && (_jsx("div", { className: "text-neutral-grey-50 pointer-events-none fixed right-0 bottom-0 flex h-24 w-24 items-center justify-center opacity-50 select-none", children: _jsx(Spinner, {}) })), (currentWorkspace.id === "agents" ||
                                     currentWorkspace.id === "taskboard" ||
                                     currentWorkspace.id === "translation-management") &&