fix(overlay): even idle pill inset, chrome-proof hit-test, hover-exit clearing, container surfaces

Four fixes from the first real dogfood on VirgilHUD (all probe-covered):

- Idle pill: EVEN 8pt inset around the single pencil button (concentric 44x44
  capsule) instead of the 4-button row's 6/8pt padding, which read as lopsided.

- Hit-test: window chrome is never an annotation target. The traffic lights are
  actionable AXButtons that passed the resolvers; rejected via subrole at chain
  level PLUS a geometric backstop (the zoom button nests a glyph AXGroup whose
  reported AX parent is the WINDOW, so a chain scan alone misses it). Also:
  descend to the SMALLEST containing child (AX order does not encode z-order),
  and never fall back to an unidentified structural group spanning the whole
  window (NSHostingView's root).

- Hover: clear the highlight when the cursor leaves the catcher (HoverPhase
  .ended) — the last-hovered element used to stay highlighted after the cursor
  left the app. New AnnotationSession.clearHover() keeps selection untouched.

- Containers: probed that a children-.contain group reports the UNION of its
  children as its AX frame (card padding dead to hover); the working pattern is
  a full-size clear background leaf carrying the identifier, validated by the
  new overlay-probe Phase 5.

Probe: +Phase 4 (chrome exclusion through the expanded overlay, incl. positive
control) and +Phase 5 (container surface body-hover), plus W1 window hygiene.
Tests: +clearHover, +chrome-subrole predicate (47 total).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: angusbezzina

Sources/AnnotKit/Overlay/AnnotationSession.swift

@@ -77,6 +77,12 @@ public final class AnnotationSession: ObservableObject {
         hovered = source.hitTest(point)
     }
 
+    /// Drop the hover highlight — the cursor left the annotatable surface, so
+    /// nothing is hovered. `selected` (an open composer) is deliberately kept.
+    public func clearHover() {
+        hovered = nil
+    }
+
     /// Select the element under a screen point (AX top-left coordinates).
     @discardableResult
     public func select(atAXPoint point: CGPoint) -> Element? {

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -96,8 +96,17 @@ struct OverlayView: View {
             Color.clear
                 .contentShape(Rectangle())
                 .onContinuousHover { phase in
-                    if case .active(let point) = phase {
+                    switch phase {
+                    case .active(let point):
                         session.hover(atAXPoint: CGPoint(x: point.x + axOrigin.x, y: point.y + axOrigin.y))
+                    case .ended:
+                        // The cursor left the catcher (it covers the host's full
+                        // frame, so this is "left the window" — or moved onto the
+                        // toolbar/composer, which consume hover). Nothing is
+                        // hovered: drop the highlight instead of freezing on the
+                        // last element. An open composer is unaffected (the
+                        // highlight renders selected ?? hovered).
+                        session.clearHover()
                     }
                 }
                 .gesture(
@@ -437,7 +446,11 @@ private struct ToolbarView: View {
                 }
             }
         }
-        .padding(.horizontal, 6)
+        // Idle shows ONE 28pt button, so the inset must be EVEN (8pt all around ->
+        // a concentric 44x44 capsule hugging the hover wash). The 6pt horizontal
+        // inset is for the annotate-mode 4-button ROW only, where the buttons'
+        // own spacing makes the tighter ends read as balanced.
+        .padding(.horizontal, annotating ? 6 : 8)
         .padding(.vertical, 8) // 28pt buttons + 8*2 -> 44pt pill height
         .background(
             Capsule(style: .continuous)

Sources/AnnotKit/macOS/AXIntrospection.swift

@@ -250,6 +250,18 @@ enum AXIntrospection {
 
         let chain = ancestorChain(from: deepest)
         guard !chain.isEmpty else { return nil }
+        // A hit through window CHROME (the traffic lights) is not annotatable at
+        // ANY level: the hit itself may be the button or one of its inner glyph
+        // groups, and everything above it is the title bar / window. Two checks,
+        // because the glyph groups report the WINDOW (not the button) as their
+        // AX parent, so the chain scan alone can miss them — the geometric
+        // backstop catches any query point inside a chrome button's frame.
+        if chain.contains(where: isChrome) { return nil }
+        if let window = chain.first(where: { string($0, kAXRoleAttribute) == "AXWindow" }),
+           elementArray(window, kAXChildrenAttribute)
+               .contains(where: { isChrome($0) && frameScreen(of: $0).contains(point) }) {
+            return nil
+        }
         // Never fall back to the window or application container: escalating to
         // AXWindow is what made a background click resolve to the whole app.
         guard let target = nearestIdentified(in: chain) ?? deepestNonContainer(in: chain) else {
@@ -273,17 +285,27 @@ enum AXIntrospection {
     }
 
     /// Deepest descendant of `element` whose (non-empty) frame contains `point`.
-    /// Later children are drawn on top, so a topmost match wins; returns
-    /// `element` itself when no child contains the point.
+    /// Among children containing the point, descend into the SMALLEST (most
+    /// specific) one: AX child order does not reliably encode z-order, so a
+    /// full-size sibling layer (a window's title-bar strip, or a card's clear
+    /// accessibility surface in `.background`) must not swallow the more
+    /// specific content that visually sits above it. Returns `element` itself
+    /// when no child contains the point.
     private static func deepestChild(of element: AXUIElement, containing point: CGPoint, depth: Int) -> AXUIElement {
         guard depth < maxDepth else { return element }
-        for child in elementArray(element, kAXChildrenAttribute).reversed() {
-            let frame = frameScreen(of: child)
-            if frame.width > 0, frame.height > 0, frame.contains(point) {
-                return deepestChild(of: child, containing: point, depth: depth + 1)
+        let candidate = elementArray(element, kAXChildrenAttribute)
+            .filter {
+                let frame = frameScreen(of: $0)
+                return frame.width > 0 && frame.height > 0 && frame.contains(point)
             }
-        }
-        return element
+            .min { area(of: $0) < area(of: $1) }
+        guard let candidate else { return element }
+        return deepestChild(of: candidate, containing: point, depth: depth + 1)
+    }
+
+    private static func area(of element: AXUIElement) -> CGFloat {
+        let frame = frameScreen(of: element)
+        return frame.width * frame.height
     }
 
     /// Climb `kAXParentAttribute` from `element` up to the window, returning the
@@ -307,6 +329,29 @@ enum AXIntrospection {
     /// to the whole window (and show its title in the composer header). Structural
     /// `AXGroup`s are skipped unless they are actionable or identified, so a
     /// near-miss lands on the nearest meaningful control rather than a wrapper.
+    /// Window-chrome subroles: the traffic lights (+ the full-screen affordance).
+    /// They are real, actionable `AXButton`s, but they are the WINDOW's chrome,
+    /// not app content — their selectors locate no app code, so the hit-test must
+    /// never offer them as annotation targets. Checked in BOTH resolvers below:
+    /// `deepestNonContainer` is the fallback path, so filtering only
+    /// `nearestIdentified` would just hand the rejected button back via the
+    /// fallback.
+    static let chromeSubroles: Set<String> = [
+        kAXCloseButtonSubrole as String,
+        kAXMinimizeButtonSubrole as String,
+        kAXZoomButtonSubrole as String,
+        kAXFullScreenButtonSubrole as String,
+    ]
+
+    /// True when `subrole` marks window chrome (see ``chromeSubroles``).
+    static func isWindowChrome(subrole: String) -> Bool {
+        chromeSubroles.contains(subrole)
+    }
+
+    private static func isChrome(_ element: AXUIElement) -> Bool {
+        isWindowChrome(subrole: string(element, kAXSubroleAttribute) ?? "")
+    }
+
     private static func nearestIdentified(in rootFirstChain: [AXUIElement]) -> AXUIElement? {
         for element in rootFirstChain.reversed() {
             let role = string(element, kAXRoleAttribute) ?? ""
@@ -328,9 +373,24 @@ enum AXIntrospection {
     /// to that leaf rather than escalating to the whole window (which would then
     /// show the window title in the composer header).
     private static func deepestNonContainer(in rootFirstChain: [AXUIElement]) -> AXUIElement? {
+        // A structural, unidentified group that spans (nearly) the whole window is
+        // the window in disguise — NSHostingView's root AXGroup covers the full
+        // window frame, so falling back to it is the same "background click
+        // highlights the whole app" bug the window/application skip guards
+        // against. Detect it geometrically: the group's frame swallows the
+        // window's frame minus a small inset.
+        let windowFrame = rootFirstChain.first { string($0, kAXRoleAttribute) == "AXWindow" }
+            .map(frameScreen(of:))
         for element in rootFirstChain.reversed() {
             let role = string(element, kAXRoleAttribute) ?? ""
             if role == "AXWindow" || role == "AXApplication" { continue }
+            if role == "AXGroup",
+               (string(element, kAXIdentifierAttribute) ?? "").isEmpty,
+               labelText(element).isEmpty,
+               let windowFrame,
+               frameScreen(of: element).contains(windowFrame.insetBy(dx: 8, dy: 8)) {
+                continue
+            }
             return element
         }
         return nil

Sources/AnnotKitOverlayProbe/main.swift

@@ -896,17 +896,193 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
 
             self.resizeController?.unmount()
             host.orderOut(nil)
+            self.phase4Chrome()
+        }
+    }
+
+    // ---- Phase 4: window CHROME is never an annotation target ---------------
+    // The traffic lights are real, actionable AXButtons, so before the subrole
+    // filter the hit-test offered them as targets (user bug: hovering close/
+    // minimize/zoom highlighted them). While annotating, the native point query
+    // hits the expanded overlay and is DISCARDED, so chrome resolves via the
+    // geometric hitBeneathOverlay path — this phase exercises that real path
+    // end-to-end (filter must cover deepestNonContainer too, or the fallback
+    // hands the rejected button straight back), plus a positive control proving
+    // real content still resolves.
+    var chromeController: OverlayController?
+    var chromeSession: AnnotationSession?
+    var chromeHost: NSWindow?
+    var passChrome = true
+    func check4(_ cond: Bool, _ msg: String) {
+        passChrome = passChrome && cond
+        print("      " + (cond ? "ok   " : "FAIL ") + msg)
+    }
+
+    func phase4Chrome() {
+        print("\n--- Phase 4: window chrome (traffic lights) is never an annotation target ---")
+        // Retire Phase 1's host: titled windows are constrained ON-SCREEN by
+        // AppKit, and a still-ordered-in W1 overlapping this phase's host makes
+        // the geometric hit-test descend the WRONG window.
+        h1?.orderOut(nil)
+        // .miniaturizable + .resizable so all three traffic lights exist (the
+        // other probe hosts are only titled+closable).
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 480, height: 320),
+            styleMask: [.titled, .closable, .miniaturizable, .resizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "AnnotKit Harness W4 (chrome)"
+        window.contentView = NSHostingView(
+            rootView: Button("Probe Target") {}
+                .accessibilityIdentifier("Probe.ChromeContent")
+                .padding(40)
+        )
+        window.makeKeyAndOrderFront(nil)
+        chromeHost = window
+
+        let session = AnnotationSession(
+            source: MacElementSource(),
+            sink: NotesFileSink(path: NSTemporaryDirectory() + "annotkit-chrome.md")
+        )
+        let controller = OverlayController(session: session)
+        controller.mount(on: window)
+        controller.start()   // expand, so hits resolve through the geometric path
+        chromeController = controller
+        chromeSession = session
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.9) { [weak self] in
+            guard let self else { return }
+            let source = MacElementSource()
+            // Chrome buttons via raw AX (subrole is not part of the public
+            // Element); the content control via the public snapshot.
+            let app = AXUIElementCreateApplication(ProcessInfo.processInfo.processIdentifier)
+            let axWindow = AX.windows(app).first {
+                AX.string($0, kAXTitleAttribute) == "AnnotKit Harness W4 (chrome)"
+            }
+            let chromeSubroles: Set<String> = [
+                kAXCloseButtonSubrole as String,
+                kAXMinimizeButtonSubrole as String,
+                kAXZoomButtonSubrole as String,
+                kAXFullScreenButtonSubrole as String,
+            ]
+            let chrome = axWindow.map { self.axFindAll(in: $0, subroles: chromeSubroles, depth: 0) } ?? []
+            check4(chrome.count >= 3, "host exposes >=3 traffic-light AXButtons (found \(chrome.count))")
+            for button in chrome {
+                let frame = AX.frame(button)
+                let subrole = AX.string(button, kAXSubroleAttribute)
+                let hit = source.hitTest(CGPoint(x: frame.midX, y: frame.midY))
+                print("      \(subrole) center=\(fmt(frame)) -> \(hit.map { "#\($0.id)" } ?? "nil")")
+                check4(hit == nil, "\(subrole) is NOT an annotation target")
+            }
+            if let content = self.findElement(id: "Probe.ChromeContent", in: source.snapshot().map(\.root)) {
+                let hit = source.hitTest(CGPoint(x: content.frame.midX, y: content.frame.midY))
+                check4(hit?.id == "Probe.ChromeContent",
+                       "content control still resolves through the expanded overlay (got \(hit.map { "#\($0.id)" } ?? "nil"))")
+            } else {
+                check4(false, "content control Probe.ChromeContent present in the snapshot")
+            }
+            self.chromeController?.unmount()
+            window.orderOut(nil)
+            self.phase5Card()
+        }
+    }
+
+    // ---- Phase 5: a seeded CONTAINER resolves when its BODY is hovered -------
+    // Mirrors the HUD-card fix: cards get .accessibilityElement(children:
+    // .contain) + an identifier, and hovering the card body (inside the card,
+    // outside any child) must resolve to the CARD, while hovering a child still
+    // resolves the child. Validates nearestIdentified's identified-container
+    // branch through the expanded overlay.
+    var cardController: OverlayController?
+    var cardSession: AnnotationSession?
+    var cardHost: NSWindow?
+    var passCard = true
+    func check5(_ cond: Bool, _ msg: String) {
+        passCard = passCard && cond
+        print("      " + (cond ? "ok   " : "FAIL ") + msg)
+    }
+
+    func phase5Card() {
+        print("\n--- Phase 5: seeded container (card) resolves on body hover ---")
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 480, height: 360),
+            styleMask: [.titled, .closable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "AnnotKit Harness W5 (card)"
+        window.contentView = NSHostingView(rootView: ProbeCardView())
+        window.makeKeyAndOrderFront(nil)
+        cardHost = window
+
+        let session = AnnotationSession(
+            source: MacElementSource(),
+            sink: NotesFileSink(path: NSTemporaryDirectory() + "annotkit-card.md")
+        )
+        let controller = OverlayController(session: session)
+        controller.mount(on: window)
+        controller.start()
+        cardController = controller
+        cardSession = session
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.9) { [weak self] in
+            guard let self else { return }
+            let source = MacElementSource()
+            let roots = source.snapshot().map(\.root)
+            guard let card = self.findElement(id: "Probe.Card", in: roots),
+                  let text = self.findElement(id: "Probe.CardText", in: roots) else {
+                check5(false, "snapshot exposes Probe.Card + Probe.CardText")
+                self.cardController?.unmount()
+                window.orderOut(nil)
+                self.finish()
+                return
+            }
+            // A body point: inside the card, left of the (centered) text child.
+            let body = CGPoint(x: card.frame.minX + 16, y: card.frame.midY)
+            check5(!text.frame.contains(body), "sanity: the body point is outside the text child")
+            let bodyHit = source.hitTest(body)
+            print("      card=\(fmt(card.frame)) text=\(fmt(text.frame)) body-hit -> \(bodyHit.map { "#\($0.id)" } ?? "nil")")
+            check5(bodyHit?.id == "Probe.Card",
+                   "hovering the card BODY resolves to the seeded container (got \(bodyHit.map { "#\($0.id)" } ?? "nil"))")
+            let textHit = source.hitTest(CGPoint(x: text.frame.midX, y: text.frame.midY))
+            check5(textHit?.id == "Probe.CardText",
+                   "hovering a child still resolves the CHILD, not the container (got \(textHit.map { "#\($0.id)" } ?? "nil"))")
+            self.cardController?.unmount()
+            window.orderOut(nil)
             self.finish()
         }
     }
 
+    /// Recursive raw-AX search for elements matching one of `subroles`.
+    func axFindAll(in element: AXUIElement, subroles: Set<String>, depth: Int) -> [AXUIElement] {
+        guard depth < 12 else { return [] }
+        var out: [AXUIElement] = []
+        if subroles.contains(AX.string(element, kAXSubroleAttribute)) { out.append(element) }
+        for child in AX.children(element) {
+            out.append(contentsOf: axFindAll(in: child, subroles: subroles, depth: depth + 1))
+        }
+        return out
+    }
+
+    /// Depth-first search of the public snapshot tree by element id.
+    func findElement(id: String, in elements: [Element]) -> Element? {
+        for element in elements {
+            if element.id == id { return element }
+            if let found = findElement(id: id, in: element.children) { return found }
+        }
+        return nil
+    }
+
     func finish() {
         print("\n  issue-2 (per-control hit-test through the expanded overlay): \(passIssue2 ? "PASS" : "FAIL")")
         print("  issue-1 (retention / copy / export / pill persistence):       \(pass1 ? "PASS" : "FAIL")")
         print("  Feature 1 (numbered-pin MODEL: anchors + update + delete/reflow): \(passPins ? "PASS" : "FAIL")")
         print("  Phase 3 (mis-placed-pill regression: pill + axOrigin track FINAL frame): \(passResize ? "PASS" : "FAIL")")
+        print("  Phase 4 (window chrome excluded from the hit-test): \(passChrome ? "PASS" : "FAIL")")
+        print("  Phase 5 (seeded container resolves on body hover): \(passCard ? "PASS" : "FAIL")")
         print("\n=== AnnotKitOverlayProbe complete ===")
-        exit(pass1 && passIssue2 && passPins && passResize ? 0 : 1)
+        exit(pass1 && passIssue2 && passPins && passResize && passChrome && passCard ? 0 : 1)
     }
 
     func collectIDs(_ elements: [Element]) -> [String] {
@@ -919,6 +1095,31 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
     }
 }
 
+/// Phase 5 host content: the HUD-card pattern under test. NOTE a plain
+/// `.accessibilityElement(children: .contain)` container is NOT enough: SwiftUI
+/// reports the contained group's AX frame as the UNION OF ITS CHILDREN (probed:
+/// card frame == text frame), so the card's visual padding is dead to the AX
+/// hit-test. The working pattern is an explicit full-size accessibility SURFACE:
+/// a clear background carrying the card's identifier, whose AX frame is the
+/// card's real visual bounds. Hovering the body hits the surface; hovering a
+/// child still hits the child (the surface sits below content in AX z-order).
+struct ProbeCardView: View {
+    var body: some View {
+        VStack {
+            Text("Card body probe")
+                .accessibilityIdentifier("Probe.CardText")
+        }
+        .padding(60)
+        .background(
+            Color.clear
+                .contentShape(Rectangle())
+                .accessibilityElement(children: .ignore)
+                .accessibilityIdentifier("Probe.Card")
+        )
+        .padding(40)
+    }
+}
+
 let app = NSApplication.shared
 app.setActivationPolicy(.accessory)
 let delegate = OverlayProbeDelegate()