@parhelia/core 0.1.12882 → 0.1.12884

package/dist/editor/menubar/toolbar-sections/ManualBrowser.js

@@ -11,6 +11,7 @@ import { useEditContext } from "../../client/editContext";
 import { cn } from "../../../lib/utils";
 import { sanitizeSvg } from "../../../lib/sanitize";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "../../../components/ui/dropdown-menu";
+import { waitForSelectorAnimations } from "../../ui/animationSettle";
 /** Render a sanitized SVG string at a specific pixel size. */
 function SvgIcon({ svg, size, className, }) {
     const sanitizedSvg = sanitizeSvg(svg).trim();
@@ -37,15 +38,6 @@ function getEditorFormSlider(elements = []) {
 function isEditorFormSliderHidden(slider) {
     return slider?.getAttribute(EDITOR_FORM_HIDDEN_ATTRIBUTE) === "true";
 }
-async function waitForEditorFormSliderOpen(slider, timeoutMs = 1000) {
-    const startedAt = Date.now();
-    while (Date.now() - startedAt < timeoutMs) {
-        if (!isEditorFormSliderHidden(slider ?? getEditorFormSlider())) {
-            return;
-        }
-        await waitForDelay(50);
-    }
-}
 async function waitForResolvedElements(resolveElements, selector, timeoutMs = 1000) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
@@ -171,7 +163,8 @@ function parseSelectorToken(selectorToken) {
     if (!selectorToken.startsWith("@"))
         return { selector: selectorToken };
     const raw = selectorToken.slice(1);
-    // Preserve iframe: selectors (handled specially by expandSelector/highlightElement)
+    // Preserve iframe: selectors as unavailable selectors. Page DOM inspection now
+    // goes through the editing bridge instead of same-origin iframe probing.
     if (raw.startsWith("iframe:"))
         return { selector: selectorToken };
     // Check for sidebar-only syntax: @sidebar-id-sidebar (e.g., @reviews-sidebar)
@@ -207,7 +200,6 @@ export function expandSelector(selectorShorthand) {
         return selector;
     }
     if (selector.startsWith("iframe:")) {
-        // Iframe selector: @iframe:selector → iframe:selector (handled by GuidanceOverlay)
         return selector;
     }
     // Default: data-testid selector: @name → [data-testid="name"]
@@ -216,12 +208,7 @@ export function expandSelector(selectorShorthand) {
 function getElementsForSelector(selector) {
     const cssSelector = expandSelector(selector);
     if (cssSelector.startsWith("iframe:")) {
-        const iframeSelector = cssSelector.substring(7);
-        const iframe = document.querySelector("iframe.page-iframe");
-        if (!iframe?.contentDocument) {
-            return [];
-        }
-        return Array.from(iframe.contentDocument.querySelectorAll(iframeSelector));
+        return [];
     }
     return Array.from(document.querySelectorAll(cssSelector));
 }
@@ -302,32 +289,6 @@ async function waitForScrollToFinish(element) {
         previousRect = currentRect;
     }
 }
-// Wait until an element's box (position and size) stops changing. This avoids
-// drawing the highlight overlay mid-animation (e.g. while a sidebar panel is
-// still expanding from its collapsed width).
-async function waitForStableRect(element, timeoutMs = 1000) {
-    let previousRect = element.getBoundingClientRect();
-    let stableFrames = 0;
-    const startedAt = Date.now();
-    while (Date.now() - startedAt < timeoutMs) {
-        await waitForNextFrame();
-        const currentRect = element.getBoundingClientRect();
-        const changed = Math.abs(currentRect.width - previousRect.width) > 0.5 ||
-            Math.abs(currentRect.height - previousRect.height) > 0.5 ||
-            Math.abs(currentRect.top - previousRect.top) > 0.5 ||
-            Math.abs(currentRect.left - previousRect.left) > 0.5;
-        if (changed) {
-            stableFrames = 0;
-        }
-        else {
-            stableFrames += 1;
-            if (stableFrames >= 2) {
-                return;
-            }
-        }
-        previousRect = currentRect;
-    }
-}
 async function scrollElementForHighlight(element) {
     if (shouldSkipHighlightScroll(element)) {
         return;
@@ -347,27 +308,28 @@ export async function highlightElement(selector, duration = HIGHLIGHT_DURATION_M
     const elements = getElementsForSelector(selector).filter(isElementVisible);
     if (elements.length === 0)
         return;
+    const overlayLifetimes = [];
     if (cssSelector.startsWith("iframe:")) {
         const iframe = document.querySelector("iframe.page-iframe");
         const iframeRect = iframe?.getBoundingClientRect();
         if (elements[0]) {
             await scrollElementForHighlight(elements[0]);
-            await waitForStableRect(elements[0]);
         }
         elements.forEach((element) => {
             const elementRect = element.getBoundingClientRect();
-            showHighlightOverlay(elementRect.left + (iframeRect?.left ?? 0), elementRect.top + (iframeRect?.top ?? 0), elementRect.width, elementRect.height, duration);
+            overlayLifetimes.push(showHighlightOverlay(elementRect.left + (iframeRect?.left ?? 0), elementRect.top + (iframeRect?.top ?? 0), elementRect.width, elementRect.height, duration));
         });
+        await Promise.all(overlayLifetimes);
         return;
     }
     if (elements[0]) {
         await scrollElementForHighlight(elements[0]);
-        await waitForStableRect(elements[0]);
     }
     elements.forEach((element) => {
         const rect = element.getBoundingClientRect();
-        showHighlightOverlay(rect.left, rect.top, rect.width, rect.height, duration);
+        overlayLifetimes.push(showHighlightOverlay(rect.left, rect.top, rect.width, rect.height, duration));
     });
+    await Promise.all(overlayLifetimes);
 }
 // Check if an element is currently present in the DOM (regardless of visibility)
 function isElementPresent(selector) {
@@ -393,7 +355,8 @@ export function deriveSelectorState(params) {
     }
     return "disabled";
 }
-// Create a temporary highlight overlay
+// Create a temporary highlight overlay. Resolves when its finite "life"
+// animation ends and the overlay has been removed (event-driven, not a timer).
 function showHighlightOverlay(x, y, width, height, duration) {
     const padding = 4;
     const viewportWidth = window.innerWidth;
@@ -410,9 +373,11 @@ function showHighlightOverlay(x, y, width, height, duration) {
     const clampedHeight = bottom - top;
     // Skip if target is fully outside the viewport after clamping.
     if (clampedWidth <= 0 || clampedHeight <= 0)
-        return;
+        return Promise.resolve();
     const overlay = document.createElement("div");
     overlay.className = "selector-highlight-overlay";
+    // Two animations: the infinite pulse for the visual, and a finite "life"
+    // animation whose animationend drives removal (single source of duration).
     overlay.style.cssText = `
     position: fixed;
     left: ${left}px;
@@ -424,7 +389,7 @@ function showHighlightOverlay(x, y, width, height, duration) {
     background: color-mix(in srgb, var(--color-component-default) 10%, transparent);
     pointer-events: none;
     z-index: 999999;
-    animation: pulse-highlight 1s ease-in-out infinite;
+    animation: pulse-highlight 1s ease-in-out infinite, selector-highlight-life ${duration}ms linear forwards;
     box-shadow: 0 0 0 4px color-mix(in srgb, var(--color-component-default) 20%, transparent);
   `;
     // Add animation keyframes if not already added
@@ -436,22 +401,62 @@ function showHighlightOverlay(x, y, width, height, duration) {
         0%, 100% { box-shadow: 0 0 0 4px color-mix(in srgb, var(--color-component-default) 20%, transparent); }
         50% { box-shadow: 0 0 0 8px color-mix(in srgb, var(--color-component-default) 10%, transparent); }
       }
+      @keyframes selector-highlight-life {
+        from { opacity: 1; }
+        to { opacity: 1; }
+      }
     `;
         document.head.appendChild(style);
     }
     document.body.appendChild(overlay);
-    setTimeout(() => {
-        overlay.remove();
-    }, duration);
+    return new Promise((resolve) => {
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            overlay.removeEventListener("animationend", onAnimationEnd);
+            overlay.remove();
+            resolve();
+        };
+        const onAnimationEnd = (event) => {
+            // Ignore the infinite pulse; only the finite life animation ends.
+            if (event.animationName === "selector-highlight-life") {
+                finish();
+            }
+        };
+        overlay.addEventListener("animationend", onAnimationEnd);
+        // Guardrail: if animationend is ever missed, remove shortly after duration.
+        window.setTimeout(finish, duration + 500);
+    });
 }
 let activeRevealController = null;
 let revealControllerSeq = 0;
+// Serialize Show-me reveal clicks across ALL buttons so overlapping rapid clicks
+// can never interleave. Each click chains behind the previous handler and grabs
+// a monotonic token. This closes the race where, during the
+// `await superseded.close()` teardown window, no global controller is registered:
+// without serialization a faster later click could start, become active, and
+// then be overwritten by this (older, still-awaiting) handler — i.e. NOT
+// "last click wins". With the chain, a newer click waits for this one to fully
+// settle (and is then properly superseded), and an older handler that has been
+// overtaken while waiting discards its work via the token check.
+let revealClickChain = Promise.resolve();
+let revealClickSeq = 0;
+// Store the new active reveal. Superseding the previous one is done explicitly
+// at click start (see supersedeActiveReveal), so this only records state.
 function registerActiveReveal(controller) {
-    const previous = activeRevealController;
     activeRevealController = controller;
-    if (previous && previous.id !== controller.id) {
-        previous.close();
+}
+// Detach and return the currently active reveal unless it belongs to exceptId.
+// The caller is responsible for closing it (and awaiting its teardown).
+function supersedeActiveReveal(exceptId) {
+    const current = activeRevealController;
+    if (current && current.id !== exceptId) {
+        activeRevealController = null;
+        return current;
     }
+    return null;
 }
 function clearActiveReveal(id) {
     if (activeRevealController?.id === id) {
@@ -465,6 +470,28 @@ function closeMorePanelsIfOpen() {
     const trigger = document.querySelector('[data-testid="more-sidebars-button"]');
     trigger?.click();
 }
+function closeVersionSelectorIfOpen() {
+    if (!isElementPresent("@version-selector-list"))
+        return;
+    const list = document.querySelector('[data-testid="version-selector-list"]');
+    if (list) {
+        list.dispatchEvent(new KeyboardEvent("keydown", {
+            key: "Escape",
+            code: "Escape",
+            bubbles: true,
+            cancelable: true,
+        }));
+        return;
+    }
+    const trigger = document.querySelector('[data-testid="version-selector"][aria-expanded="true"]') ??
+        document.querySelector('[data-testid="version-selector"]');
+    trigger?.click();
+}
+function isAgentsPanelOpen() {
+    const trigger = document.querySelector('[data-testid="agents-panel-button"]');
+    return (trigger?.getAttribute("aria-pressed") === "true" ||
+        isElementVisibleBySelector("@sidebar-panel-agents-panel"));
+}
 // Button component for "Show me" functionality with availability detection
 function SelectorButton({ selectorDef, keyProp, }) {
     const editContext = useEditContext();
@@ -521,19 +548,21 @@ function SelectorButton({ selectorDef, keyProp, }) {
     }, []);
     // Run the undo steps and reset. Used for explicit close (2nd click, auto
     // timer, or being superseded by another reveal via mutual exclusion).
-    const runRestore = useCallback(() => {
+    const runRestore = useCallback(async () => {
         const reveal = revealRef.current;
+        // Reset button state immediately (button turns blue) while the surface
+        // teardown animation plays out; the returned promise resolves once settled.
+        clearActiveReveal(reveal?.id ?? controllerIdRef.current);
+        revealRef.current = null;
+        setIsActiveReveal(false);
         if (reveal) {
             try {
-                reveal.restore();
+                await reveal.restore();
             }
             catch {
                 // ignore restore failures
             }
         }
-        clearActiveReveal(reveal?.id ?? controllerIdRef.current);
-        revealRef.current = null;
-        setIsActiveReveal(false);
     }, []);
     const runRestoreRef = useRef(runRestore);
     runRestoreRef.current = runRestore;
@@ -626,138 +655,260 @@ function SelectorButton({ selectorDef, keyProp, }) {
                         }
                         if (isDisabled)
                             return;
-                        const runId = globalThis.crypto?.randomUUID?.() ??
-                            `manual-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-                        const resolveElements = (selector = selectorDef.selector) => selector ? getElementsForSelector(selector) : [];
-                        const runManualAction = async (actionName, elements) => {
-                            if (!actionName || !editContext || !manualActions?.[actionName]) {
+                        // Sequence overlapping Show-me clicks across ALL buttons so a rapid
+                        // second click can't interleave with this one. We chain behind any
+                        // in-flight reveal and take a monotonic token; if a newer click
+                        // arrives while we wait our turn, this (now stale) handler bails out
+                        // instead of overtaking it. This guarantees "last click wins" and
+                        // closes the teardown-window race where, during
+                        // `await superseded.close()`, no global controller is registered.
+                        const clickToken = ++revealClickSeq;
+                        const previousClick = revealClickChain;
+                        let releaseClick = () => { };
+                        revealClickChain = new Promise((resolve) => {
+                            releaseClick = resolve;
+                        });
+                        try {
+                            await previousClick;
+                            // A newer click superseded this one while we waited our turn.
+                            if (clickToken !== revealClickSeq) {
                                 return;
                             }
-                            const action = manualActions[actionName];
-                            const actionProps = {
-                                editContext,
-                                selectorDef,
-                                duration: HIGHLIGHT_DURATION_MS,
-                                runId,
-                                elements,
-                                resolveElements,
+                            // State-machine semantics: any new Show-me action supersedes the
+                            // currently active State 3 reveal from another button, restoring
+                            // its UI first. Await the teardown so this reveal samples fresh
+                            // DOM and avoids a stale "was this surface open?" read. Because
+                            // clicks are serialized above, the superseded controller is
+                            // always the previous fully-settled reveal (no race here).
+                            const superseded = supersedeActiveReveal(controllerIdRef.current);
+                            if (superseded) {
+                                try {
+                                    // Await the close so A's surface finishes its teardown
+                                    // animation before B starts revealing (event-driven, not timed).
+                                    await superseded.close();
+                                }
+                                catch {
+                                    // ignore supersede failures
+                                }
+                            }
+                            const runId = globalThis.crypto?.randomUUID?.() ??
+                                `manual-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                            const resolveElements = (selector = selectorDef.selector) => selector ? getElementsForSelector(selector) : [];
+                            const runManualAction = async (actionName, elements) => {
+                                if (!actionName ||
+                                    !editContext ||
+                                    !manualActions?.[actionName]) {
+                                    return;
+                                }
+                                const action = manualActions[actionName];
+                                const actionProps = {
+                                    editContext,
+                                    selectorDef,
+                                    duration: HIGHLIGHT_DURATION_MS,
+                                    runId,
+                                    elements,
+                                    resolveElements,
+                                };
+                                await action(actionProps);
                             };
-                            await action(actionProps);
-                        };
-                        // Undo steps captured as we reveal, plus predicates telling whether
-                        // the revealed container is still open.
-                        const undoSteps = [];
-                        const openPredicates = [];
-                        // 1. Sidebar-only: open the sidebar.
-                        if (isSidebarOnly &&
-                            editContext?.openSidebar &&
-                            selectorDef.location) {
-                            const sidebarId = selectorDef.location;
-                            const wasOpen = !!editContext.openSidebars?.includes(sidebarId);
-                            if (!wasOpen) {
-                                editContext.openSidebar(sidebarId);
-                                undoSteps.push(() => editContextRef.current?.toggleSidebar?.(sidebarId, {
-                                    forceClose: true,
-                                }));
-                                // Give the sidebar a moment to render before querying.
-                                await new Promise((resolve) => setTimeout(resolve, 150));
+                            // Undo steps captured as we reveal, plus predicates telling
+                            // whether the revealed container is still open.
+                            const undoSteps = [];
+                            const openPredicates = [];
+                            // 1. Sidebar-only: open the sidebar.
+                            if (isSidebarOnly &&
+                                editContext?.openSidebar &&
+                                selectorDef.location) {
+                                const sidebarId = selectorDef.location;
+                                const wasOpen = !!editContext.openSidebars?.includes(sidebarId);
+                                if (!wasOpen) {
+                                    editContext.openSidebar(sidebarId);
+                                    undoSteps.push(async () => {
+                                        editContextRef.current?.toggleSidebar?.(sidebarId, {
+                                            forceClose: true,
+                                        });
+                                        await editContextRef.current?.waitForSurfaceSettled?.(`sidebar:${sidebarId}`);
+                                    });
+                                    // Wait for the sidebar's open animation to finish before querying.
+                                    await editContext.waitForSurfaceSettled?.(`sidebar:${sidebarId}`);
+                                }
+                                openPredicates.push(() => !!editContextRef.current?.openSidebars?.includes(sidebarId));
                             }
-                            openPredicates.push(() => !!editContextRef.current?.openSidebars?.includes(sidebarId));
-                        }
-                        const availabilityElements = anchorSelector
-                            ? resolveElements(anchorSelector)
-                            : [];
-                        const relevantElements = !isSidebarOnly
-                            ? [...resolveElements(), ...availabilityElements]
-                            : availabilityElements;
-                        const formSlider = getEditorFormSlider(relevantElements);
-                        const shouldOpenEditorForm = !isSidebarOnly &&
-                            !!formSlider &&
-                            isEditorFormSliderHidden(formSlider);
-                        if (selectorDef.tab) {
-                            editContext?.setActiveEditorTab(selectorDef.tab);
-                        }
-                        // 2. Editor form slider.
-                        if (shouldOpenEditorForm && editContext) {
-                            const slotId = editContext.getActiveSlotId();
-                            editContext.setEditorFormHiddenForSlot(slotId, false);
-                            undoSteps.push(() => editContextRef.current?.setEditorFormHiddenForSlot(slotId, true));
-                            openPredicates.push(() => !isEditorFormSliderHidden(getEditorFormSlider()));
-                            await waitForEditorFormSliderOpen(formSlider);
-                        }
-                        else if (selectorDef.tab) {
-                            await waitForNextFrame();
-                        }
-                        // 3. beforeAction (may open the More-panels flyout, reveal fields, etc.).
-                        const resolvedElements = !isSidebarOnly
-                            ? await waitForResolvedElements(resolveElements, selectorDef.selector)
-                            : [];
-                        const actionElements = resolvedElements.length > 0
-                            ? resolvedElements
-                            : availabilityElements;
-                        const morePanelsWasOpen = isElementPresent("@more-sidebars-panel");
-                        await runManualAction(selectorDef.beforeAction, actionElements);
-                        if (selectorDef.beforeAction === "open-more-sidebars") {
-                            const morePanelsNowOpen = isElementPresent("@more-sidebars-panel");
-                            if (!morePanelsWasOpen && morePanelsNowOpen) {
-                                undoSteps.push(() => closeMorePanelsIfOpen());
-                                openPredicates.push(() => isElementPresent("@more-sidebars-panel"));
+                            const availabilityElements = anchorSelector
+                                ? resolveElements(anchorSelector)
+                                : [];
+                            const relevantElements = !isSidebarOnly
+                                ? [...resolveElements(), ...availabilityElements]
+                                : availabilityElements;
+                            const formSlider = getEditorFormSlider(relevantElements);
+                            const shouldOpenEditorForm = !isSidebarOnly &&
+                                !!formSlider &&
+                                isEditorFormSliderHidden(formSlider);
+                            if (selectorDef.tab) {
+                                editContext?.setActiveEditorTab(selectorDef.tab);
                             }
-                        }
-                        // afterAction is the declared inverse for custom reveals (e.g. field actions).
-                        if (selectorDef.afterAction) {
-                            undoSteps.push(() => {
-                                void runManualAction(selectorDef.afterAction, !isSidebarOnly ? resolveElements() : availabilityElements);
-                            });
-                        }
-                        // Highlight the target. For sidebar-only selectors there is no inner
-                        // target, so we highlight the opened sidebar panel itself. Wait for
-                        // it to become visible first, since a just-revealed element may be
-                        // present but not yet laid out (highlightElement skips invisible ones).
-                        const highlightSelector = isSidebarOnly
-                            ? selectorDef.location
-                                ? `@sidebar-panel-${selectorDef.location}`
-                                : ""
-                            : selectorDef.selector;
-                        if (highlightSelector) {
-                            const highlightTargets = await waitForVisibleElements(highlightSelector, 1500);
-                            if (highlightTargets.length > 0) {
-                                await highlightElement(highlightSelector, HIGHLIGHT_DURATION_MS);
+                            // 2. Editor form slider.
+                            if (shouldOpenEditorForm && editContext) {
+                                const slotId = editContext.getActiveSlotId();
+                                editContext.setEditorFormHiddenForSlot(slotId, false);
+                                undoSteps.push(async () => {
+                                    editContextRef.current?.setEditorFormHiddenForSlot(slotId, true);
+                                    await editContextRef.current?.waitForSurfaceSettled?.("editor-form");
+                                });
+                                openPredicates.push(() => !isEditorFormSliderHidden(getEditorFormSlider()));
+                                await editContext.waitForSurfaceSettled?.("editor-form");
                             }
-                        }
-                        // If we opened/undid anything, this was a State-3 reveal: keep the
-                        // button active (green) and register it for mutual exclusion.
-                        if (undoSteps.length > 0) {
-                            const id = ++revealControllerSeq;
-                            controllerIdRef.current = id;
-                            revealRef.current = {
-                                id,
-                                restore: () => {
-                                    for (let i = undoSteps.length - 1; i >= 0; i -= 1) {
-                                        try {
-                                            undoSteps[i]?.();
+                            else if (selectorDef.tab) {
+                                await waitForNextFrame();
+                            }
+                            // 3. beforeAction (may open the More-panels flyout, reveal fields, etc.).
+                            const resolvedElements = !isSidebarOnly
+                                ? await waitForResolvedElements(resolveElements, selectorDef.selector)
+                                : [];
+                            const actionElements = resolvedElements.length > 0
+                                ? resolvedElements
+                                : availabilityElements;
+                            const morePanelsWasOpen = isElementPresent("@more-sidebars-panel");
+                            const versionSelectorWasOpen = isElementPresent("@version-selector-list");
+                            // Capture pre-reveal state for the AI Assistant reveals so we only
+                            // restore (close) what THIS button actually opened.
+                            const agentsPanelWasOpen = isAgentsPanelOpen();
+                            const agentSettingsWasOpen = !!selectorDef.selector &&
+                                isElementPresent(selectorDef.selector) &&
+                                selectorDef.beforeAction === "open-agent-settings";
+                            await runManualAction(selectorDef.beforeAction, actionElements);
+                            if (selectorDef.beforeAction === "open-more-sidebars") {
+                                const morePanelsNowOpen = isElementPresent("@more-sidebars-panel");
+                                if (!morePanelsWasOpen && morePanelsNowOpen) {
+                                    undoSteps.push(async () => {
+                                        closeMorePanelsIfOpen();
+                                        await waitForSelectorAnimations('[data-testid="more-sidebars-panel"]');
+                                    });
+                                    openPredicates.push(() => isElementPresent("@more-sidebars-panel"));
+                                }
+                            }
+                            if (selectorDef.beforeAction === "open-version-selector") {
+                                const versionSelectorNowOpen = isElementPresent("@version-selector-list");
+                                if (!versionSelectorWasOpen && versionSelectorNowOpen) {
+                                    undoSteps.push(async () => {
+                                        closeVersionSelectorIfOpen();
+                                        await waitForSelectorAnimations('[data-testid="version-selector-list"]');
+                                    });
+                                    openPredicates.push(() => isElementPresent("@version-selector-list"));
+                                }
+                            }
+                            if (selectorDef.beforeAction === "open-agents-panel" ||
+                                selectorDef.beforeAction === "open-agent-settings") {
+                                // The beforeAction already awaited the panel/popover open
+                                // animation (see config openAgentsPanel/openAgentSettings), so
+                                // no polling here.
+                                const agentsPanelNowOpen = isAgentsPanelOpen();
+                                // Push the panel-close undo first so that, since undo steps run
+                                // in reverse, the settings popover is closed before the panel.
+                                if (!agentsPanelWasOpen && agentsPanelNowOpen) {
+                                    undoSteps.push(async () => {
+                                        if (editContextRef.current?.isMobile) {
+                                            editContextRef.current?.toggleSidebar?.("agents-panel", {
+                                                forceClose: true,
+                                            });
+                                            await editContextRef.current?.waitForSurfaceSettled?.("sidebar:agents-panel");
                                         }
-                                        catch {
-                                            // ignore individual undo failures
+                                        else {
+                                            editContextRef.current?.setShowAgentsPanel?.(false);
+                                            await editContextRef.current?.waitForSurfaceSettled?.("agents-panel");
                                         }
+                                    });
+                                    openPredicates.push(() => isAgentsPanelOpen());
+                                }
+                                if (selectorDef.beforeAction === "open-agent-settings") {
+                                    const settingsTargetNowOpen = !!selectorDef.selector &&
+                                        isElementPresent(selectorDef.selector);
+                                    if (!agentSettingsWasOpen && settingsTargetNowOpen) {
+                                        undoSteps.push(async () => {
+                                            const trigger = document.querySelector('[data-testid="agent-settings-popover-trigger"]');
+                                            if (trigger &&
+                                                selectorDef.selector &&
+                                                isElementPresent(selectorDef.selector)) {
+                                                trigger.click();
+                                                await waitForSelectorAnimations('[data-testid="agent-settings-popover-content"]');
+                                            }
+                                        });
+                                        openPredicates.push(() => selectorDef.selector
+                                            ? isElementPresent(selectorDef.selector)
+                                            : false);
                                     }
-                                },
-                                isStillOpen: () => openPredicates.length === 0
-                                    ? true
-                                    : openPredicates.some((predicate) => predicate()),
-                            };
-                            registerActiveReveal({
-                                id,
-                                close: () => runRestoreRef.current(),
-                            });
-                            setIsActiveReveal(true);
-                            if (closeMode === "auto") {
-                                window.setTimeout(() => {
-                                    if (controllerIdRef.current === id) {
-                                        runRestoreRef.current();
-                                    }
-                                }, HIGHLIGHT_DURATION_MS);
+                                }
+                            }
+                            // afterAction is the declared inverse for custom reveals (e.g. field actions).
+                            if (selectorDef.afterAction) {
+                                undoSteps.push(async () => {
+                                    await runManualAction(selectorDef.afterAction, !isSidebarOnly ? resolveElements() : availabilityElements);
+                                });
+                            }
+                            // Highlight the target. For sidebar-only selectors there is no
+                            // inner target, so we highlight the opened sidebar panel itself.
+                            // Wait for it to become visible first, since a just-revealed
+                            // element may be present but not yet laid out (highlightElement
+                            // skips invisible ones).
+                            const highlightSelector = isSidebarOnly
+                                ? selectorDef.location
+                                    ? `@sidebar-panel-${selectorDef.location}`
+                                    : ""
+                                : selectorDef.selector;
+                            // The highlight runs a finite CSS animation; highlightElement
+                            // resolves on its animationend. We do NOT await it before
+                            // registering the reveal (the button must turn green immediately);
+                            // close=auto instead chains its restore onto this lifetime.
+                            let highlightLifetime = Promise.resolve();
+                            if (highlightSelector) {
+                                const highlightTargets = await waitForVisibleElements(highlightSelector, 1500);
+                                if (highlightTargets.length > 0) {
+                                    highlightLifetime = highlightElement(highlightSelector, HIGHLIGHT_DURATION_MS);
+                                }
                             }
+                            // If we opened/undid anything, this was a State-3 reveal: keep the
+                            // button active (green) and register it for mutual exclusion.
+                            if (undoSteps.length > 0) {
+                                const id = ++revealControllerSeq;
+                                controllerIdRef.current = id;
+                                revealRef.current = {
+                                    id,
+                                    restore: async () => {
+                                        for (let i = undoSteps.length - 1; i >= 0; i -= 1) {
+                                            try {
+                                                await undoSteps[i]?.();
+                                            }
+                                            catch {
+                                                // ignore individual undo failures
+                                            }
+                                        }
+                                    },
+                                    isStillOpen: () => openPredicates.length === 0
+                                        ? true
+                                        : openPredicates.some((predicate) => predicate()),
+                                };
+                                registerActiveReveal({
+                                    id,
+                                    close: () => runRestoreRef.current(),
+                                    isStillOpen: () => revealRef.current?.isStillOpen() ?? false,
+                                });
+                                setIsActiveReveal(true);
+                                if (closeMode === "auto") {
+                                    // Restore right after the highlight animation completes,
+                                    // instead of racing a duration-matched timer.
+                                    void highlightLifetime.then(() => {
+                                        if (controllerIdRef.current === id) {
+                                            void runRestoreRef.current();
+                                        }
+                                    });
+                                }
+                            }
+                        }
+                        finally {
+                            // Release our slot so the next queued click can proceed (and then
+                            // properly supersede us). Runs even if the reveal threw, so the
+                            // click chain can never deadlock.
+                            releaseClick();
                         }
                     }, disabled: isDisabled && !isActiveReveal, className: cn("inline-flex h-5 w-5 items-center justify-center rounded border transition-colors", isActiveReveal
                         ? "border-feedback-green bg-feedback-green-light text-feedback-green hover:bg-feedback-green-light cursor-pointer"
@@ -806,10 +957,10 @@ function renderLineWithSelectors(text, uiSelectors, manualLinkTargets, onManualL
 function renderInlineSelectorsAndFormatting(text, uiSelectors) {
     const parts = [];
     let lastIndex = 0;
-    // Combined regex for {{namedSelector}}, @selector, and **bold**
-    // Note: @selector can include -sidebar suffix for sidebar-only selectors
-    // Also supports @iframe:selector syntax (iframe: is special and allowed)
-    // Now also matches optional parentheses around selectors: ({{name}}) or (@selector)
+    // Combined regex for {{namedSelector}}, @selector, and **bold**.
+    // @selector can include -sidebar suffix for sidebar-only selectors.
+    // The matcher keeps legacy @iframe: tokens parseable, but they are unavailable.
+    // Also matches optional parentheses around selectors: ({{name}}) or (@selector).
     const regex = /(\()?(\{\{([\w\-]+)\}\})|(\()?(@(?:iframe:[\w\-\.#\[\]=]*[\w\-#\[\]=]|[\w\-\.#\[\]=]*[\w\-#\[\]=]))|(\*\*(.+?)\*\*)/g;
     let match;
     while ((match = regex.exec(text)) !== null) {