fix(overlay): a click on a pin edits its comment, in both tools (VRT-u209)

A comment written with the FRAME tool could be read and never edited. Pins were
made hit-test-inert in frame mode so a press starting on one could still draw a
frame (VRT-dp47) — but going inert was only ever meant to stop a pin swallowing a
DRAG, and it also removed the only route to the editor. Reported as "I need to
click on the comment again to edit the text… right now when I hover on one of the
numbers, nothing happens".

Diagnosed by measurement rather than by reading: the probe's phase 11c presses a
real pin in each tool and printed editingNoteID=nil in frame mode, while point
mode opened the editor. That leg had PINNED the empty result as the desired
outcome, so the contract was half-written down and the gap looked deliberate.

The press is now routed by GEOMETRY at the catcher's release —
PinAttentionRule.pressedNote via SelectionGesture — so the pin view stays inert
and the pin stays live. TRAVEL, NOT TOOL, IS THE GATE: a click on a pin edits it
in either tool, a drag from a pin still draws its frame. One sentence true of
both, so the VRT-dp47 report cannot come back; mutation-verified (dropping the
gate fails exactly the two drag-from-pin tests) and measured by a new probe leg
that drags off a pin and asserts the frame still resolves.

The press radius is the pin's OWN (10pt), deliberately not the 20pt attention
radius: attending is free and may reach outside the pin, a click is scarce
because the same press could have selected the element underneath. Wired to
attentionRadius every pin would be a 40pt hole in the canvas that looks 20pt.

Highlighting the captured selection while its card is open needed no new
plumbing — attendedNoteID is editingNoteID ?? hoveredNoteID, so the open card
already wins the tie — but it was only covered for the hover path. It is now
asserted end-to-end in the tool it was broken in, and in the probe for both.

230 unit tests, 0 failures; probe 11/11 phases PASS against a live AX tree; iOS
module type-checks clean against the iPhoneOS SDK in Swift 6.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: angusbezzina

DECISIONS.md

@@ -263,14 +263,32 @@ window) leaves the catcher's last answer pointing at the pin it saw before.
 Observed exactly that way during the visual check — the card read note 1 while the
 canvas drew note 3.
 
-**Why pins are inert in frame mode.** `AnnotationPin` is a `Button` mounted above
-the catcher, so a press starting on one never reaches the drag gesture — and every
-capture plants one exactly where the next frame is most likely to be drawn. That,
-plus hover-to-edit dropping a ~284x172 card under the pointer, is the reported "if
-I select an element I cannot also use the frame tool". In frame mode the user is
-drawing, not editing, so one condition removes both with no gesture negotiation.
-Measured both ways in the probe (11c): the same synthesized press opens the editor
-in point mode and does nothing in frame mode.
+**Why the pin VIEW is inert in frame mode.** `AnnotationPin` is a `Button` mounted
+above the catcher, so a press starting on one never reaches the drag gesture — and
+every capture plants one exactly where the next frame is most likely to be drawn.
+That, plus hover-to-edit dropping a ~284x172 card under the pointer, is the reported
+"if I select an element I cannot also use the frame tool". In frame mode the user is
+drawing, so one condition removes both with no gesture negotiation.
+
+**Why a pin is still CLICKABLE there (VRT-u209).** Going hit-test-inert was meant to
+stop a pin swallowing a DRAG; it also removed the only route to the editor, so a
+comment written with the frame tool could be read and never edited — reported as "I
+need to click the comment again to edit it… right now when I hover on one of the
+numbers, nothing happens", and settled by probe 11c printing `editingNoteID=nil` for
+a real press on a real pin in frame mode. The press is now routed by GEOMETRY at the
+catcher's release (`PinAttentionRule.pressedNote` via `SelectionGesture`), so the
+view stays inert and the pin stays live. **Travel, not tool, is the gate**: a click
+on a pin edits it in either tool, a drag from a pin still draws its frame — one
+sentence true of both, and the `VRT-dp47` report cannot come back. Probe 11c now
+measures all three legs (click in each tool, drag from a pin).
+
+**Why the press radius is the pin's own, not `attentionRadius`.** The two circles are
+paid for differently. Attending is free — it draws a picture and takes nothing away —
+so it may reach outside the pin (and must, since in point mode the catcher only ever
+sees points outside a live button). A click is scarce: the same press could have
+selected the element underneath, so its target is exactly the circle the user can
+SEE. Wired to `attentionRadius`, every pin would be a 40pt hole in the canvas that
+looks 20pt wide.
 
 **The composer covering its own element is ACCEPTED.** A card the user may be
 typing into must consume its own clicks; dismissing it or starting the drag from

PARITY.md

@@ -22,7 +22,8 @@ row; each asymmetry is closed by code or has a tracked mitigation.
 | 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 |
-| Pins inert in frame mode / hover-to-edit gated to point mode | shared `AnnotationPins` (`allowsHitTesting(session.tool == .point)`, and the same condition on the hover that opens the editor) | same | none in the code. ASYMMETRIC VERIFICATION, recorded rather than closed: `AnnotKitOverlayProbe` phase 11c posts a real press at a pin's own coordinates in each mode and is macOS-only, so on iOS the fix is covered only by the unit tests over the session and the rules. Note the hover half is largely moot on touch-only iOS — hover exists there only with a trackpad or pencil |
+| Pin VIEW inert in frame mode / hover-to-edit gated to point mode | shared `AnnotationPins` (`allowsHitTesting(session.tool == .point)`, and the same condition on the hover that opens the editor) | same | none in the code. ASYMMETRIC VERIFICATION, recorded rather than closed: `AnnotKitOverlayProbe` phase 11c posts a real press at a pin's own coordinates in each mode and is macOS-only, so on iOS the fix is covered only by the unit tests over the session and the rules. Note the hover half is largely moot on touch-only iOS — hover exists there only with a trackpad or pencil |
+| Pin CLICK-TO-EDIT in both tools (VRT-u209) | shared: `SelectionGesture.resolve(…pins:)` consults `PinAttentionRule.pressedNote` on a press that did not travel, and the shared catcher in `OverlayView` opens the editor for `.editNote` | same | none — the whole decision is a pure rule over the notes' stored window-local anchors, so both hosts route a tap identically, and iOS gets it from the one catcher it already shares. The TRAVEL gate is the only platform-sensitive part and it is already parameterized (`SelectionGesture.minimumTravel` is 10 on iOS vs 6 on macOS, because a finger rolls several points on a deliberate tap) — so a touch that would have been a sloppy tap still opens the pin's editor rather than being read as a drag. Verification is the same asymmetry as the row above: probe 11c is macOS-only; iOS relies on the shared unit tests |
 | Recall survives a scroll | `KeyablePanel.scrollWheel` measures the translation it applied to the host's `NSScrollView` and feeds `AnnotationSession.translateNotes(by:within:)` | none | ASYMMETRIC BY THE MECHANISM: the correction is affordable on macOS only because the overlay panel already intercepts every wheel event and drives the clip itself, so the exact translation is known at the moment it is applied. iOS does not intercept `UIScrollView`, so nothing there knows a scroll happened; a note's rects stay where they were captured, which is the pre-existing behaviour `AnnotationPins` has always accepted for the pin. The RECEIVING side is shared and unit-tested (`translateNotes` is pure bookkeeping over `pending`), so an iOS host that later observes its own scrollers can adopt it without re-deriving anything |
 | Overlay excluded from element lookup | AX window identifier (`AXIntrospection.overlayWindowIdentifier`) filtered out of every `kAXWindows` read | `PassThroughWindow` TYPE identity filtered out of `IOSElementSource.windows()` | ASYMMETRIC BY NECESSITY — the hosts are different window kinds. macOS's overlay is a separate `NSPanel` matched by the identifier the controller stamps on it; iOS's is a `UIWindow` in the HOST's scene sharing its pid, so no pid/scene filter separates it and a type check (internal to the module) cannot drift the way an identifier convention can. Both filter in the shared window lookup, so snapshot / hit-test / region-anchor / marquee agree; leaving it in would let a marquee bind the user's note to AnnotKit's own UI |
 | Coordinate space | Cocoa bottom-left to AX top-left flip | UIKit top-left native | iOS needs no flip; shared `ScreenSpace` used only on macOS |

Sources/AnnotKit/Overlay/AnnotationPins.swift

@@ -19,20 +19,36 @@ import SwiftUI
 /// The whole overlay stays `accessibilityHidden`, so pins never disturb the AX
 /// point query's see-through.
 ///
-/// IN FRAME MODE THEY ARE INERT. Sitting above the catcher means a press that
-/// starts on a pin never reaches the catcher's drag gesture — and every capture
-/// plants one exactly where the user is most likely to draw the next frame, on the
-/// thing they just annotated. That is the "I selected an element and now I can't
-/// use the frame tool" report. In frame mode the user is drawing, not editing, and
-/// the tool is an explicit choice ("the tool you picked is the outcome you get",
-/// per ``SelectionGesture``), so one condition removes the collision with no
-/// gesture negotiation — the thing `VRT-dp47` learned to stay away from.
+/// IN FRAME MODE THE VIEW IS INERT — the view, not the pin. Sitting above the
+/// catcher means a press that starts on a pin never reaches the catcher's drag
+/// gesture, and every capture plants one exactly where the user is most likely to
+/// draw the next frame, on the thing they just annotated. That is the "I selected
+/// an element and now I can't use the frame tool" report. One condition removes the
+/// collision with no gesture negotiation — the thing `VRT-dp47` learned to stay
+/// away from.
 ///
-/// Recall does NOT ride on the pin's own hover, and that is what makes going inert
-/// affordable: a view with `allowsHitTesting(false)` receives no hover at all.
-/// "Which note's pin is the pointer on?" is answered geometrically by
-/// ``PinAttentionRule``, from the catcher's `onContinuousHover`, which covers the
-/// whole surface and fires in BOTH modes.
+/// WHAT THE PIN STILL DOES THERE is the correction `VRT-u209` made, and it is worth
+/// separating from the sentence above because they were conflated for two releases.
+/// Going hit-test-inert was only ever meant to stop a pin SWALLOWING A DRAG; it also
+/// silently removed the only way to re-open a note, so a comment written with the
+/// frame tool could be read and never edited. Measured, not assumed — the probe's
+/// phase 11c presses a real pin in both tools and reported `editingNoteID=nil` in
+/// frame mode, which is exactly the "I hover the numbers and nothing happens"
+/// report. Both behaviours are now had at once, because neither the click nor the
+/// recall rides on this view any more:
+///
+/// * **Click → edit** is resolved GEOMETRICALLY at the catcher's release, by
+///   ``PinAttentionRule/pressedNote(atWindowPoint:in:)`` via ``SelectionGesture``,
+///   gated on the press not having travelled. So a click on a pin edits it in BOTH
+///   tools, and a drag from a pin still draws its frame.
+/// * **Recall** ("which note's pin is the pointer on?") is answered the same way
+///   from the catcher's `onContinuousHover`, which covers the whole surface and
+///   fires in both tools.
+///
+/// The `Button` below is therefore a point-mode convenience that duplicates a route
+/// that already works, not the mechanism — deliberately kept, because it is the one
+/// path that answers a press on the pin's exact pixels without consulting geometry,
+/// and it costs nothing to leave in agreement with the rule.
 struct AnnotationPins: View {
     @ObservedObject var session: AnnotationSession
 

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -326,8 +326,19 @@ struct OverlayView: View {
                                 tool: session.tool,
                                 from: value.startLocation,
                                 to: value.location,
-                                axOrigin: axOrigin
+                                axOrigin: axOrigin,
+                                // The retained notes, so a click that landed on a pin
+                                // re-opens that note rather than binding a new one.
+                                // Handing the WHOLE set (not a pre-filtered hit) keeps
+                                // the overlap tie-break — last drawn wins — inside the
+                                // rule with the geometry it belongs to.
+                                pins: session.pending
                             ) {
+                            case .editNote(let id):
+                                // The one branch that does NOT touch the app beneath:
+                                // it opens the note's own card, which nils `selected`
+                                // for the usual exactly-one-card-at-a-time reason.
+                                session.beginEditing(id: id)
                             case .point(let point):
                                 session.select(atAXPoint: point)
                             case .frame(let rect):

Sources/AnnotKit/Overlay/PinAttentionRule.swift

@@ -43,19 +43,53 @@ enum PinAttentionRule {
     /// window from empty space has already set the answer to nil on its way out.
     static let attentionRadius: CGFloat = pinDiameter
 
+    /// How close a CLICK must come to a pin's centre to open that note's editor —
+    /// the pin's OWN drawn radius, deliberately NOT ``attentionRadius``.
+    ///
+    /// The two differ because they are paid for differently. Attending a pin is free:
+    /// it draws a picture and takes nothing away, so a generous annulus outside the
+    /// pin costs a user nothing when it fires early. A click is scarce — the same
+    /// press could have selected the element underneath — so its target must be
+    /// exactly the circle the user can SEE. At ``attentionRadius`` a press 18pt clear
+    /// of a pin would silently open an editor instead of selecting what was pressed,
+    /// and the pin would be a 40pt hole in the canvas that looks 20pt wide.
+    static let pressRadius: CGFloat = pinDiameter / 2
+
     /// The id of the note whose pin the pointer at `point` (WINDOW-LOCAL, the space
     /// ``AnnotationNote/anchorRect`` is stored in) is attending, or nil for a point
     /// near no pin.
+    static func attendedNote(atWindowPoint point: CGPoint, in notes: [AnnotationNote]) -> String? {
+        note(atWindowPoint: point, in: notes, within: attentionRadius)
+    }
+
+    /// The id of the note whose pin a CLICK at `point` (WINDOW-LOCAL) landed on, or
+    /// nil for a press that hit no pin.
     ///
+    /// This is what makes click-to-edit work in BOTH tools. In point mode the pin is
+    /// a live `Button` and answers its own click; in frame mode it is deliberately
+    /// `allowsHitTesting(false)` — so a press there reaches the catcher, and geometry
+    /// is the only thing left that can say "that was pin 3". Deciding it from the
+    /// stored anchors rather than from a view means the answer does not depend on
+    /// which tool happens to be active, which is the whole defect this closes: a
+    /// note captured in frame mode could be read but never re-opened.
+    ///
+    /// The CALLER owns the click-vs-drag distinction (see ``SelectionGesture``): a
+    /// press that travelled is a drag, and a drag that began on a pin must still draw
+    /// its frame.
+    static func pressedNote(atWindowPoint point: CGPoint, in notes: [AnnotationNote]) -> String? {
+        note(atWindowPoint: point, in: notes, within: pressRadius)
+    }
+
     /// LAST NOTE WINS on overlap, because pins are drawn in `pending` order and a
     /// later one is therefore painted ON TOP of an earlier one. The user can only
-    /// mean the pin they can see.
-    static func attendedNote(atWindowPoint point: CGPoint, in notes: [AnnotationNote]) -> String? {
+    /// mean the pin they can see — which is why both callers share this walk rather
+    /// than each writing their own loop and disagreeing about the tie.
+    private static func note(atWindowPoint point: CGPoint, in notes: [AnnotationNote], within radius: CGFloat) -> String? {
         for note in notes.reversed() {
             guard let anchor = note.anchorRect?.origin else { continue }
             let dx = point.x - anchor.x
             let dy = point.y - anchor.y
-            if dx * dx + dy * dy <= attentionRadius * attentionRadius { return note.id }
+            if dx * dx + dy * dy <= radius * radius { return note.id }
         }
         return nil
     }

Sources/AnnotKit/Overlay/SelectionGesture.swift

@@ -44,6 +44,11 @@ enum SelectionGesture {
     /// — the transform living in one place is why the click path, the frame path
     /// and the highlight agree on a secondary display.
     enum Outcome: Equatable {
+        /// The press landed on the numbered pin of an already-captured note: open
+        /// that note's editor instead of binding anything new. Carries the note id
+        /// rather than a coordinate because nothing downstream needs the geometry —
+        /// the card anchors itself to the pin it belongs to.
+        case editNote(String)
         case point(CGPoint)
         case frame(CGRect)
         case none
@@ -61,12 +66,42 @@ enum SelectionGesture {
 
     /// Route a completed press. The one place the mode semantics live, so they are
     /// pinned by tests rather than by a human dragging a mouse.
+    ///
+    /// `pins` is the retained note set, consulted so a CLICK on an existing pin
+    /// re-opens that note instead of binding a new one — in BOTH tools. It defaults
+    /// to empty, which reproduces the original two-branch routing exactly, so a
+    /// caller with no notes on screen pays nothing and reads the same.
     static func resolve(
         tool: AnnotationSession.SelectionTool,
         from start: CGPoint,
         to end: CGPoint,
-        axOrigin: CGPoint
+        axOrigin: CGPoint,
+        pins: [AnnotationNote] = []
     ) -> Outcome {
+        // A CLICK on a pin edits that note, whatever the tool. Ordered FIRST because
+        // it is the most specific reading of the press: the user pressed a control
+        // that is on screen, drawn, and numbered, and every other branch below is
+        // about the app UNDERNEATH it.
+        //
+        // The travel gate is what keeps this from costing frame mode its main
+        // gesture. A press that travelled is a DRAG, and a drag that began on a pin
+        // must still draw its frame — pins sit exactly where the user just annotated,
+        // so they are precisely where the next frame gets drawn from (the `VRT-dp47`
+        // report, and the reason the pins are hit-test-inert in frame mode at all).
+        // Gating on travel rather than on tool keeps one sentence true of both: a
+        // click on a pin edits it, a drag from a pin draws.
+        //
+        // COORDINATES: `start` is WINDOW-LOCAL here, which is the space
+        // ``AnnotationNote/anchorRect`` is stored in — so it is handed to the rule
+        // UNSHIFTED. The `axOrigin` additions below are what turn the same point into
+        // the AX screen space the element queries use; adding it here too would look
+        // symmetrical and test every pin against a point off by the window's screen
+        // origin (invisible on the primary display, wrong on every other one).
+        if !travelledFarEnough(from: start, to: end),
+           let id = PinAttentionRule.pressedNote(atWindowPoint: start, in: pins) {
+            return .editNote(id)
+        }
+
         switch tool {
         case .point:
             // `startLocation`, not `location`: it is where the user AIMED, and it is