fix(overlay): the pill is pinned to the panel's corner, not centred in it

Closing the menu shortened the pill leftwards and then jumped it back to the
right. The animation was never the problem: the pill was in the wrong place for
a third of a second on every open and close.

OverlayPlacement.toolbarFrame computes the panel's frame BACKWARDS from where
the control has to land, subtracting the trailing/bottom chrome. That is only
true of the drawn pill if the content is pinned to that corner, and a fixedSize
root in an oversized NSHostingView is CENTRED instead. Since VRT-jiuo the panel
grows the instant the mode flips and shrinks 0.3s later (early shrinking clips
the pill mid-animation), so the two disagree across the whole transition.
Measured: idle content (72pt) in the still-open panel (258pt) sits 93pt from
each edge instead of 14pt from the trailing one. The pill collapsed toward the
middle of the still-wide panel, then snapped 79pt right when the panel finally
narrowed under it.

Pinning bottom-trailing leaves the width animation as the only thing that
moves: the pill opens leftwards and closes back in from the left, and the late
shrink is invisible because it only takes away space the pill never occupied.
It also corrects the same offset at mount, where the panel is still at its
generous unmeasured seed.

The flexible frame does not disturb the measurement the same view is used for:
an unspecified proposal, which is what fittingSize asks with, resolves it to the
content's ideal size. Pinned by a test, along with the anchoring itself, which
is asserted by rasterising the real view and finding the pill's opaque body.
PanelFrameEnforcementTests passed throughout because it derives the pill's
corner FROM the panel frame, which is the assumption that was false.

233 unit tests, warning-free build, iOS simulator cross-compile clean, probe
11/11 phases PASS against a live AX tree.

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

Author: angusbezzina

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -646,13 +646,14 @@ struct ToolbarOverlayView: View {
     let onExport: () -> Void
 
     var body: some View {
-        // 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.
+        // JUST the pill, inset by the space its shadow and count badge need. The
+        // panel is no longer a fixed 240x104 rect with the pill parked in one
+        // corner of it — 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. The corner
+        // alignment below is what keeps that true while the panel is briefly LARGER
+        // than the pill, which is every open and close.
         ToolbarView(
             session: session,
             onToggle: onToggle,
@@ -661,6 +662,29 @@ struct ToolbarOverlayView: View {
         )
         .padding(PillStyle.panelChrome)
         .fixedSize()
+        // PINNED to the panel's bottom-trailing corner, which is where
+        // ``OverlayPlacement/toolbarFrame(hostFrame:visibleFrame:panelSize:)``
+        // computes backwards FROM — it subtracts the trailing/bottom chrome to put
+        // the pill at its inset from the host's corner. Without this the pill is
+        // CENTERED in whatever bounds the panel has, and the two agree only while
+        // the panel is exactly the measured size.
+        //
+        // They disagree for a third of a second on EVERY open and close, because
+        // the panel grows immediately and shrinks late (see
+        // ``OverlayController/scheduleToolbarShrink()``), and that is the whole of
+        // the "it shortens to the left, then jumps right" close animation: a
+        // centered pill collapsed toward the middle of the still-wide panel, then
+        // snapped back to the corner when the panel finally narrowed under it. With
+        // the corner pinned, the width animation is the ONLY thing that moves — the
+        // pill opens leftwards and closes back in from the left — and the late
+        // shrink is invisible because it only takes away space the pill was never
+        // occupying. It also fixes the same offset at mount, where the panel is
+        // still at its generous unmeasured seed.
+        //
+        // `maxWidth`/`maxHeight` do not disturb the measurement this same view is
+        // used for: an unspecified proposal (what `fittingSize` asks with) resolves
+        // a flexible frame to its content's ideal size. Verified.
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottomTrailing)
         .ignoresSafeArea()
         .accessibilityHidden(true)
     }

Tests/AnnotKitTests/ToolbarPillAnchorTests.swift

@@ -0,0 +1,127 @@
+#if os(macOS)
+import AppKit
+import SwiftUI
+import XCTest
+@testable import AnnotKit
+
+/// "Closing the menu shortens it to the left, then it jumps to the right."
+///
+/// The toolbar panel does not change size in step with the pill it carries. It
+/// GROWS the instant the mode flips and SHRINKS a third of a second later, once the
+/// pill's 0.15s width animation has settled (``OverlayController``'s asymmetry: a
+/// panel that shrinks early clips the control mid-animation). So on every open and
+/// close there is a window in which the panel is wider than its content — and
+/// ``OverlayPlacement/toolbarFrame(hostFrame:visibleFrame:panelSize:)`` places the
+/// panel by computing backwards from the pill's corner, which is only where the
+/// pill actually IS if the content is pinned to that corner.
+///
+/// It was not: a `fixedSize` root in an oversized `NSHostingView` is CENTERED.
+/// Measured before the fix, idle content (72pt) in the still-open panel (258pt):
+/// the pill sat 93pt from each edge instead of 14pt from the trailing one — so it
+/// collapsed toward the middle as it narrowed, then snapped 79pt right when the
+/// panel finally shrank under it.
+///
+/// These tests rasterise the real view and look for the pill's opaque body, because
+/// the bug is entirely about where the control is DRAWN — every value the placement
+/// math produced was already correct. That is also why
+/// `PanelFrameEnforcementTests.testTheToolbarDoesNotMoveWhenTheMenuOpensOrCloses`
+/// passed throughout: it derives the pill's corner FROM the panel frame, which is
+/// the very assumption that only held once the panel had settled.
+@MainActor
+final class ToolbarPillAnchorTests: XCTestCase {
+    /// The panel size the controller holds during a close: measured for ANNOTATE
+    /// mode, while the pill has already animated back down to the lone pencil.
+    private let oversized = CGSize(width: 258, height: 104)
+
+    private func makeSession() -> AnnotationSession {
+        AnnotationSession(source: MacElementSource(), sink: NotesFileSink(path: "/dev/null"))
+    }
+
+    /// The mid-close state: idle content, panel still at its annotate-mode width.
+    func testThePillKeepsItsCornerWhileThePanelIsWiderThanTheContent() throws {
+        let pill = try drawnPillFrame(panelSize: oversized, session: makeSession())
+        XCTAssertEqual(oversized.width - pill.maxX, PillStyle.panelChrome.trailing, accuracy: 1,
+                       "the pill's trailing edge must stay one chrome margin from the panel's, "
+                       + "or the panel's late shrink drags the control sideways")
+        XCTAssertEqual(pill.minY, PillStyle.panelChrome.bottom, accuracy: 1,
+                       "same for the bottom edge — the seed panel is taller than the pill too")
+    }
+
+    /// The settled state, and the one the placement math is written against. The
+    /// two must agree pixel for pixel: that they did NOT is the jump.
+    func testTheSettledPanelDrawsThePillInTheSamePlaceAsTheOversizedOne() throws {
+        let session = makeSession()
+        let snugSize = measuredSize(session: session)
+        let snug = try drawnPillFrame(panelSize: snugSize, session: session)
+        let wide = try drawnPillFrame(panelSize: oversized, session: session)
+
+        XCTAssertEqual(snugSize.width - snug.maxX, oversized.width - wide.maxX, accuracy: 1)
+        XCTAssertEqual(snug.minY, wide.minY, accuracy: 1)
+        XCTAssertEqual(snug.size.width, wide.size.width, accuracy: 1)
+    }
+
+    /// The corner pin is a `maxWidth`/`maxHeight` frame, and the SAME view is what
+    /// ``OverlayController/measuredToolbarSize()`` sizes the panel from. A flexible
+    /// frame that reported its max instead of its content's ideal would inflate the
+    /// panel to fill the screen — every pixel of which is a pixel of the host app
+    /// that can no longer be clicked.
+    func testPinningTheCornerDoesNotInflateTheMeasuredSize() {
+        let size = measuredSize(session: makeSession())
+        XCTAssertLessThan(size.width, 200, "idle is one 44pt pill plus 14pt of chrome a side")
+        XCTAssertLessThan(size.height, 120)
+        XCTAssertGreaterThan(size.width, 40)
+        XCTAssertGreaterThan(size.height, 40)
+    }
+
+    // MARK: - Rasterising
+
+    private func toolbarView(session: AnnotationSession) -> ToolbarOverlayView {
+        ToolbarOverlayView(session: session, onToggle: {}, onCopy: {}, onExport: {})
+    }
+
+    /// What the controller sizes the panel from: a fresh, uninstalled hosting view's
+    /// `fittingSize`, with the default sizing options that make it report one.
+    private func measuredSize(session: AnnotationSession) -> CGSize {
+        NSHostingView(rootView: toolbarView(session: session)).fittingSize
+    }
+
+    /// The pill's drawn bounds inside a panel of `panelSize`, in AppKit's y-UP
+    /// panel-local coordinates.
+    ///
+    /// Found by alpha, not by colour: the pill's capsule is opaque, and the only
+    /// other thing the view draws is its shadow — black at 0.4, radius 12 — so a
+    /// high alpha threshold picks out the body and ignores the halo around it.
+    private func drawnPillFrame(panelSize: CGSize, session: AnnotationSession) throws -> CGRect {
+        let view = NSHostingView(rootView: toolbarView(session: session))
+        // Match the panel's own hosting view: the controller owns the frame, so the
+        // view must NOT resize itself to its content — being stretched past its
+        // content is the whole state under test.
+        view.sizingOptions = []
+        view.frame = CGRect(origin: .zero, size: panelSize)
+        view.layoutSubtreeIfNeeded()
+
+        let rep = try XCTUnwrap(view.bitmapImageRepForCachingDisplay(in: view.bounds),
+                                "no bitmap backing for the hosting view")
+        view.cacheDisplay(in: view.bounds, to: rep)
+
+        let scale = CGFloat(rep.pixelsWide) / panelSize.width
+        var minX = Int.max, maxX = Int.min, minY = Int.max, maxY = Int.min
+        for y in 0..<rep.pixelsHigh {
+            for x in 0..<rep.pixelsWide {
+                guard let color = rep.colorAt(x: x, y: y), color.alphaComponent > 0.9 else { continue }
+                minX = min(minX, x); maxX = max(maxX, x)
+                minY = min(minY, y); maxY = max(maxY, y)
+            }
+        }
+        try XCTSkipIf(minX == Int.max, "the offscreen rasterisation drew nothing on this machine")
+
+        // The bitmap is y-DOWN; the panel geometry this is compared against is y-UP.
+        let top = CGFloat(minY) / scale
+        let bottom = CGFloat(maxY + 1) / scale
+        return CGRect(x: CGFloat(minX) / scale,
+                      y: panelSize.height - bottom,
+                      width: CGFloat(maxX + 1 - minX) / scale,
+                      height: bottom - top)
+    }
+}
+#endif