Annotation UX round 3 (cli-i2bnm): numbered comment pins, pill polish, composer autofocus

- Numbered comment pins (feature 1): each captured note stores a WINDOW-LOCAL
  anchor (element AX top-left minus axOrigin at capture) so a pin stays glued to
  where the note was made under host-window moves (fixed, not live-tracked). Pins
  render only in annotate mode, layered above the catcher so they consume their
  own hover/click and never re-select the element. Hovering a pin opens an
  inline-editable popover (edit + delete-this-comment) via new
  AnnotationSession.updateNote/deleteNote; pin numbers and the count badge derive
  from the retained set, so delete reflows both. anchor is UI-only (omitted from
  CodingKeys) so the JSON store + MCP payload are byte-identical.

- Pill polish (feature 2): count bubble overlaps the whole pill's top-left corner;
  annotate toggle active state is a white glyph with no blue circle; the media
  play/pause glyph is replaced with a pencil (Lucide square-dashed-mouse-pointer
  needs elliptical arcs + dashed strokes the shared LucideShape parser/stroker do
  not support).

- Composer autofocus (feature 3): the field focuses on element click (panel made
  key first, since the child panel is non-activating); Escape cancels; the
  multiline field keeps Return-as-newline with Cmd-Return to submit. Focus is
  re-asserted on the next tick for both the composer and the pin editor to beat
  the first-responder race.

New AnnotKitOverlayProbe pin-model assertions (distinct window-local anchors;
updateNote edits; deleteNote reflows). Build clean (Swift 6); 44 tests; both
probes pass.

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

Author: angusbezzina

Sources/AnnotKit/AnnotationSink.swift

@@ -1,3 +1,4 @@
+import CoreGraphics
 import Foundation
 
 /// Output format for sinks that serialize notes as a blob (clipboard, logs).
@@ -40,6 +41,21 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
     /// ISO-8601 timestamp, injected by the caller (kept out of pure logic so the
     /// model stays deterministic and testable).
     public var timestamp: String
+    /// Window-local top-left where the numbered pin is drawn in annotate mode
+    /// (the element's AX frame origin minus the host window's `axOrigin` AT
+    /// CAPTURE). UI-only: intentionally NOT persisted — it is omitted from
+    /// ``CodingKeys`` so the on-disk JSON store and the MCP payload stay
+    /// byte-for-byte unchanged, and older files still decode (`anchor` -> nil).
+    public var anchor: CGPoint?
+
+    /// Explicit keys that OMIT `anchor`: `JSONFileSink` and the MCP
+    /// `FileNotesStore` encode/decode `[AnnotationNote]` directly, so a naked
+    /// stored property would leak the pin position into the serialized record.
+    /// `anchor` decodes to nil when absent, so the store and old files round-trip
+    /// unchanged.
+    private enum CodingKeys: String, CodingKey {
+        case id, route, selector, elementPath, selectedText, comment, screenshot, timestamp
+    }
 
     public init(
         id: String,
@@ -49,7 +65,8 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
         selectedText: String? = nil,
         comment: String,
         screenshot: CapturedImage? = nil,
-        timestamp: String
+        timestamp: String,
+        anchor: CGPoint? = nil
     ) {
         self.id = id
         self.route = route
@@ -59,5 +76,6 @@ public struct AnnotationNote: Sendable, Hashable, Identifiable, Codable {
         self.comment = comment
         self.screenshot = screenshot
         self.timestamp = timestamp
+        self.anchor = anchor
     }
 }

Sources/AnnotKit/Overlay/AnnotationPins.swift

@@ -0,0 +1,144 @@
+import SwiftUI
+
+/// Numbered comment pins (Feature 1), shared by the macOS and iOS overlay hosts.
+///
+/// Each captured note carries a window-local ``AnnotationNote/anchor`` — the
+/// element's AX top-left minus the host window's `axOrigin` AT CAPTURE — so a pin
+/// stays glued to where the note was made when the host WINDOW moves (the panel is
+/// a child window, so a window-local value is invariant under a window drag). It is
+/// FIXED, not live-tracked: it will not chase a scrolled element (accepted).
+///
+/// Pins are annotate-mode-only chrome, mounted in ``OverlayView`` ABOVE the
+/// full-window catcher and BELOW the composer/toolbar, so each pin consumes its
+/// own hover/click and can never fall through to re-select the element beneath it.
+/// The whole overlay stays `accessibilityHidden`, so pins never disturb the AX
+/// point query's see-through.
+struct AnnotationPins: View {
+    @ObservedObject var session: AnnotationSession
+
+    var body: some View {
+        // Enumerate the FULL retained set so a pin's number matches the count
+        // badge; notes captured without an anchor simply draw nothing.
+        ForEach(Array(session.pending.enumerated()), id: \.element.id) { index, note in
+            if let anchor = note.anchor {
+                AnnotationPin(session: session, note: note, number: index + 1, anchor: anchor)
+            }
+        }
+    }
+}
+
+/// A single numbered pin overlapping the element's top-left corner. It is a button
+/// that consumes its own click (opens the editor, never selects), and — sitting
+/// above the catcher — its hover/click cannot fall through to the element.
+private struct AnnotationPin: View {
+    @ObservedObject var session: AnnotationSession
+    let note: AnnotationNote
+    let number: Int
+    let anchor: CGPoint
+
+    @State private var editing = false
+
+    private let diameter: CGFloat = 20
+
+    var body: some View {
+        Button {
+            editing = true
+        } label: {
+            Text("\(number)")
+                .font(.caption2.monospacedDigit().bold())
+                .foregroundStyle(.white)
+                .frame(width: diameter, height: diameter)
+                .background(Circle().fill(Color.accentColor))
+                .overlay(Circle().strokeBorder(Color.black.opacity(0.35), lineWidth: 1))
+                .contentShape(Circle())
+        }
+        .buttonStyle(.plain)
+        .shadow(color: .black.opacity(0.3), radius: 3, y: 1)
+        // Open the editor on hover; do NOT close on hover-exit. Pure hover-driven
+        // popovers are finicky — moving the pointer from the pin INTO the popover
+        // can dismiss it — so this uses the stable "open on hover, close
+        // explicitly" rule: the popover owns dismissal (click-away / Save / Delete
+        // / Esc).
+        .onHover { inside in
+            if inside { editing = true }
+        }
+        .popover(isPresented: $editing, arrowEdge: .top) {
+            PinPopover(session: session, note: note, isPresented: $editing)
+        }
+        // The overlay ZStack is `.topLeading`, so centering the pin on the
+        // element's top-left corner is `anchor - radius`.
+        .offset(x: anchor.x - diameter / 2, y: anchor.y - diameter / 2)
+    }
+}
+
+/// The pin's edit popover: an auto-focused, inline-editable comment field plus
+/// Save and Delete. Reuses Feature 3's focus pattern (`@FocusState` + `.onAppear`),
+/// ⌘Return to save, and Escape to cancel. Save edits the retained note in place;
+/// Delete drops it from `pending`, so the `ForEach` reflows the numbers and the
+/// count badge automatically.
+private struct PinPopover: View {
+    @ObservedObject var session: AnnotationSession
+    let note: AnnotationNote
+    @Binding var isPresented: Bool
+
+    @State private var draft: String
+    @FocusState private var focused: Bool
+
+    init(session: AnnotationSession, note: AnnotationNote, isPresented: Binding<Bool>) {
+        self.session = session
+        self.note = note
+        self._isPresented = isPresented
+        self._draft = State(initialValue: note.comment)
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack(spacing: 8) {
+                Text(note.selector)
+                    .font(.caption.monospaced())
+                    .lineLimit(1)
+                Spacer(minLength: 8)
+                Text("⌘⏎ save · esc cancel")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                    .fixedSize()
+            }
+            .frame(width: 240)
+            TextField("Describe the change", text: $draft, axis: .vertical)
+                .textFieldStyle(.roundedBorder)
+                .lineLimit(2 ... 5)
+                .frame(width: 240)
+                .focused($focused)
+            HStack {
+                Button(role: .destructive) {
+                    session.deleteNote(id: note.id)
+                    isPresented = false
+                } label: {
+                    Label("Delete", systemImage: "trash")
+                }
+                Spacer()
+                Button("Save") {
+                    session.updateNote(id: note.id, comment: draft)
+                    isPresented = false
+                }
+                .keyboardShortcut(.return, modifiers: .command)
+                .disabled(draft.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            }
+            .frame(width: 240)
+        }
+        .padding(12)
+        // Auto-focus the field on appearance (same pattern as the composer). The
+        // popover presents in its own window, so `makeKey` on the parent panel does
+        // not apply here; re-assert focus on the next tick to beat the same
+        // first-responder race the composer guards against.
+        .onAppear {
+            focused = true
+            Task { @MainActor in focused = true }
+        }
+        #if os(macOS)
+        // Escape cancels without saving (macOS/tvOS-only API; iOS dismisses the
+        // popover by tapping away).
+        .onExitCommand { isPresented = false }
+        #endif
+    }
+}

Sources/AnnotKit/Overlay/AnnotationSession.swift

@@ -89,7 +89,8 @@ public final class AnnotationSession: ObservableObject {
     public func addNote(
         comment: String,
         selectedText: String? = nil,
-        screenshot: CapturedImage? = nil
+        screenshot: CapturedImage? = nil,
+        anchor: CGPoint? = nil
     ) -> AnnotationNote? {
         guard let element = selected else { return nil }
         let note = AnnotationNote(
@@ -100,13 +101,28 @@ public final class AnnotationSession: ObservableObject {
             selectedText: selectedText,
             comment: comment,
             screenshot: screenshot,
-            timestamp: timestamp()
+            timestamp: timestamp(),
+            anchor: anchor
         )
         pending.append(note)
         selected = nil
         return note
     }
 
+    /// Edit a retained note's comment in place (the numbered-pin edit popover).
+    /// No-op if the id is no longer present.
+    public func updateNote(id: String, comment: String) {
+        guard let index = pending.firstIndex(where: { $0.id == id }) else { return }
+        pending[index].comment = comment
+    }
+
+    /// Remove a retained note (the numbered-pin delete action). The pin numbers
+    /// and the count badge are DERIVED from `pending`'s order and size, so
+    /// dropping a note reflows both for free — no explicit renumbering.
+    public func deleteNote(id: String) {
+        pending.removeAll { $0.id == id }
+    }
+
     /// Write the full retained set to the sink, WITHOUT clearing it. Notes
     /// persist until ``clear()``, so the same set can be exported repeatedly (and
     /// also copied). The file sink overwrites its file with the current set, so