@parhelia/core 0.1.12881 → 0.1.12883

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

@@ -11,12 +11,58 @@ 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();
     return (_jsx("span", { className: cn("inline-flex items-center justify-center [&>svg]:block [&>svg]:h-full [&>svg]:w-full", className), style: { width: size, height: size }, dangerouslySetInnerHTML: { __html: sanitizedSvg } }));
 }
 const HIGHLIGHT_DURATION_MS = 2000;
+const EDITOR_FORM_SLIDER_SELECTOR = '[data-testid="editor-form-slider"]';
+const EDITOR_FORM_HIDDEN_ATTRIBUTE = "aria-hidden";
+const CLOSE_PANE_LABEL = "Close pane";
+function waitForDelay(delayMs) {
+    return new Promise((resolve) => {
+        window.setTimeout(resolve, delayMs);
+    });
+}
+function getEditorFormSlider(elements = []) {
+    for (const element of elements) {
+        const slider = element.closest(EDITOR_FORM_SLIDER_SELECTOR);
+        if (slider) {
+            return slider;
+        }
+    }
+    return document.querySelector(EDITOR_FORM_SLIDER_SELECTOR);
+}
+function isEditorFormSliderHidden(slider) {
+    return slider?.getAttribute(EDITOR_FORM_HIDDEN_ATTRIBUTE) === "true";
+}
+async function waitForResolvedElements(resolveElements, selector, timeoutMs = 1000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const elements = resolveElements(selector);
+        if (elements.length > 0) {
+            return elements;
+        }
+        await waitForDelay(50);
+    }
+    return resolveElements(selector);
+}
+// Wait until at least one element for the selector is actually VISIBLE (not just
+// present). After a reveal/animation a target can be in the DOM but not yet laid
+// out, which would otherwise cause highlightElement to skip it.
+async function waitForVisibleElements(selector, timeoutMs = 1000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const elements = getVisibleElementsForSelector(selector);
+        if (elements.length > 0) {
+            return elements;
+        }
+        await waitForDelay(50);
+    }
+    return getVisibleElementsForSelector(selector);
+}
 const manualMarkdownComponents = {
     h1: ({ children }) => (_jsx("h1", { className: "text-neutral-grey-100 mt-4 mb-0 text-xl font-bold", children: children })),
     h2: ({ children }) => (_jsx("h2", { className: "text-neutral-grey-100 mt-3 mb-0 text-lg font-semibold", children: children })),
@@ -52,7 +98,15 @@ export function parseUiSelectors(uiSelectors) {
             let beforeAction;
             let afterAction;
             let availabilitySelector;
+            let selectorOverride;
+            let tab;
+            let closeMode;
             for (const segment of segments) {
+                if (segment.startsWith("close=")) {
+                    const value = segment.substring("close=".length).trim();
+                    closeMode = value === "auto" ? "auto" : "click";
+                    continue;
+                }
                 if (segment.startsWith("beforeAction=")) {
                     beforeAction = segment.substring("beforeAction=".length).trim();
                     continue;
@@ -67,6 +121,14 @@ export function parseUiSelectors(uiSelectors) {
                         .trim();
                     continue;
                 }
+                if (segment.startsWith("selector=")) {
+                    selectorOverride = segment.substring("selector=".length).trim();
+                    continue;
+                }
+                if (segment.startsWith("tab=")) {
+                    tab = segment.substring("tab=".length).trim();
+                    continue;
+                }
                 if (!notFoundMessage) {
                     notFoundMessage = segment;
                 }
@@ -80,14 +142,16 @@ export function parseUiSelectors(uiSelectors) {
                 : undefined;
             const parsed = {
                 name,
-                selector: isSidebarOnly ? "" : `@${name}`, // Empty selector for sidebar-only
+                selector: isSidebarOnly ? "" : selectorOverride || `@${name}`,
                 availabilitySelector,
+                tab,
                 description,
                 notFoundMessage: notFoundMessage || undefined,
                 location: isSidebarOnly ? sidebarId : undefined, // Use actual sidebar ID (without -sidebar suffix) for sidebar-only
                 isSidebarOnly,
                 beforeAction,
                 afterAction,
+                closeMode,
             };
             // Primary key remains the selector name
             map.set(name, parsed);
@@ -148,6 +212,46 @@ function getElementsForSelector(selector) {
     }
     return Array.from(document.querySelectorAll(cssSelector));
 }
+// Determine whether an element is genuinely visible to the user, not merely
+// present in the DOM. A target sitting inside a collapsed panel, a hidden
+// sidebar (aria-hidden), or with `display:none` / `visibility:hidden` / zero
+// size counts as NOT visible.
+function isElementVisible(element) {
+    // Treat anything inside an explicitly aria-hidden container (e.g. a collapsed
+    // editor form slider) as not visible.
+    if (element.closest('[aria-hidden="true"]')) {
+        return false;
+    }
+    const candidate = element;
+    if (typeof candidate.checkVisibility === "function") {
+        if (!candidate.checkVisibility({
+            checkOpacity: true,
+            checkVisibilityCSS: true,
+        })) {
+            return false;
+        }
+    }
+    else {
+        // Fallback for environments without Element.checkVisibility (e.g. jsdom).
+        const style = window.getComputedStyle(element);
+        if (style.display === "none" ||
+            style.visibility === "hidden" ||
+            style.visibility === "collapse") {
+            return false;
+        }
+        // position:fixed elements have a null offsetParent but can still be visible.
+        if (element.offsetParent === null && style.position !== "fixed") {
+            return false;
+        }
+    }
+    // Reject zero-area elements (e.g. a width:0 collapsed panel).
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+}
+// Return only the elements matching a selector that are currently visible.
+function getVisibleElementsForSelector(selector) {
+    return getElementsForSelector(selector).filter(isElementVisible);
+}
 function shouldSkipHighlightScroll(element) {
     const rect = element.getBoundingClientRect();
     const computedStyle = window.getComputedStyle(element);
@@ -199,22 +303,60 @@ async function scrollElementForHighlight(element) {
 // Highlight an element temporarily
 export async function highlightElement(selector, duration = HIGHLIGHT_DURATION_MS) {
     const cssSelector = expandSelector(selector);
-    const elements = getElementsForSelector(selector);
+    // Only ever highlight elements that are actually visible. A target inside a
+    // collapsed panel or hidden sidebar must not receive a stray overlay.
+    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]);
+        }
+        elements.forEach((element) => {
+            const elementRect = element.getBoundingClientRect();
+            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]);
     }
     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 available in the DOM
-function isElementAvailable(selector) {
+// Check if an element is currently present in the DOM (regardless of visibility)
+function isElementPresent(selector) {
     return getElementsForSelector(selector).length > 0;
 }
-// Create a temporary highlight overlay
+// Check if an element matching the selector is currently visible to the user
+function isElementVisibleBySelector(selector) {
+    return getVisibleElementsForSelector(selector).length > 0;
+}
+export function deriveSelectorState(params) {
+    if (!params.isAnchorReachable) {
+        return "disabled";
+    }
+    // Sidebar-only selectors have no element to "see"; opening the sidebar is the action.
+    if (params.isSidebarOnly) {
+        return "show-action";
+    }
+    if (params.isTargetVisible) {
+        return "show";
+    }
+    if (params.hasRevealPath) {
+        return "show-action";
+    }
+    return "disabled";
+}
+// 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;
@@ -231,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;
@@ -245,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
@@ -257,114 +401,492 @@ 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) {
+    activeRevealController = controller;
+}
+// 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) {
+        activeRevealController = null;
+    }
+}
+// Close the More-panels flyout if it is currently open (inverse of open-more-sidebars).
+function closeMorePanelsIfOpen() {
+    if (!isElementPresent("@more-sidebars-panel"))
+        return;
+    const trigger = document.querySelector('[data-testid="more-sidebars-button"]');
+    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();
     const manualActions = editContext?.configuration.editor.manualActions;
-    const availabilitySelector = selectorDef.availabilitySelector || selectorDef.selector;
-    // For sidebar-only selectors, we don't need to check for an element
-    const isSidebarOnly = selectorDef.isSidebarOnly;
-    // Initialize to true for sidebar-only, false otherwise to avoid hydration mismatch
-    // (document.querySelector doesn't exist during SSR)
-    const [isAvailable, setIsAvailable] = useState(isSidebarOnly ? true : false);
-    // Can open sidebar if: sidebar-only selector
-    const canAutoOpenSidebar = Boolean(isSidebarOnly && editContext?.openSidebar && selectorDef.location);
+    const isSidebarOnly = !!selectorDef.isSidebarOnly;
+    const targetSelector = selectorDef.selector;
+    // Anchor = explicit availabilitySelector only. It gates the disabled state.
+    const anchorSelector = selectorDef.availabilitySelector;
+    const hasAvailabilitySelector = Boolean(anchorSelector);
+    const closeMode = selectorDef.closeMode ?? "click";
+    // Keep a fresh reference to editContext for use inside reveal/restore closures.
+    const editContextRef = useRef(editContext);
+    editContextRef.current = editContext;
     const hasBeforeAction = Boolean(selectorDef.beforeAction &&
         manualActions?.[selectorDef.beforeAction] &&
         editContext);
-    const isActionable = isSidebarOnly
-        ? canAutoOpenSidebar || hasBeforeAction
-        : isAvailable || canAutoOpenSidebar || hasBeforeAction;
-    // Monitor for element availability changes (skip for sidebar-only selectors)
+    // A sidebar-only selector is reachable only when the current workspace
+    // supports sidebars and offers this specific sidebar (both are workspace-scoped).
+    const canAutoOpenSidebar = Boolean(isSidebarOnly &&
+        selectorDef.location &&
+        editContext?.openSidebar &&
+        editContext.workspace?.supportsSidebars &&
+        editContext.availableSidebars?.some((s) => s.id === selectorDef.location));
+    // Presence/visibility probes, kept up to date by the effect below.
+    // The anchor gates "is this relevant in the current context", so it checks
+    // presence (it may itself be a currently-collapsed container). The target
+    // checks visibility to distinguish "show" from "show-action".
+    const [isTargetPresent, setIsTargetPresent] = useState(false);
+    const [isTargetVisible, setIsTargetVisible] = useState(false);
+    const [isAnchorPresent, setIsAnchorPresent] = useState(false);
+    // True while THIS button has revealed a container (State 3 active -> green).
+    const [isActiveReveal, setIsActiveReveal] = useState(false);
+    const controllerIdRef = useRef(0);
+    const revealRef = useRef(null);
+    const isAnchorReachable = hasAvailabilitySelector
+        ? isAnchorPresent
+        : isSidebarOnly
+            ? canAutoOpenSidebar
+            : isTargetPresent || hasBeforeAction;
+    const hasRevealPath = isSidebarOnly || hasBeforeAction || canAutoOpenSidebar || isTargetPresent;
+    const state = deriveSelectorState({
+        isSidebarOnly,
+        isAnchorReachable,
+        isTargetVisible,
+        hasRevealPath,
+    });
+    const isDisabled = state === "disabled";
+    // Reset active (green) state WITHOUT running the undo steps. Used when the
+    // revealed container was closed by some other means.
+    const resetActiveState = useCallback(() => {
+        clearActiveReveal(controllerIdRef.current);
+        revealRef.current = null;
+        setIsActiveReveal(false);
+    }, []);
+    // 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(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 {
+                await reveal.restore();
+            }
+            catch {
+                // ignore restore failures
+            }
+        }
+    }, []);
+    const runRestoreRef = useRef(runRestore);
+    runRestoreRef.current = runRestore;
+    // Keep the presence/visibility probes fresh.
     useEffect(() => {
-        // Sidebar-only selectors are always "available" if openSidebar exists
-        if (isSidebarOnly) {
-            setIsAvailable(true);
-            return;
+        const check = () => {
+            setIsTargetPresent(targetSelector ? isElementPresent(targetSelector) : false);
+            setIsTargetVisible(targetSelector ? isElementVisibleBySelector(targetSelector) : false);
+            setIsAnchorPresent(anchorSelector ? isElementPresent(anchorSelector) : false);
+        };
+        check();
+        const attributeFilter = [
+            "data-testid",
+            "class",
+            "id",
+            "style",
+            "hidden",
+            "aria-hidden",
+        ];
+        const observer = new MutationObserver(check);
+        observer.observe(document.body, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter,
+        });
+        let iframeObserver = null;
+        const iframe = document.querySelector("iframe.page-iframe");
+        if (iframe?.contentDocument?.body) {
+            iframeObserver = new MutationObserver(check);
+            iframeObserver.observe(iframe.contentDocument.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                attributeFilter,
+            });
         }
-        // Initial check
-        const initialAvailable = isElementAvailable(availabilitySelector);
-        setIsAvailable(initialAvailable);
-        // Set up MutationObserver to watch for DOM changes
-        const checkAvailability = () => {
-            const available = isElementAvailable(availabilitySelector);
-            setIsAvailable(available);
+        const intervalId = setInterval(check, 1000);
+        return () => {
+            observer.disconnect();
+            iframeObserver?.disconnect();
+            clearInterval(intervalId);
+        };
+    }, [targetSelector, anchorSelector]);
+    // While active, detect if the revealed container was closed externally and
+    // reset the button's active (green) state accordingly.
+    useEffect(() => {
+        if (!isActiveReveal)
+            return;
+        const check = () => {
+            const reveal = revealRef.current;
+            if (!reveal || !reveal.isStillOpen()) {
+                resetActiveState();
+            }
         };
-        // Watch the main document for changes
-        const observer = new MutationObserver(checkAvailability);
+        const observer = new MutationObserver(check);
         observer.observe(document.body, {
             childList: true,
             subtree: true,
             attributes: true,
-            attributeFilter: ["data-testid", "class", "id"],
+            attributeFilter: [
+                EDITOR_FORM_HIDDEN_ATTRIBUTE,
+                "class",
+                "style",
+                "data-testid",
+            ],
         });
-        // Also poll periodically as a fallback for async UI updates.
-        const intervalId = setInterval(checkAvailability, 1000);
+        const intervalId = setInterval(check, 500);
         return () => {
             observer.disconnect();
             clearInterval(intervalId);
         };
-    }, [availabilitySelector, isSidebarOnly]);
-    const tooltipText = isActionable
-        ? selectorDef.description
-        : selectorDef.notFoundMessage || selectorDef.description;
-    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs("button", { "aria-label": "Show me", onClick: async () => {
-                        if (!isActionable)
+    }, [isActiveReveal, resetActiveState]);
+    // Clear the global active controller if this button unmounts while active.
+    useEffect(() => {
+        return () => {
+            clearActiveReveal(controllerIdRef.current);
+        };
+    }, []);
+    const tooltipText = isActiveReveal
+        ? CLOSE_PANE_LABEL
+        : isDisabled
+            ? selectorDef.notFoundMessage || selectorDef.description
+            : selectorDef.description;
+    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs("button", { "aria-label": isActiveReveal ? CLOSE_PANE_LABEL : "Show me", onClick: async () => {
+                        // Second click while active -> restore (close=click behaviour).
+                        if (isActiveReveal) {
+                            runRestore();
                             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]) {
+                        }
+                        if (isDisabled)
+                            return;
+                        // 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);
-                        };
-                        // If this selector is sidebar-only, open the sidebar before highlighting.
-                        // For sidebar-only selectors, location is the sidebar ID (without -sidebar suffix)
-                        if (selectorDef.isSidebarOnly &&
-                            editContext?.openSidebar &&
-                            selectorDef.location) {
-                            const sidebarId = selectorDef.location;
-                            const isSidebarAlreadyOpen = !!editContext.openSidebars?.includes(sidebarId);
-                            if (!isSidebarAlreadyOpen) {
-                                editContext.openSidebar(sidebarId);
-                                // Give the sidebar a moment to render before querying/highlighting.
-                                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));
+                            }
+                            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(async () => {
+                                    editContextRef.current?.setEditorFormHiddenForSlot(slotId, true);
+                                    await editContextRef.current?.waitForSurfaceSettled?.("editor-form");
+                                });
+                                openPredicates.push(() => !isEditorFormSliderHidden(getEditorFormSlider()));
+                                await editContext.waitForSurfaceSettled?.("editor-form");
+                            }
+                            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");
+                            // 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-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");
+                                        }
+                                        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);
+                                    }
+                                }
+                            }
+                            // 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();
+                                        }
+                                    });
+                                }
                             }
                         }
-                        const resolvedElements = !isSidebarOnly ? resolveElements() : [];
-                        await runManualAction(selectorDef.beforeAction, resolvedElements);
-                        // For sidebar-only selectors, we just open the sidebar (done above)
-                        // For regular selectors, also highlight the element
-                        if (!isSidebarOnly && selectorDef.selector) {
-                            await highlightElement(selectorDef.selector, HIGHLIGHT_DURATION_MS);
-                        }
-                        if (selectorDef.afterAction) {
-                            window.setTimeout(() => {
-                                void runManualAction(selectorDef.afterAction, !isSidebarOnly ? resolveElements() : []);
-                            }, HIGHLIGHT_DURATION_MS);
+                        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: !isActionable, className: cn("inline-flex h-5 w-5 items-center justify-center rounded border transition-colors", isActionable
-                        ? "border-feedback-blue bg-feedback-blue-light text-feedback-blue hover:bg-feedback-blue-light cursor-pointer"
-                        : "border-border-default bg-neutral-grey-5 text-neutral-grey-50 cursor-not-allowed"), children: [_jsx(LocateFixed, { className: "h-3.5 w-3.5", strokeWidth: 1.5 }), _jsx("span", { className: "sr-only", children: "Show me" })] }, keyProp) }), _jsx(TooltipContent, { children: tooltipText })] }));
+                    }, 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"
+                        : !isDisabled
+                            ? "border-feedback-blue bg-feedback-blue-light text-feedback-blue hover:bg-feedback-blue-light cursor-pointer"
+                            : "border-border-default bg-neutral-grey-5 text-neutral-grey-50 cursor-not-allowed"), children: [_jsx(LocateFixed, { className: "h-3.5 w-3.5", strokeWidth: 1.5 }), _jsx("span", { className: "sr-only", children: "Show me" })] }, keyProp) }), _jsx(TooltipContent, { children: tooltipText })] }));
 }
 // Render markdown content with clickable selectors
 // Supports both {{selectorName}} syntax (looks up in uiSelectors) and legacy @selector syntax