fix(overlay): stop the hover-driven relayout storm that hid the pill

Two multipliers behind 'the menu disappears when I hover over it and then
off it, on scrollable screens'.

AXIntrospection.appElement() WROTE AXEnhancedUserInterface on every call,
and the catcher calls it from the hover hit-test at up to 60Hz. That
attribute announces an assistive client, and AppKit answers by
re-evaluating and relaying out its windows -- so a moving pointer drove a
resize storm in the host. Hovering ONTO the pill stops the writes (the
pill consumes hover, so the catcher sees .ended and queries nothing) and
moving OFF restarts them, which is exactly the reported trigger. Scrollable
screens surfaced it first because a large scroll view is a large AX tree,
so materialising it costs a real layout pass. It is now set once per
process and the element is cached.

Each resulting resize then pushed a fresh SwiftUI root view, tearing the
pill down and rebuilding it mid-hover. syncFrameAndOrigin() now skips that
when neither axOrigin nor surfaceSize changed, while still recording the
host frame for the settle poll and still rebuilding on a REAL change.

Both pinned by mutation-verified tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: angusbezzina

Sources/AnnotKit/macOS/AXIntrospection.swift

@@ -97,12 +97,39 @@ enum AXIntrospection {
 
     // MARK: - Application element
 
-    /// Our own application AX element, with `AXEnhancedUserInterface` set so
-    /// AppKit/SwiftUI materializes the full semantic tree for us. Self-query
-    /// needs no accessibility-trust prompt.
+    /// The process's application AX element, cached, with `AXEnhancedUserInterface`
+    /// set EXACTLY ONCE so AppKit/SwiftUI materializes the full semantic tree for us.
+    /// Self-query needs no accessibility-trust prompt.
+    ///
+    /// Setting that attribute once is load-bearing, not an optimization. It was
+    /// previously re-set on every call — and this is called from the HOVER hit-test,
+    /// which the catcher runs at up to 60Hz while the pointer moves. Writing
+    /// `AXEnhancedUserInterface` tells AppKit an assistive client just attached, and
+    /// AppKit responds by re-evaluating (and, on SwiftUI hosts, relaying out) its
+    /// windows; doing that 60 times a second drove a resize storm in the host, each
+    /// resize firing `didResize` -> `syncFrameAndOrigin()` -> a fresh SwiftUI root
+    /// view, which is what made the toolbar pill visibly vanish.
+    ///
+    /// The reported trigger pinpointed it: hovering ONTO the pill stops the storm
+    /// (the pill consumes hover, so the catcher sees `.ended` and queries nothing)
+    /// and moving OFF it restarts them. It showed up on scrollable screens because a
+    /// large scroll view is a large AX tree, so materializing it is far more likely
+    /// to cost a real layout pass.
+    ///
+    /// The element itself is stable for the life of the process, so caching it also
+    /// drops an `AXUIElementCreateApplication` per query.
+    private static var cachedAppElement: AXUIElement?
+    /// How many times `AXEnhancedUserInterface` has been written. Must never exceed 1;
+    /// the probe asserts it across a hover storm so the regression cannot come back
+    /// silently.
+    private(set) static var enhancedUserInterfaceWrites = 0
+
     private static func appElement() -> AXUIElement {
+        if let cachedAppElement { return cachedAppElement }
         let app = AXUIElementCreateApplication(ProcessInfo.processInfo.processIdentifier)
         AXUIElementSetAttributeValue(app, "AXEnhancedUserInterface" as CFString, kCFBooleanTrue)
+        enhancedUserInterfaceWrites += 1
+        cachedAppElement = app
         return app
     }
 

Sources/AnnotKit/macOS/OverlayController.swift

@@ -35,6 +35,10 @@ public final class OverlayController: NSObject {
     private var axOrigin: CGPoint = .zero
     /// Panel-local size, for clamping the composer inside the visible region.
     private var surfaceSize: CGSize = .zero
+    /// How many times a fresh SwiftUI root view has been pushed into the hosting view.
+    /// Rebuilding it mid-hover is what makes the pill flicker or vanish, so the probe
+    /// asserts a storm of redundant geometry notifications pushes none.
+    private(set) var rootViewPushes = 0
 
     /// Host frame captured at the last geometry sync. A SwiftUI/content-sized host
     /// can attach at its PRE-LAYOUT frame and grow to its final size a runloop turn
@@ -374,9 +378,21 @@ public final class OverlayController: NSObject {
         // the VISIBLE region rather than inside a window that runs off the display.
         // Clamping the TOP (a host tucked under the menu bar) genuinely does move the
         // origin, and that is the case a host-derived origin breaks silently.
-        axOrigin = ScreenSpace.windowAXOrigin(cocoaFrame: panelFrame, primaryHeight: primaryHeight)
-        surfaceSize = panelFrame.size
+        let newAXOrigin = ScreenSpace.windowAXOrigin(cocoaFrame: panelFrame, primaryHeight: primaryHeight)
+        // Always record the host frame, even on the early-out below: the settle poll
+        // decides "has the host stopped growing" by comparing against this, so leaving
+        // it stale would keep the poll re-syncing a window that has already settled.
         lastSyncedHostFrame = host.frame
+        // Push a new SwiftUI root view ONLY when something it renders from actually
+        // changed. `syncFrameAndOrigin()` runs on every move/resize/screen-parameter
+        // notification, and a host that emits a burst of them (a relayout storm, a live
+        // resize drag) would otherwise replace the root view on each one — tearing down
+        // and rebuilding the pill mid-hover, which reads as the toolbar flickering or
+        // vanishing. Cheap guard, and it makes a redundant notification free.
+        guard newAXOrigin != axOrigin || panelFrame.size != surfaceSize else { return }
+        axOrigin = newAXOrigin
+        surfaceSize = panelFrame.size
+        rootViewPushes += 1
         hostingView?.rootView = makeRootView()
     }
 

Tests/AnnotKitTests/HoverStormTests.swift

@@ -0,0 +1,107 @@
+#if os(macOS)
+import AppKit
+import CoreGraphics
+import Foundation
+import XCTest
+@testable import AnnotKit
+
+/// The vanishing-pill regression, reported as: "the menu disappears when I hover over
+/// it and then off it, on scrollable screens."
+///
+/// Two multipliers, both fixed, both pinned here:
+///
+/// 1. `AXIntrospection.appElement()` WROTE `AXEnhancedUserInterface` on every call,
+///    and the catcher calls it from the hover hit-test at up to 60Hz. That attribute
+///    announces an assistive client; AppKit answers by re-evaluating and relaying out
+///    its windows, so a moving pointer drove a resize storm in the host.
+/// 2. Every resulting resize pushed a FRESH SwiftUI root view, tearing the pill down
+///    and rebuilding it mid-hover.
+///
+/// The reported trigger is what identified it: hovering ONTO the pill stops the
+/// writes — the pill consumes hover, so the catcher sees `.ended` and queries nothing
+/// — and moving OFF restarts them. Scrollable screens showed it first because a large
+/// scroll view is a large AX tree, so materializing it costs a real layout pass.
+@MainActor
+final class HoverStormTests: XCTestCase {
+    /// A hover storm must write the AX attribute ZERO extra times.
+    ///
+    /// `snapshot()` goes through the same `appElement()` every hover hit-test uses, so
+    /// this exercises the real path without needing a live window. The first call in
+    /// the process may legitimately write once; what must never happen again is a
+    /// second write, let alone one per query.
+    func testHoverStormDoesNotRewriteTheEnhancedUIAttribute() {
+        _ = NSApplication.shared
+        // Prime the cache so this test is independent of whichever test ran first.
+        _ = AXIntrospection.snapshot()
+        let writesAfterPriming = AXIntrospection.enhancedUserInterfaceWrites
+        XCTAssertLessThanOrEqual(writesAfterPriming, 1, "the attribute is set once per process, not per query")
+
+        // ~3 seconds of real 60Hz hovering.
+        for _ in 0 ..< 200 { _ = AXIntrospection.snapshot() }
+
+        XCTAssertEqual(AXIntrospection.enhancedUserInterfaceWrites, writesAfterPriming,
+                       "200 queries wrote AXEnhancedUserInterface again — this is the resize storm that ate the pill")
+    }
+
+    /// Redundant geometry notifications must not rebuild the overlay's SwiftUI root.
+    ///
+    /// A relayout storm arrives as a burst of `didResize`/`didMove`. None of them
+    /// change the panel's geometry, so none may tear down and rebuild the pill — that
+    /// rebuild is what the user SEES as the toolbar vanishing.
+    func testRedundantGeometryNotificationsDoNotRebuildTheOverlay() {
+        _ = NSApplication.shared
+        let host = NSWindow(contentRect: NSRect(x: 200, y: 200, width: 640, height: 480),
+                            styleMask: [.titled, .resizable], backing: .buffered, defer: false)
+        host.orderFront(nil)
+        defer { host.orderOut(nil) }
+
+        let controller = OverlayController(
+            session: AnnotationSession(source: MacElementSource(), sink: NotesFileSink(path: "/dev/null"))
+        )
+        controller.mount(on: host)
+        defer { controller.unmount() }
+
+        let pushesBefore = controller.rootViewPushes
+        let frameBefore = host.childWindows?.first?.frame
+
+        for _ in 0 ..< 50 {
+            NotificationCenter.default.post(name: NSWindow.didResizeNotification, object: host)
+            NotificationCenter.default.post(name: NSWindow.didMoveNotification, object: host)
+        }
+
+        XCTAssertEqual(controller.rootViewPushes, pushesBefore,
+                       "100 redundant notifications rebuilt the pill — mid-hover that reads as it vanishing")
+        XCTAssertEqual(host.childWindows?.first?.frame, frameBefore, "and the panel must not have moved")
+    }
+
+    /// The guard must skip REDUNDANT syncs, not all of them.
+    ///
+    /// An idempotence check that silently stopped syncing would be a far worse bug
+    /// than the flicker it fixes: the panel would drift away from a host that really
+    /// did move.
+    func testARealResizeStillRebuildsTheOverlay() {
+        _ = NSApplication.shared
+        let host = NSWindow(contentRect: NSRect(x: 200, y: 200, width: 640, height: 480),
+                            styleMask: [.titled, .resizable], backing: .buffered, defer: false)
+        host.orderFront(nil)
+        defer { host.orderOut(nil) }
+
+        let controller = OverlayController(
+            session: AnnotationSession(source: MacElementSource(), sink: NotesFileSink(path: "/dev/null"))
+        )
+        controller.mount(on: host)
+        defer { controller.unmount() }
+
+        let pushesBefore = controller.rootViewPushes
+        // MOVE the host rather than growing it. In idle mode the panel is a fixed-size
+        // corner pinned to the host's BOTTOM edge, so growing the window upward leaves
+        // the panel exactly where it was — the guard correctly skips that, and a test
+        // built on it would be asserting the guard is broken.
+        host.setFrameOrigin(NSPoint(x: host.frame.minX + 140, y: host.frame.minY + 90))
+        NotificationCenter.default.post(name: NSWindow.didMoveNotification, object: host)
+
+        XCTAssertGreaterThan(controller.rootViewPushes, pushesBefore,
+                             "a real resize must still push a new root view, or the overlay stops tracking its host")
+    }
+}
+#endif