Overlay UX (cli-k0z7h): per-window child overlay, anchored composer, Lucide icon toolbar

Fix the three demo UX issues, root-caused first (composer landed on the AXWindow
because nearestIdentified escalated past label-less SwiftUI AXGroups, compounded
by an NSScreen.main-vs-primary coordinate assumption):

- Window model + layering (issue 2): OverlayController rewritten to attach the
  overlay as a CHILD window of the host app's own window (addChildWindow .above)
  instead of a status-bar float over the whole desktop; NSApp.activate on start;
  a single per-window axOrigin transform (no NSScreen.main assumption) shared by
  click/highlight/composer, correct on any display.
- Composer anchored (issue 1): nearestIdentified no longer climbs to AXWindow;
  composer placed adjacent to the selected element (ComposerPlacement: below/flip
  -above, on-screen clamp, accent caret connector), tracked with the selection.
- Icon toolbar (issue 3): compact dark Lucide icon pill (hand-ported Lucide
  glyphs as SwiftUI Shapes, offline/zero-dep) with tooltips + pending badge;
  every icon maps to a real capability.

Build clean (Swift 6, warnings as errors); 40 tests pass (added ComposerPlacement
+ Lucide + coordinate tests); probe PASS (hitTest resolves to the control).

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

Author: angusbezzina

Sources/AnnotKit/Coordinates.swift

@@ -37,4 +37,16 @@ public enum ScreenSpace {
             height: rect.height
         )
     }
+
+    /// AX top-left origin of a Cocoa (bottom-left, y-up) window frame.
+    /// ADD to a window-local top-left (y-down) point -> AX-screen point.
+    /// SUBTRACT from an AX-screen point/frame -> window-local point.
+    /// `primaryHeight` is `NSScreen.screens.first!.frame.height` (the menu-bar/
+    /// origin display — NOT `NSScreen.main`, which is the active screen and is
+    /// the source of the single-display bug). Because the origin is fixed per
+    /// window, click, highlight, and composer all share one transform: add
+    /// `axOrigin` going into the AX point query, subtract it placing overlays.
+    public static func windowAXOrigin(cocoaFrame: CGRect, primaryHeight: CGFloat) -> CGPoint {
+        CGPoint(x: cocoaFrame.minX, y: primaryHeight - cocoaFrame.maxY)
+    }
 }

Sources/AnnotKit/Overlay/ComposerPlacement.swift

@@ -0,0 +1,77 @@
+import CoreGraphics
+
+/// Where to put the note composer relative to the selected element, expressed in
+/// the overlay's window-local space (top-left origin, y grows down — the same
+/// space the highlight and the `.offset` chrome live in).
+///
+/// Pure geometry, so it is unit-tested without SwiftUI. The catcher feeds the AX
+/// point query by ADDING the host window's `axOrigin`; everything drawn on the
+/// overlay (highlight, composer, caret) SUBTRACTS it. Sharing that one transform
+/// is why the click, the highlight, and the composer agree by construction on any
+/// display, and why the primary-at-origin case (`axOrigin == .zero`) is a no-op.
+///
+/// The card is placed adjacent to the element — below it by default, flipped
+/// above when it would spill off the bottom — and always fully clamped inside the
+/// surface. A caret (small pointer) ties the card back to the element: it points
+/// up toward the element when the card is below, down when the card is flipped
+/// above, and slides horizontally to line up with the element's center.
+struct ComposerPlacement: Equatable {
+    /// Card top-left in window-local space; feed straight into `.offset`.
+    var origin: CGPoint
+    /// Caret points up (card below the element) vs down (card flipped above it).
+    var caretPointsUp: Bool
+    /// Horizontal caret offset from the card's center, aligning it with the
+    /// element's horizontal center and clamped so it never rides a rounded corner.
+    var caretDX: CGFloat
+
+    /// Resolve placement for a selected element.
+    /// - Parameters:
+    ///   - elementFrame: the element's frame in AX-screen coordinates.
+    ///   - axOrigin: AX top-left origin of the host window (subtracted to reach
+    ///     window-local space; see ``ScreenSpace/windowAXOrigin(cocoaFrame:primaryHeight:)``).
+    ///   - surfaceSize: window-local surface size, used to clamp the card fully
+    ///     on-screen.
+    ///   - composerSize: estimated card size, for the clamp and the flip decision.
+    ///   - gap: spacing between the element and the card (and the surface edge).
+    ///   - caretCornerInset: how far the caret must stay from the card's side
+    ///     edges so it never overlaps a rounded corner.
+    static func resolve(
+        elementFrame: CGRect,
+        axOrigin: CGPoint,
+        surfaceSize: CGSize,
+        composerSize: CGSize,
+        gap: CGFloat = 8,
+        caretCornerInset: CGFloat = 18
+    ) -> ComposerPlacement {
+        // Element in window-local (y-down) space.
+        let ex = elementFrame.minX - axOrigin.x
+        let ey = elementFrame.minY - axOrigin.y
+        let elementCenterX = ex + elementFrame.width / 2
+
+        // Horizontal: left-align with the element, clamped so the whole card fits.
+        let maxX = max(gap, surfaceSize.width - composerSize.width - gap)
+        let x = min(max(gap, ex), maxX)
+
+        // Vertical: below the element by default; flip above when it would spill
+        // off the bottom (the diagnosis's window-selected (640,790) off-screen
+        // spill). Then clamp the top on-screen.
+        var caretPointsUp = true
+        var y = ey + elementFrame.height + gap
+        if y + composerSize.height > surfaceSize.height - gap {
+            y = ey - composerSize.height - gap
+            caretPointsUp = false
+        }
+        y = max(gap, y)
+
+        // Caret: align with the element center, clamped within the card.
+        let cardCenterX = x + composerSize.width / 2
+        let caretLimit = max(0, composerSize.width / 2 - caretCornerInset)
+        let caretDX = min(max(-caretLimit, elementCenterX - cardCenterX), caretLimit)
+
+        return ComposerPlacement(
+            origin: CGPoint(x: x, y: y),
+            caretPointsUp: caretPointsUp,
+            caretDX: caretDX
+        )
+    }
+}