feat(marquee): session entry point + persisted frame on notes

`AnnotationSession.select(inAXRect:)` is the marquee counterpart to `select(atAXPoint:)`. It delegates to `MarqueeTargetSource.marqueeLadder(in:)`, whose ladder contract is identical to `ComponentLadderSource`'s, so widening and the note's `component` field keep working untouched. A drag that resolves to nothing degrades to a REGION note anchored at the frame's centre, mirroring the no-hit click path but carrying the drawn frame instead of a point. The drawn frame is held ABSOLUTE (`selectedMarqueeRect`) and relativized only at `addNote`, because `widenSelection()` can rebind the note to an enclosing element AFTER the drag — a frame relativized at selection time would describe a box the note no longer names. Synthetic regions measure from `marqueeRegionOrigin` (the anchor) since their own frame IS the drawn rect and would trivially be (0, 0). Both new fields carry the exact stale-state hazard 7993a67 fixed for `selectedRegionOffset`: the `selected` didSet only clears on nil, never on replacement, so they are also cleared at the top of BOTH select entry points. Tests cover the regression in both directions (marquee -> click must not leak `regionRect`; region-click -> marquee must not leak `regionOffset`). `AnnotationNote.regionRect` follows the additive-optional pattern of `regionOffset` (doc comment, CodingKeys entry, trailing defaulted init param), so old JSON decodes to nil and click notes serialize unchanged. The formatter emits `**Region**: framed WxH at (x: X, y: Y) from the top-left of <selector>` as an `else if` against the point-offset line — the two locators are mutually exclusive by construction and the chain documents that. 86 -> 99 tests, all green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
angusbezzina · Aug 10, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
commit 5e99ca61a54be05356ed3419f02366236d0b3908
diff --git a/Sources/AnnotKit/AnnotationSink.swift b/Sources/AnnotKit/AnnotationSink.swift
@@ -70,6 +70,14 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
     /// the top-left of #Dashboard.Today"). Optional, so element notes serialize
     /// unchanged and old files decode (nil).
     public var regionOffset: CGPoint?
+    /// MARQUEE note: the frame the user DREW, with its origin relative to the
+    /// top-left of the element named by `selector` (its size is absolute). Like
+    /// `regionOffset` it is PERSISTED — it is the locator agents need when the
+    /// user framed a spot rather than clicked one ("a 320x48 band 40pt down inside
+    /// #Settings.Models"). Mutually exclusive with `regionOffset` by construction:
+    /// a note carries the point locator or the frame locator, never both. Optional,
+    /// so click notes serialize unchanged and old files decode (nil).
+    public var regionRect: CGRect?
 
     /// Explicit keys that OMIT `anchor`: `JSONFileSink` and the MCP
     /// `FileNotesStore` encode/decode `[AnnotationNote]` directly, so a naked
@@ -79,7 +87,7 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
     private enum CodingKeys: String, CodingKey {
         case id, route, selector, elementPath, selectedText, comment, screenshot, timestamp
         case component, elementRole, elementText, unseeded
-        case regionOffset
+        case regionOffset, regionRect
     }
 
     public init(
@@ -96,7 +104,8 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
         screenshot: CapturedImage? = nil,
         timestamp: String,
         anchor: CGPoint? = nil,
-        regionOffset: CGPoint? = nil
+        regionOffset: CGPoint? = nil,
+        regionRect: CGRect? = nil
     ) {
         self.id = id
         self.route = route
@@ -112,5 +121,6 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
         self.timestamp = timestamp
         self.anchor = anchor
         self.regionOffset = regionOffset
+        self.regionRect = regionRect
     }
 }
diff --git a/Sources/AnnotKit/Overlay/AnnotationSession.swift b/Sources/AnnotKit/Overlay/AnnotationSession.swift
@@ -23,12 +23,15 @@ public final class AnnotationSession: ObservableObject {
     @Published public private(set) var pending: [AnnotationNote] = []
     @Published public private(set) var hovered: Element?
     @Published public private(set) var selected: Element? {
-        // The region offset and the widening ladder only make sense while their
-        // selection is alive; clearing the selection (capture, cancel, stop, pin
-        // editing) must never leave a stale offset or ladder for the NEXT note.
+        // The region offset, the drawn marquee frame, and the widening ladder only
+        // make sense while their selection is alive; clearing the selection
+        // (capture, cancel, stop, pin editing) must never leave a stale offset,
+        // frame, or ladder for the NEXT note.
         didSet {
             if selected == nil {
                 selectedRegionOffset = nil
+                selectedMarqueeRect = nil
+                marqueeRegionOrigin = nil
                 componentLadder = []
                 ladderIndex = 0
             }
@@ -38,6 +41,19 @@ public final class AnnotationSession: ObservableObject {
     /// (see ``select(atAXPoint:)``); nil for ordinary element selections.
     public private(set) var selectedRegionOffset: CGPoint?
 
+    /// The frame the user DREW for the current selection, in ABSOLUTE AX screen
+    /// coordinates; nil for click selections. Kept absolute (not element-relative)
+    /// so ``widenSelection()`` re-relativizes it for free: widening rebinds the
+    /// note to an enclosing element with a different origin, and a frame already
+    /// relativized at selection time would then silently describe the drag against
+    /// a box the note no longer names.
+    public private(set) var selectedMarqueeRect: CGRect?
+    /// Origin the drawn frame is measured from when the selection is a synthetic
+    /// REGION — whose own `frame` IS the drawn rect, so it cannot be its own
+    /// reference (it would relativize to 0,0 and locate nothing). nil for element
+    /// selections, which measure from the selected element's origin.
+    private var marqueeRegionOrigin: CGPoint?
+
     /// The component-widening ladder for the current selection (target first, each
     /// enclosing identified component after), and the index of the currently
     /// selected rung. Populated on ``select(atAXPoint:)`` when the source offers a
@@ -122,11 +138,15 @@ public final class AnnotationSession: ObservableObject {
         // Any catcher tap dismisses an open pin editor: a tap on empty space is a
         // click-away close, and a tap on an element hands the stage to the composer.
         editingNoteID = nil
-        // Every selection starts offset-free and ladder-free: a region -> element
-        // re-selection (the catcher stays active behind an open composer) must not
-        // leak the previous region's offset or ladder onto an ELEMENT note — the
-        // didSet only clears them when `selected` becomes nil, not on replacement.
+        // Every selection starts offset-free, frame-free and ladder-free: a
+        // region -> element or marquee -> click re-selection (the catcher stays
+        // active behind an open composer) must not leak the previous region's
+        // offset, the previous drag's drawn frame, or a stale ladder onto the next
+        // note — the didSet only clears them when `selected` becomes nil, not on
+        // replacement.
         selectedRegionOffset = nil
+        selectedMarqueeRect = nil
+        marqueeRegionOrigin = nil
         componentLadder = []
         ladderIndex = 0
         selected = source.hitTest(point)
@@ -160,6 +180,84 @@ public final class AnnotationSession: ObservableObject {
         return selected
     }
 
+    /// Select the annotation target for a frame the user DREW (AX top-left screen
+    /// coordinates) — the marquee gesture: press-drag a rectangle AROUND what you
+    /// mean instead of hunting for the one pixel that hit-tests to it.
+    ///
+    /// The source resolves the frame (``MarqueeTargetSource``) and hands back the
+    /// same target-first, broadest-last ladder ``ComponentLadderSource`` produces,
+    /// so widening and the note's `component` field work unchanged. When nothing
+    /// in the frame is annotatable the drag is NOT dropped: it degrades to a
+    /// REGION note anchored at the frame's centre, exactly as a no-hit click does,
+    /// but carrying the drawn frame rather than a single point.
+    @discardableResult
+    public func select(inAXRect rect: CGRect) -> Element? {
+        guard mode == .annotating else { return nil }
+        // A drag on the catcher dismisses an open pin editor for the same reason a
+        // tap does: the composer is about to take the stage.
+        editingNoteID = nil
+        // Same stale-state hazard as the point path, and then some — a marquee ->
+        // click flow must not leak `selectedMarqueeRect` onto the click's note, and
+        // a region-click -> marquee flow must not leak `selectedRegionOffset` onto
+        // the framed one. The didSet only fires on nil, not on replacement.
+        selectedRegionOffset = nil
+        selectedMarqueeRect = nil
+        marqueeRegionOrigin = nil
+        componentLadder = []
+        ladderIndex = 0
+
+        // Normalize once: a right-to-left or bottom-to-top drag arrives with
+        // negative extents. A zero-width or zero-height rect is a click that never
+        // moved, not a marquee — bail before the region fallback too, or a stray
+        // press would silently plant a degenerate framed note.
+        let normalized = rect.standardized
+        guard normalized.width > 0, normalized.height > 0 else { return nil }
+
+        if let marqueeSource = source as? MarqueeTargetSource {
+            let ladder = marqueeSource.marqueeLadder(in: normalized)
+            if let {
+                selected = target
+                componentLadder = ladder
+                ladderIndex = 0
+                selectedMarqueeRect = normalized
+                return selected
+            }
+        }
+
+        // Region fallback, mirroring the point path but anchored at the frame's
+        // CENTRE — the one point inside a drawn rect that is nearest everything it
+        // covers, so the anchor a user would name themselves.
+        if let anchorSource = source as? RegionAnchorSource,
+           let anchorElement = anchorSource.regionAnchor(at: CGPoint(x: normalized.midX, y: normalized.midY)) {
+            let offset = CGPoint(
+                x: (normalized.minX - anchorElement.frame.minX).rounded(),
+                y: (normalized.minY - anchorElement.frame.minY).rounded()
+            )
+            let anchorName = anchorElement.label.isEmpty ? anchorElement.id : anchorElement.label
+            selected = Element(
+                id: anchorElement.id,
+                role: "AXRegion",
+                type: "Region",
+                label: "Region \(Int(normalized.width))x\(Int(normalized.height)) at (\(Int(offset.x)), \(Int(offset.y))) in \(anchorName)",
+                value: "",
+                // The DRAWN rect, not a marker at a point, so the overlay
+                // highlights the frame the user actually swept.
+                frame: normalized,
+                isVisible: true,
+                isActionable: false,
+                path: anchorElement.path
+            )
+            selectedMarqueeRect = normalized
+            // The synthetic element's frame IS the drawn rect, so it cannot be its
+            // own measuring stick; record the anchor's origin instead.
+            marqueeRegionOrigin = anchorElement.frame.origin
+            // Deliberately NOT setting `selectedRegionOffset`: `regionOffset` stays
+            // the point-click locator so every note carries exactly one, and the
+            // formatter's framed/offset branches stay mutually exclusive.
+        }
+        return selected
+    }
+
     /// Step the current selection UP to the next enclosing identified component
     /// (a coarser-grained note: the card instead of the label inside it). No-op
     /// when the selection is already at the broadest rung, is a region, or the
@@ -171,6 +269,10 @@ public final class AnnotationSession: ObservableObject {
         ladderIndex += 1
         // Widening always lands on a real element, so it is never a region note.
         selectedRegionOffset = nil
+        // `selectedMarqueeRect` is deliberately KEPT: it is absolute, so it is
+        // still the frame the user drew whichever rung is now bound, and `addNote`
+        // re-relativizes it against the widened element. `marqueeRegionOrigin` is
+        // moot here — regions get no ladder, so a widen can never start from one.
         // A non-nil assignment does not trip the didSet clear, so the ladder and
         // index survive for a further widen.
         selected = componentLadder[ladderIndex]
@@ -206,6 +308,20 @@ public final class AnnotationSession: ObservableObject {
             ? ownIdentifier
             : (componentLadder.dropFirst().first?.id
                 ?? element.path.last(where: { !($0.identifier ?? "").isEmpty })?.identifier)
+        // Relativize the drawn frame HERE rather than at selection — the asymmetry
+        // with `regionOffset` (computed at selection) is deliberate:
+        // ``widenSelection()`` can rebind the note to an enclosing element AFTER
+        // the frame was drawn, so the persisted rect must be measured against
+        // whatever element the note FINALLY names. A region never widens, so its
+        // offset's anchor is fixed the moment it is picked.
+        let regionRect: CGRect? = selectedMarqueeRect.map { drawn in
+            // A synthetic region's own frame IS the drawn rect, so it measures from
+            // its anchor (else it would trivially be 0,0); elements measure from
+            // themselves.
+            let base = marqueeRegionOrigin ?? element.frame.origin
+            return CGRect(x: (drawn.minX - base.x).rounded(), y: (drawn.minY - base.y).rounded(),
+                          width: drawn.width.rounded(), height: drawn.height.rounded())
+        }
         let note = AnnotationNote(
             id: makeID(),
             route: route(),
@@ -220,7 +336,8 @@ public final class AnnotationSession: ObservableObject {
             screenshot: screenshot,
             timestamp: timestamp(),
             anchor: anchor,
-            regionOffset: selectedRegionOffset
+            regionOffset: selectedRegionOffset,
+            regionRect: regionRect
         )
         pending.append(note)
         selected = nil

diff --git a/Sources/AnnotKit/Sinks/AnnotationFormatter.swift b/Sources/AnnotKit/Sinks/AnnotationFormatter.swift
@@ -40,7 +40,14 @@ public enum AnnotationFormatter {
         if note.unseeded == true {
             lines.append("**Unseeded**: the clicked element has no accessibilityIdentifier — locate it via the Component above, then narrow by the Element role/text; consider seeding it")
         }
-        if let region = note.regionOffset {
+        // `else if`, not a second `if`: the two locators are mutually exclusive by
+        // construction (a note is framed or it is a point, never both), and the
+        // chain is what documents that — two independent lines would let a future
+        // leak of one into the other print a self-contradicting block instead of
+        // failing loudly.
+        if let rect = note.regionRect {
+            lines.append("**Region**: framed \(Int(rect.width))x\(Int(rect.height)) at (x: \(Int(rect.minX)), y: \(Int(rect.minY))) from the top-left of \(note.selector)")
+        } else if let region = note.regionOffset {
             lines.append("**Region**: (x: \(Int(region.x)), y: \(Int(region.y))) from the top-left of \(note.selector)")
         }
         if let selected = note.selectedText, !selected.isEmpty {
@@ -74,6 +81,10 @@ public enum AnnotationFormatter {
         let timestamp: String
         let regionOffsetX: Int?
         let regionOffsetY: Int?
+        let regionRectX: Int?
+        let regionRectY: Int?
+        let regionRectWidth: Int?
+        let regionRectHeight: Int?
         let screenshotPixelWidth: Int?
         let screenshotPixelHeight: Int?
 
@@ -91,6 +102,10 @@ public enum AnnotationFormatter {
             timestamp = note.timestamp
             regionOffsetX = note.regionOffset.map { Int($0.x) }
             regionOffsetY = note.regionOffset.map { Int($0.y) }
+            regionRectX = note.regionRect.map { Int($0.minX) }
+            regionRectY = note.regionRect.map { Int($0.minY) }
+            regionRectWidth = note.regionRect.map { Int($0.width) }
+            regionRectHeight = note.regionRect.map { Int($0.height) }
             screenshotPixelWidth = note.screenshot?.pixelWidth
             screenshotPixelHeight = note.screenshot?.pixelHeight
         }