Overlay UX round 4 (cli-4gbzc): toggle glyphs, copy feedback, tooltips, X-to-exit, keyboard, colors

1. Annotate toggle uses the real Lucide pencil (idle) / pencil-off (annotating).
   Adds elliptical-arc (A/a) handling to the LucideShape parser (line-to-endpoint
   approximation) so the real Lucide d-strings render.
2. Copy shows a green check for ~1s as success feedback, then reverts.
3. Every pill icon gets a reliable hover tooltip (SwiftUI .help plus an
   NSView.toolTip backing for the non-activating overlay panel).
4. The X no longer unmounts the pill (which made it vanish permanently); it now
   exits annotate mode, and the pill is always visible in dev.
5. In the note field, Enter submits and Shift+Enter inserts a newline
   (.onKeyPress(keys: [.return]) checking the shift modifier), replacing the
   Cmd-Return decision. Applies to the composer and the pin editor.
6. Composer: 'Add note' (and the pin 'Save') are blue prominent buttons; the
   caret triangle now uses the card's material so it matches the box gray.
7. The pin-editor Delete button is red.

Build clean (Swift 6); 44 tests; AnnotKitProbe + AnnotKitOverlayProbe pass.

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

Author: angusbezzina

Sources/AnnotKit/Overlay/AnnotationPins.swift

@@ -91,14 +91,21 @@ private struct PinPopover: View {
         self._draft = State(initialValue: note.comment)
     }
 
+    /// Save the edited comment (Enter or the Save button) and dismiss.
+    private func save() {
+        guard !draft.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
+        session.updateNote(id: note.id, comment: draft)
+        isPresented = false
+    }
+
     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")
+                Text("⏎ save · ⇧⏎ newline")
                     .font(.caption2)
                     .foregroundStyle(.secondary)
                     .fixedSize()
@@ -109,20 +116,25 @@ private struct PinPopover: View {
                 .lineLimit(2 ... 5)
                 .frame(width: 240)
                 .focused($focused)
+                // Enter saves the edit; Shift+Enter inserts a newline.
+                .onKeyPress(keys: [.return]) { key in
+                    if key.modifiers.contains(.shift) { return .ignored }
+                    save()
+                    return .handled
+                }
             HStack {
                 Button(role: .destructive) {
                     session.deleteNote(id: note.id)
                     isPresented = false
                 } label: {
                     Label("Delete", systemImage: "trash")
+                        .foregroundStyle(.red)
                 }
+                .tint(.red)
                 Spacer()
-                Button("Save") {
-                    session.updateNote(id: note.id, comment: draft)
-                    isPresented = false
-                }
-                .keyboardShortcut(.return, modifiers: .command)
-                .disabled(draft.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                Button("Save") { save() }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(draft.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
             }
             .frame(width: 240)
         }

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -107,9 +107,8 @@ struct OverlayView: View {
                     .font(.headline)
                     .lineLimit(1)
                 Spacer(minLength: 8)
-                // The field is multiline (Return inserts a newline), so surface
-                // the submit/cancel keys instead of relying on a bare Return.
-                Text("⌘⏎ save · esc cancel")
+                // Enter submits; Shift+Enter inserts a newline; Esc cancels.
+                Text("⏎ save · ⇧⏎ newline")
                     .font(.caption2)
                     .foregroundStyle(.secondary)
                     .fixedSize()
@@ -120,6 +119,13 @@ struct OverlayView: View {
                 .lineLimit(2 ... 5)
                 .frame(width: 260)
                 .focused($composerFocused)
+                // Enter submits the note; Shift+Enter falls through to insert a
+                // newline in the multiline field.
+                .onKeyPress(keys: [.return]) { key in
+                    if key.modifiers.contains(.shift) { return .ignored }
+                    addNote()
+                    return .handled
+                }
             HStack {
                 Button("Cancel") {
                     comment = ""
@@ -129,33 +135,23 @@ struct OverlayView: View {
                 // panel is key while typing, so the shortcut reaches this button.
                 .keyboardShortcut(.cancelAction)
                 Spacer()
-                Button("Add note") {
-                    // Snapshot the pin anchor BEFORE addNote clears the selection:
-                    // element AX top-left minus axOrigin, the same window-local
-                    // transform the highlight uses, so the pin lands on the
-                    // element's top-left corner.
-                    let anchor = session.selected.map {
-                        CGPoint(x: $0.frame.minX - axOrigin.x, y: $0.frame.minY - axOrigin.y)
-                    }
-                    session.addNote(comment: comment, anchor: anchor)
-                    comment = ""
-                }
-                // Multiline field: Return is a newline, ⌘Return submits.
-                .keyboardShortcut(.return, modifiers: .command)
-                .disabled(comment.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                Button("Add note") { addNote() }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(comment.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
             }
             .frame(width: 260)
         }
         .padding(12)
         .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 10))
-        // Accent caret in the gap, tying the card back to the highlighted
-        // element: it uses the same accent as the highlight stroke, points up
-        // when the card is below (down when flipped above), and slides
-        // horizontally (`caretDX`) to line up with the element's center. Added
-        // before the shadow so the card and caret cast one unified shadow.
+        // Caret in the gap, tying the card back to the highlighted element. It
+        // uses the SAME material as the card so it reads as the card's pointer
+        // (not an accent), points up when the card is below (down when flipped
+        // above), and slides horizontally (`caretDX`) to line up with the
+        // element's center. Added before the shadow so card and caret cast one
+        // unified shadow.
         .overlay(alignment: placement.caretPointsUp ? .top : .bottom) {
             ComposerCaret(pointsUp: placement.caretPointsUp)
-                .fill(Color.accentColor)
+                .fill(.regularMaterial)
                 .frame(width: 16, height: 8)
                 .offset(x: placement.caretDX, y: placement.caretPointsUp ? -7 : 7)
         }
@@ -187,6 +183,20 @@ struct OverlayView: View {
         Task { @MainActor in composerFocused = true }
     }
 
+    /// Capture the pending note. Snapshots the pin anchor BEFORE `addNote` clears
+    /// the selection (element AX top-left minus axOrigin — the same window-local
+    /// transform the highlight uses — so the pin lands on the element's top-left
+    /// corner), then resets the field. Enter submits; Shift+Enter inserts a
+    /// newline (handled in the field's `onKeyPress`).
+    private func addNote() {
+        guard !comment.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
+        let anchor = session.selected.map {
+            CGPoint(x: $0.frame.minX - axOrigin.x, y: $0.frame.minY - axOrigin.y)
+        }
+        session.addNote(comment: comment, anchor: anchor)
+        comment = ""
+    }
+
     /// Estimated card size (260 field + 12 padding each side ≈ 284 wide; a
     /// representative height). Only used to clamp the card on-screen and to pick
     /// below vs above — the caret attaches to the card's real edge via layout, so
@@ -253,29 +263,35 @@ private struct ToolbarView: View {
     let onClose: () -> Void
 
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @State private var justCopied = false
 
     private var annotating: Bool { session.mode == .annotating }
     private var hasNotes: Bool { !session.pending.isEmpty }
 
     var body: some View {
         HStack(spacing: 2) {
             PillButton(
-                icon: .pencil,
+                icon: annotating ? .pencilOff : .pencil,
                 isActive: annotating,
                 tooltip: annotating ? "Stop annotating" : "Annotate",
                 action: onToggle
             )
 
             if hasNotes {
-                PillButton(icon: .copy, tooltip: "Copy notes (Markdown)", action: onCopy)
+                PillButton(
+                    icon: justCopied ? .check : .copy,
+                    glyphTint: justCopied ? PillStyle.success : nil,
+                    tooltip: justCopied ? "Copied" : "Copy notes (Markdown)",
+                    action: { onCopy(); flashCopied() }
+                )
                 PillButton(icon: .download, tooltip: "Export to AGENTATION_NOTES.md", action: onExport)
                 PillButton(icon: .trash, isDestructive: true, tooltip: "Clear notes") {
                     session.clear()
                 }
             }
 
             divider
-            PillButton(icon: .close, tooltip: "Close", action: onClose)
+            PillButton(icon: .close, tooltip: "Exit annotate mode", action: onClose)
         }
         .padding(.horizontal, 6)
         .padding(.vertical, 8) // 28pt buttons + 8*2 -> 44pt pill height
@@ -299,6 +315,16 @@ private struct ToolbarView: View {
         .animation(reduceMotion ? nil : .easeOut(duration: 0.15), value: hasNotes)
     }
 
+    /// Show a green check on the Copy button for a beat as success feedback, then
+    /// revert to the copy glyph.
+    private func flashCopied() {
+        justCopied = true
+        Task { @MainActor in
+            try? await Task.sleep(for: .seconds(1))
+            justCopied = false
+        }
+    }
+
     /// Compact count bubble that overlaps the pill's top-left corner. A ~18pt
     /// accent capsule (grows for multi-digit counts) with white monospaced digits
     /// and a thin dark ring for contrast; reuses the accent so it reads as one
@@ -330,13 +356,15 @@ private struct PillButton: View {
     let icon: LucideIcon
     var isActive: Bool = false
     var isDestructive: Bool = false
+    var glyphTint: Color? = nil
     let tooltip: String
     let action: () -> Void
 
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
     @State private var hovering = false
 
     private var glyphColor: Color {
+        if let glyphTint { return glyphTint }
         if isDestructive && hovering { return .white }
         if isActive { return .white }
         return hovering ? PillStyle.iconHover : PillStyle.iconIdle
@@ -360,7 +388,7 @@ private struct PillButton: View {
                 .contentShape(Circle())
         }
         .buttonStyle(PressablePillButtonStyle(reduceMotion: reduceMotion))
-        .help(tooltip)
+        .pillToolTip(tooltip)
         .accessibilityLabel(tooltip)
         .onHover { value in
             guard !reduceMotion else { hovering = value; return }

Sources/AnnotKit/Overlay/PillStyle.swift

@@ -37,6 +37,7 @@ enum PillStyle {
     static let iconHover = Color.white.opacity(0.8)
     static let hoverBackground = Color.white.opacity(0.1)
     static let destructive = Color(hex: "EF4444")
+    static let success = Color(hex: "22C55E")
     static let divider = Color.white.opacity(0.08)
 }
 
@@ -62,14 +63,21 @@ enum IconPart {
 struct LucideIcon {
     let parts: [IconPart]
 
-    /// The annotate-toggle glyph (an annotate-indicative `pencil`). Authored from
-    /// straight strokes only — Lucide's real `pencil` and `square-dashed-mouse-
-    /// pointer` are arc-heavy, and the primitive `d`-parser implements no
-    /// elliptical arc (`A`) command, so this follows the existing `download`
-    /// precedent: a diagonal shaft with a triangular tip, plus a collar band.
+    /// Lucide `pencil` — the annotate toggle's IDLE glyph. Uses the real Lucide
+    /// `d` strings; the parser approximates the small corner arcs (`a`) as a line
+    /// to the arc endpoint, which reads identically at 16pt.
     static let pencil = LucideIcon(parts: [
-        .path("M4 20 L4 16 L14 6 L18 10 L8 20 Z"),
-        .line(CGPoint(x: 13, y: 7), CGPoint(x: 17, y: 11)),
+        .path("M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"),
+        .path("m15 5 4 4"),
+    ])
+
+    /// Lucide `pencil-off` — the annotate toggle's ACTIVE (annotating) glyph: the
+    /// pencil with a diagonal slash through it.
+    static let pencilOff = LucideIcon(parts: [
+        .path("m10 10-6.157 6.162a2 2 0 0 0-.5.833l-1.322 4.36a.5.5 0 0 0 .622.624l4.358-1.323a2 2 0 0 0 .83-.5L14 13.982"),
+        .path("m12.829 7.172 4.359-4.346a1 1 0 1 1 3.986 3.986l-4.353 4.353"),
+        .path("m15 5 4 4"),
+        .path("m2 2 20 20"),
     ])
 
     static let check = LucideIcon(parts: [.path("M20 6 9 17l-5-5")])
@@ -201,6 +209,17 @@ struct LucideShape: Shape {
                 let end = rel ? CGPoint(x: current.x + c, y: current.y + d2) : CGPoint(x: c, y: d2)
                 current = end
                 path.addQuadCurve(to: scaled(end), control: scaled(ctrl))
+            case "A", "a":
+                // Elliptical arc. The parser has no arc-to-bezier, so it draws a
+                // straight segment to the arc ENDPOINT — Lucide's pencil/pencil-off
+                // arcs are small corner rounds and the flat eraser diagonal, which
+                // read the same at 16pt. Consume all 7 params (rx ry rot large
+                // sweep x y).
+                guard nextNumber() != nil, nextNumber() != nil, nextNumber() != nil,
+                      nextNumber() != nil, nextNumber() != nil,
+                      let ax = nextNumber(), let ay = nextNumber() else { return }
+                current = command == "a" ? CGPoint(x: current.x + ax, y: current.y + ay) : CGPoint(x: ax, y: ay)
+                path.addLine(to: scaled(current))
             case "Z", "z":
                 path.closeSubpath()
                 current = subStart
@@ -254,3 +273,35 @@ struct LucideShape: Shape {
         return tokens
     }
 }
+
+// MARK: - Tooltip
+
+#if os(macOS)
+/// A zero-content `NSView` carrying a `toolTip`, layered behind a control so the
+/// hover tooltip shows reliably inside the borderless, non-activating overlay
+/// panel (where SwiftUI's `.help` alone can fail to render).
+private struct ToolTipBacking: NSViewRepresentable {
+    let text: String
+    func makeNSView(context: Context) -> NSView {
+        let view = NSView()
+        view.toolTip = text
+        return view
+    }
+    func updateNSView(_ view: NSView, context: Context) {
+        view.toolTip = text
+    }
+}
+#endif
+
+extension View {
+    /// Hover tooltip for a pill control: SwiftUI `.help` plus (on macOS) an
+    /// NSView-backed `toolTip` for reliability inside the overlay panel.
+    @ViewBuilder
+    func pillToolTip(_ text: String) -> some View {
+        #if os(macOS)
+        help(text).background(ToolTipBacking(text: text))
+        #else
+        help(text)
+        #endif
+    }
+}

Sources/AnnotKit/macOS/OverlayController.swift

@@ -152,7 +152,9 @@ public final class OverlayController: NSObject {
             onToggle: { [weak self] in self?.toggle() },
             onCopy: { [weak self] in self?.copy() },
             onExport: { [weak self] in self?.export() },
-            onClose: { [weak self] in self?.unmount() },
+            // The pill's X exits annotate mode; it does NOT unmount the overlay.
+            // Dev overlays stay visible so the pill is always reachable.
+            onClose: { [weak self] in self?.stop() },
             // Make the non-activating child panel key so the composer/pin-editor
             // text fields accept keystrokes (a plain borderless panel that is not
             // key silently drops typing).

Tests/AnnotKitTests/LucideIconTests.swift

@@ -12,6 +12,7 @@ final class LucideIconTests: XCTestCase {
 
     private let icons: [(name: String, icon: LucideIcon)] = [
         ("pencil", .pencil),
+        ("pencilOff", .pencilOff),
         ("check", .check),
         ("copy", .copy),
         ("download", .download),