@parhelia/core 0.1.12881 → 0.1.12882

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

@@ -17,6 +17,60 @@ function SvgIcon({ svg, size, className, }) {
     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 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) {
+        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 +106,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 +129,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 +150,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);
@@ -99,8 +171,7 @@ function parseSelectorToken(selectorToken) {
     if (!selectorToken.startsWith("@"))
         return { selector: selectorToken };
     const raw = selectorToken.slice(1);
-    // Preserve iframe: selectors as unavailable selectors. Page DOM inspection now
-    // goes through the editing bridge instead of same-origin iframe probing.
+    // Preserve iframe: selectors (handled specially by expandSelector/highlightElement)
     if (raw.startsWith("iframe:"))
         return { selector: selectorToken };
     // Check for sidebar-only syntax: @sidebar-id-sidebar (e.g., @reviews-sidebar)
@@ -136,6 +207,7 @@ 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"]
@@ -144,10 +216,55 @@ export function expandSelector(selectorShorthand) {
 function getElementsForSelector(selector) {
     const cssSelector = expandSelector(selector);
     if (cssSelector.startsWith("iframe:")) {
-        return [];
+        const iframeSelector = cssSelector.substring(7);
+        const iframe = document.querySelector("iframe.page-iframe");
+        if (!iframe?.contentDocument) {
+            return [];
+        }
+        return Array.from(iframe.contentDocument.querySelectorAll(iframeSelector));
     }
     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);
@@ -185,6 +302,32 @@ 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;
@@ -199,21 +342,57 @@ 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;
+    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);
+        });
+        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);
     });
 }
-// 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;
 }
+// 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
 function showHighlightOverlay(x, y, width, height, duration) {
     const padding = 4;
@@ -265,59 +444,187 @@ function showHighlightOverlay(x, y, width, height, duration) {
         overlay.remove();
     }, duration);
 }
+let activeRevealController = null;
+let revealControllerSeq = 0;
+function registerActiveReveal(controller) {
+    const previous = activeRevealController;
+    activeRevealController = controller;
+    if (previous && previous.id !== controller.id) {
+        previous.close();
+    }
+}
+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();
+}
 // 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(() => {
+        const reveal = revealRef.current;
+        if (reveal) {
+            try {
+                reveal.restore();
+            }
+            catch {
+                // ignore restore failures
+            }
+        }
+        clearActiveReveal(reveal?.id ?? controllerIdRef.current);
+        revealRef.current = null;
+        setIsActiveReveal(false);
+    }, []);
+    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);
         };
-        // Watch the main document for changes
-        const observer = new MutationObserver(checkAvailability);
+    }, [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();
+            }
+        };
+        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;
+                        }
+                        if (isDisabled)
                             return;
                         const runId = globalThis.crypto?.randomUUID?.() ??
                             `manual-${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -337,34 +644,126 @@ function SelectorButton({ selectorDef, keyProp, }) {
                             };
                             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 &&
+                        // 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 isSidebarAlreadyOpen = !!editContext.openSidebars?.includes(sidebarId);
-                            if (!isSidebarAlreadyOpen) {
+                            const wasOpen = !!editContext.openSidebars?.includes(sidebarId);
+                            if (!wasOpen) {
                                 editContext.openSidebar(sidebarId);
-                                // Give the sidebar a moment to render before querying/highlighting.
+                                undoSteps.push(() => editContextRef.current?.toggleSidebar?.(sidebarId, {
+                                    forceClose: true,
+                                }));
+                                // Give the sidebar a moment to render before querying.
                                 await new Promise((resolve) => setTimeout(resolve, 150));
                             }
+                            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();
                         }
-                        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);
+                        // 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"));
+                            }
                         }
+                        // afterAction is the declared inverse for custom reveals (e.g. field actions).
                         if (selectorDef.afterAction) {
-                            window.setTimeout(() => {
-                                void runManualAction(selectorDef.afterAction, !isSidebarOnly ? resolveElements() : []);
-                            }, HIGHLIGHT_DURATION_MS);
+                            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);
+                            }
+                        }
+                        // 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]?.();
+                                        }
+                                        catch {
+                                            // ignore individual undo failures
+                                        }
+                                    }
+                                },
+                                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);
+                            }
                         }
-                    }, 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
@@ -407,10 +806,10 @@ function renderLineWithSelectors(text, uiSelectors, manualLinkTargets, onManualL
 function renderInlineSelectorsAndFormatting(text, uiSelectors) {
     const parts = [];
     let lastIndex = 0;
-    // 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).
+    // 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)
     const regex = /(\()?(\{\{([\w\-]+)\}\})|(\()?(@(?:iframe:[\w\-\.#\[\]=]*[\w\-#\[\]=]|[\w\-\.#\[\]=]*[\w\-#\[\]=]))|(\*\*(.+?)\*\*)/g;
     let match;
     while ((match = regex.exec(text)) !== null) {