fix(overlay): the toolbar panel is sized to the pill, not to a fixed corner (VRT-jiuo)

The panel carrying the pill was a fixed 240x104 rect pinned to the host's
bottom-right, permanently mounted in BOTH modes, and it consumes presses
across its whole frame — so that corner of the host app could not be
clicked and no frame drag could be started in it. The idle pill used 8%
of it.

The mechanism was settled by measurement last week and is the reason the
only lever is SIZE: macOS does not route mouse events through a window's
transparent parts. A panel whose content view is a bare NSView drawing
nothing at all, with isOpaque = false and a clear background, swallows
the click just the same, and ignoresMouseEvents = true would take the
pill's own clicks with it.

SIZING AND PLACEMENT ARE SPLIT. SwiftUI knows how wide the pill is; the
size is measured from it. What AppKit gets wrong is the ANCHOR — a window
resize preserves the TOP-LEFT and this panel is anchored bottom-RIGHT, so
letting AppKit apply the size slid the control left by the chrome margin.
sizingOptions = [] takes that away and toolbarFrame derives the frame
BACKWARDS from where the pill has to land, so the panel grows leftwards
and shrinks back with the control fixed at host.maxX - 20 — verified from
AppKit's own view frames (buttons at panel-local 20..207), not from the
formula under test.

Two traps, both hit and both worth the comments they now carry: measuring
`fittingSize` on the INSTALLED hosting view returns the frame it was just
stretched to, so it never shrinks (a fresh view is measured instead); and
the pill animates its width over 0.15s, so the panel grows immediately
and shrinks only once that has settled.

What remains dead is the chrome band the drop shadow and count badge draw
into. Probe 11a now pins all three claims with real clicks: a control
click that must land, a click where the old fixed panel used to sit that
must now reach the catcher, and a click in the chrome band that must
still be swallowed. Phases 3a and 9a assert the PILL's corner rather than
the panel frame, since the panel's own edges now move by design; the dead
legacy `panelFrame(for:)` shape and its only (unused) caller are gone.

The real-input legs also now report SKIPPED rather than FAILED when the
app is not frontmost — a posted click that never arrives says nothing
about the overlay either way.

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

Author: angusbezzina

DECISIONS.md

@@ -346,26 +346,49 @@ When the framed content scrolls fully out of view the frame goes off-surface wit
 it, which is the honest outcome; `ComposerPlacement` already clamps the card, so it
 stays on screen and sendable.
 
-### The toolbar panel claims its whole frame (measured, VRT-pm3k.7)
-
-The permanently-mounted toolbar panel is 240x104 with the pill in its bottom-right
-corner, and it consumes presses across the **whole** rect — so the host's
-bottom-right 240x104 is inert to clicks and to the start of a frame drag, in both
-modes.
-
-This was listed as candidate (d) on the assumption that per-pixel alpha
-pass-through would save it. It does not: measured against a panel whose content
-view was a bare `NSView` drawing nothing at all, with `isOpaque = false` and a
-clear background, the click was still swallowed. macOS does not route mouse events
-through the transparent parts of a window; `ignoresMouseEvents = true` is the only
-configuration that lets them through, and it would take the pill's own clicks with
-it. `AnnotKitOverlayProbe` phase 11a pins the behaviour with a real posted click,
-against a control click on the catcher so a null result means something.
-
-Not fixed here, deliberately: the remedy is to size the panel to the pill, which
-changes the design `be624b4` landed (a fixed-size panel whose frame moves for
-exactly one reason), and this epic's job was to settle the question. Tracked
-separately.
+### The toolbar panel is sized to the pill (VRT-jiuo)
+
+The panel carrying the pill used to be a fixed 240x104 rect pinned to the host's
+bottom-right, permanently mounted in BOTH modes. It consumes presses across its
+whole frame, so that corner of the host app could not be clicked, and no frame drag
+could be started in it. The idle pill used 8% of it; the other 92% was dead space no
+user could see and every user could hit.
+
+**The mechanism, measured rather than assumed.** macOS does not route mouse events
+through a window's transparent parts. This was listed as a candidate on the
+assumption that per-pixel alpha pass-through would save it; it does not. A panel
+whose content view is a bare `NSView` drawing NOTHING at all, with `isOpaque =
+false` and a clear background, swallows the click just the same.
+`ignoresMouseEvents = true` is the only setting that lets events through, and it
+would take the pill's own clicks with it. So the only lever is the panel's SIZE.
+
+**Sizing and placement are split, and the split is the design.** SwiftUI knows
+exactly how wide the pill is — including while it animates between the lone pencil
+and the six-control row — so the size is measured from it. What AppKit gets wrong is
+the ANCHOR: a window resize preserves the TOP-LEFT, and this panel is anchored
+bottom-RIGHT, so letting AppKit apply the size slid the control left by the chrome
+margin. `sizingOptions = []` takes that away, and
+``OverlayPlacement/toolbarFrame(hostFrame:visibleFrame:panelSize:)`` derives the
+frame BACKWARDS from where the pill has to land. The panel grows leftwards and
+shrinks back with the control fixed at `host.maxX - 20`, exactly where it always
+was — verified from AppKit's own view frames, not from the formula under test.
+
+**Measured on a FRESH hosting view, not the installed one.** The installed view has
+already been stretched to the panel's current frame, so asking it for a fitting size
+returns the answer being replaced — a measurement of the status quo, which never
+shrinks. That circularity is why the first attempt silently did nothing.
+
+**Grow now, shrink later.** A panel that grows LATE clips the control it carries; a
+panel that shrinks EARLY clips it just the same, because the pill animates its width
+over 0.15s on a mode change. So growth is immediate and speculative and shrinking
+waits for the animation. In between the panel is briefly larger than it needs to be.
+
+What remains dead is ``PillStyle/panelChrome`` — the band the drop shadow (radius
+12, offset 8 down) and the count badge (hung 5pt past the pill's top-left corner)
+draw into. Clipping either is visible, so this is the irreducible cost, and it hugs
+the control and reads as part of it. Pinned by probe 11a with three real clicks: a
+control click that must land, a click where the old fixed panel used to sit that must
+now reach the catcher, and a click in the chrome band that must still be swallowed.
 
 ### Recall survives a scroll, best-effort and no further (macOS)
 

PARITY.md

@@ -18,6 +18,7 @@ row; each asymmetry is closed by code or has a tracked mitigation.
 | Frame-mode anchoring + hover gating | shared `AnnotationSession` (`selectionAnchorFrame`, the `tool == .point` hover gate, `setTool` clearing `hovered`) rendered by the shared `OverlayView` | same | none in the code — all of it is session-level and platform-free, and one SwiftUI view renders it. ASYMMETRIC VERIFICATION, recorded as a gap rather than closed: `AnnotKitOverlayProbe` Phase 8 drives navigation, the note's `component`, the hover gate and the frame anchor against a REAL accessibility tree, and it is macOS-only (`#if os(macOS)`, AppKit + `AXUIElement`), so the iOS adapter's live behaviour is covered only by unit tests over the pure rules. Mitigated, not fixed, by the fact that everything Phase 8 asserts about anchoring and hover lives in the shared session; what remains unverified on iOS is the ADAPTER's candidate collection. Note the hover gate is also moot on touch-only iOS — hover exists there only with a trackpad or pencil — so the reported symptom cannot arise without a pointer |
 | Marquee drag threshold | cursor slop (a mouse does not move on a deliberate click) | larger touch slop | ASYMMETRIC BY DESIGN, owned by the drag UI, not the adapters: a finger rolls several points on a deliberate tap, so the macOS threshold on iOS would turn taps into marquees. Below the threshold both platforms route the gesture to the point path (`select(atAXPoint:)`), per the caller contract on `select(inAXRect:)` |
 | Escape (back out one level) | `NSEvent.addLocalMonitorForEvents(matching: .keyDown)` owned by `OverlayController`, resolving the shared pure `EscapeRule` (drag → card → mode, pass-through when idle) | none — no Escape key exists on iOS | ASYMMETRIC BY THE HARDWARE, not by the code: a touch device has no Escape key, so there is nothing to bind. The DECISION is platform-free and unit-tested (`EscapeRule`), so an iOS back-out affordance (a swipe, a hardware-keyboard binding on iPad) can adopt it without re-deriving the precedence; only the macOS delivery mechanism is `#if os(macOS)`. The mechanism is a LOCAL KEY MONITOR rather than a SwiftUI modifier (`.onExitCommand`) because a panel-scoped modifier only fires while the overlay panel is KEY, and the panel is made key solely by a card focusing its text field — so in annotate mode with nothing open, the state a user most wants to leave, the HOST window is key and no view in the panel ever sees the keystroke. A local monitor works precisely because AnnotKit is in-process with its host: the Escape headed for the host window passes through it first, and it can swallow what it acted on (`EscapeAction.consumesEvent`), which a global monitor cannot. It is installed in `start()` and removed in BOTH `stop()` and `unmount()` — a monitor outliving the overlay would keep eating the host app's own Escape for the life of the process |
+| Toolbar panel footprint | sized to the pill (`OverlayPlacement.toolbarFrame(hostFrame:visibleFrame:panelSize:)`, measured from a fresh hosting view) | n/a — the iOS overlay is a single pass-through `UIWindow`, and the pill is not carried in a window of its own | ASYMMETRIC BY THE HOSTING MODEL. On macOS the pill lives in its own `NSPanel`, and a panel covers what it covers: macOS does not route mouse events through a window's transparent parts, so the panel's SIZE is the host app's clickable area. iOS has no equivalent problem — `PassThroughWindow` forwards touches outside the overlay's interactive subviews, which is the pass-through macOS does not offer |
 | The first click on the overlay acts | `FirstMouseHostingView` (`acceptsFirstMouse -> true`) on both panels' content views | n/a | ASYMMETRIC BY THE PLATFORM, not by the code: "a mouse-down in a non-key window is discarded unless the view accepts first mouse" is an AppKit window-activation rule with no UIKit equivalent — iOS has no key window a press must first buy, and a touch on the pass-through `UIWindow` is delivered on the first tap. Nothing to mirror; the fix lives entirely in the macOS host |
 | Live selection follows the content on scroll | `translateSelection(by:within:)`, driven by the same measurement `KeyablePanel.scrollWheel` already makes | none | SAME asymmetry and the same reason as the row for captured notes below: the correction is affordable on macOS only because the overlay panel intercepts every wheel event and drives the clip itself. The receiving side is shared and unit-tested (`translateSelection` is pure geometry over session state), so an iOS host that observes its own scrollers can adopt it unchanged |
 | Recallable selection marks (a captured note's geometry comes back on hover) | shared: `AnnotationNote.anchorRect`/`drawnRect` snapshotted in `AnnotationSession.addNote`, `PinAttentionRule` + `RecalledMark` as pure rules, rendered by the shared `AnnotationMarks` | same | none — every part of it is platform-free. The two rects are WINDOW-LOCAL, which is the one place a platform could have crept in: macOS subtracts the overlay panel's `axOrigin`, iOS passes `.zero` because its view-tree frames are already view-local, and `addNote` takes that origin as a parameter rather than knowing which platform it is on. Both fields are UI-only and out of `CodingKeys`, so the exported record is identical on both |

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -635,19 +635,21 @@ struct ToolbarOverlayView: View {
     let onExport: () -> Void
 
     var body: some View {
-        VStack {
-            Spacer()
-            HStack {
-                Spacer()
-                ToolbarView(
-                    session: session,
-                    onToggle: onToggle,
-                    onCopy: onCopy,
-                    onExport: onExport
-                )
-                .padding(20)
-            }
-        }
+        // JUST the pill, inset by the space its shadow and count badge need. There
+        // are no Spacers pushing it into a corner any more, because the panel is no
+        // longer a fixed 240x104 rect the pill sits in the corner of — it is sized
+        // to THIS view (`fittingSize`) and placed so the pill lands exactly where it
+        // always has. The panel covering only the control is the point: every pixel
+        // it covers is a pixel the host app cannot be clicked through, in both
+        // modes, permanently.
+        ToolbarView(
+            session: session,
+            onToggle: onToggle,
+            onCopy: onCopy,
+            onExport: onExport
+        )
+        .padding(PillStyle.panelChrome)
+        .fixedSize()
         .ignoresSafeArea()
         .accessibilityHidden(true)
     }

Sources/AnnotKit/Overlay/PillStyle.swift

@@ -48,6 +48,30 @@ enum PillStyle {
     /// white-on-dark weight as ``border`` but a touch stronger, so it reads as a
     /// deliberate group boundary at 1pt instead of disappearing into the capsule.
     static let divider = Color.white.opacity(0.1)
+
+    /// Blank space the toolbar panel keeps AROUND the pill, for the chrome that
+    /// draws OUTSIDE the control's own layout bounds and would otherwise be clipped
+    /// by a snug window: the drop shadow (radius 12, offset 8 DOWN, hence the taller
+    /// bottom) and the count badge, which is hung 5pt past the pill's top-left
+    /// corner.
+    ///
+    /// This is the whole remaining cost of the panel being hit-testable. macOS does
+    /// not route mouse events through a window's transparent parts — measured, and
+    /// true even of a panel drawing nothing at all — so every pixel the panel covers
+    /// is a pixel the host app cannot be clicked through. Sizing the panel to the
+    /// pill reduces that to this band, which hugs the control and reads as part of
+    /// it. It was a permanently-mounted 240x104 rect over the host's bottom-right
+    /// corner, dead in BOTH modes, of which the pill used 8% when idle.
+    ///
+    /// Shared with ``OverlayPlacement/toolbarFrame(hostFrame:visibleFrame:panelSize:)``,
+    /// which subtracts it to keep the pill at the same inset from the host's corner
+    /// it has always had: the panel changing size must not move the control.
+    static let panelChrome = EdgeInsets(top: 14, leading: 14, bottom: 20, trailing: 14)
+
+    /// The pill's inset from the visible region's bottom-right corner. Unchanged
+    /// from when it was padding INSIDE a fixed 240x104 panel, so the control sits
+    /// exactly where it always has.
+    static let cornerInset: CGFloat = 20
 }
 
 // MARK: - Icon-button palette