fix(cards): Shift+Enter inserts a line break instead of eating the text

The card promises "⏎ save · ⇧⏎ newline" in its own header and the second
half was not true. It returned `.ignored` for Shift+Return and trusted the
field to do it; a vertical TextField on macOS has no newline gesture, so
the key reached AppKit as an ordinary `insertNewline:`, which ends
editing.

Measured rather than reasoned about, and the failure is worse than the
report: typing "a", Shift+Return, "b" left the binding holding "b" — no
line break, and the text already typed was GONE. A field with no key
handler at all behaved identically, so the interception was never the
cause.

`insertNewlineIgnoringFieldEditor(_:)` sent to the field editor — the
NSTextView that actually holds the text while a SwiftUI TextField is
focused — is AppKit's action for "a line break, do NOT end editing", what
Option+Return does in any NSTextField. Going through the editor rather
than appending to the binding is what lands the break at the CARET, so
someone fixing the middle of a sentence gets it where they are typing.

Rejected TextEditor, which does honour Shift+Return: it would have meant
re-creating the rounded border, the 2-5 line growth and the placeholder
by hand — restyling the one control on both cards to fix a keystroke.

Probe phase 13 asserts it end to end, through the composer's real field:
type "a", Shift+Return, "b", Enter, and read what was FILED, since the
draft is @State in the view and there is no honest way to read it from
outside. Rides the same opt-in flag as the other real-input legs.

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

Author: angusbezzina

DECISIONS.md

@@ -296,6 +296,30 @@ a mode the user has deliberately entered, so a press on the catcher is always me
 for the catcher. The alternative — making the panel unable to become key — would
 take the composer's typing with it.
 
+### Shift+Enter inserts the line break by hand (dogfooding)
+
+The card promises `⏎ save · ⇧⏎ newline` in its own header, and the second half was
+not true. It used to `return .ignored` for Shift+Return and trust the field. A
+vertical `TextField` on macOS has no newline gesture: the key arrives at AppKit as
+an ordinary `insertNewline:`, which ENDS EDITING. Measured — typing "a",
+Shift+Return, "b" left the binding holding **"b"**: no break, and the text already
+typed was gone. A field with no key handler at all behaved identically, so the
+interception was never the cause.
+
+`insertNewlineIgnoringFieldEditor(_:)` sent to the FIELD EDITOR — the `NSTextView`
+that actually holds the text while a SwiftUI `TextField` is focused — is AppKit's
+action for "a line break, do NOT end editing" (what Option+Return does in any
+`NSTextField`). Going through the editor rather than appending to the binding is
+what puts the break at the CARET, so someone fixing the middle of a sentence gets
+it where they are typing instead of stapled to the end.
+
+Rejected: swapping the field for a `TextEditor`, which does honour Shift+Return.
+It would have meant re-creating the rounded border, the 2–5 line growth and the
+placeholder by hand — restyling the one control on both cards to fix a keystroke.
+
+macOS-only by necessity; on iOS `.ignored` is correct, since UIKit's multiline
+field inserts the break itself and a touch keyboard has no Shift+Return.
+
 ### The live selection follows the content on scroll, not just the notes
 
 "The manually drawn frames disappear on scroll." They do not disappear, they

Sources/AnnotKit/Overlay/OverlayView.swift

@@ -1,4 +1,7 @@
 import SwiftUI
+#if os(macOS)
+import AppKit
+#endif
 
 /// The overlay's SwiftUI content, shared by the macOS and iOS hosts.
 ///
@@ -707,10 +710,10 @@ private struct AnnotationCard<Footer: View>: View {
                 .lineLimit(2 ... 5)
                 .frame(width: 260)
                 .focused($focused)
-                // Enter submits; Shift+Enter falls through to insert a newline in
-                // the multiline field.
+                // Enter submits; Shift+Enter inserts a line break (see
+                // ``insertLineBreak()`` for why that needs doing by hand).
                 .onKeyPress(keys: [.return]) { key in
-                    if key.modifiers.contains(.shift) { return .ignored }
+                    guard !key.modifiers.contains(.shift) else { return insertLineBreak() }
                     onSubmit()
                     return .handled
                 }
@@ -750,6 +753,38 @@ private struct AnnotationCard<Footer: View>: View {
         // acting again on the state that leaves behind.
     }
 
+    /// Insert a line break at the caret for Shift+Enter, and keep editing.
+    ///
+    /// This used to `return .ignored` and trust the field to do it. It does not —
+    /// and the failure is not merely inert, which is why it was worth measuring
+    /// rather than reasoning about. On a `TextField(axis: .vertical)`, typing "a",
+    /// Shift+Return, "b" leaves the binding holding **"b"**: no line break, and the
+    /// text that was already typed is GONE. A field with no key handler at all
+    /// behaves identically, so the interception was never the problem — a vertical
+    /// TextField on macOS simply has no newline gesture, and Shift+Return reaches
+    /// AppKit as an ordinary `insertNewline:`, which ends editing.
+    ///
+    /// `insertNewlineIgnoringFieldEditor(_:)` is the action AppKit provides for
+    /// exactly this — "a line break, do NOT end editing", what Option+Return does in
+    /// any `NSTextField` — sent to the FIELD EDITOR, the `NSTextView` that actually
+    /// holds the text while a SwiftUI `TextField` is focused. Going through it
+    /// rather than appending to the binding is what makes the break land at the
+    /// CARET: a user fixing the middle of a sentence gets it where they are typing,
+    /// not stapled to the end.
+    ///
+    /// macOS-only by necessity (`NSTextView`, `NSApp`). On iOS the key is
+    /// `.ignored`, which is the right answer there: UIKit's multiline field inserts
+    /// the break itself, and on a touch keyboard there is no Shift+Return to press.
+    private func insertLineBreak() -> KeyPress.Result {
+        #if os(macOS)
+        guard let editor = NSApp.keyWindow?.firstResponder as? NSTextView else { return .ignored }
+        editor.insertNewlineIgnoringFieldEditor(nil)
+        return .handled
+        #else
+        return .ignored
+        #endif
+    }
+
     /// Focus the text field, making the host panel key FIRST so the non-activating
     /// child window accepts keystrokes. A `@FocusState` set in the same layout pass
     /// that inserts the field can be dropped on first appearance (the classic

Sources/AnnotKitOverlayProbe/main.swift

@@ -3057,11 +3057,11 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
 
         guard realClicks else {
             print("      (end-to-end real-click legs skipped — set ANNOTKIT_PROBE_REALCLICK=1)")
-            controller.unmount(); host.window.orderOut(nil); return finish()
+            controller.unmount(); host.window.orderOut(nil); return phase13Keyboard()
         }
         guard AXIsProcessTrusted() else {
             check12(false, "posting real clicks needs Accessibility trust — the end-to-end legs CANNOT run")
-            controller.unmount(); host.window.orderOut(nil); return finish()
+            controller.unmount(); host.window.orderOut(nil); return phase13Keyboard()
         }
         host.window.setFrameOrigin(NSPoint(x: visibleFrame.minX + 140, y: visibleFrame.minY + 240))
         NSApp.activate(ignoringOtherApps: true)
@@ -3075,7 +3075,7 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
                              "ONE click on the catcher selects — the first press is not spent making the panel key")
                 controller.unmount()
                 host.window.orderOut(nil)
-                self.finish()
+                self.phase13Keyboard()
             }
         ])
     }
@@ -3128,6 +3128,92 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
         }
     }
 
+    // ---- Phase 13: the card's keyboard contract ----------------------------
+    // The card promises "⏎ save · ⇧⏎ newline" in its own header, and the second
+    // half of that was not true: Shift+Return inserted nothing AND discarded what
+    // had already been typed, because a vertical `TextField` has no newline gesture
+    // on macOS and the key reached AppKit as an ordinary `insertNewline:`.
+    //
+    // Asserted END TO END, through the composer's real text field, because that is
+    // the only place the claim is meaningful: the draft is `@State` in the view, so
+    // the only honest way to read it is to make the note and look at what was
+    // filed. Real key events, so it rides the same opt-in flag as the click legs.
+    var passKeyboard = true
+    func check13(_ c: Bool, _ m: String) {
+        print("      " + (c ? "ok   " : "FAIL ") + m)
+        passKeyboard = passKeyboard && c
+    }
+
+    var keyboardController: OverlayController?
+
+    func phase13Keyboard() {
+        print("\n--- Phase 13: the card's keyboard contract (⏎ saves, ⇧⏎ inserts a line break) ---")
+        guard realClicks else {
+            print("      (needs real key events — skipped; set ANNOTKIT_PROBE_REALCLICK=1)")
+            return finish()
+        }
+        guard AXIsProcessTrusted() else {
+            check13(false, "posting real key events needs Accessibility trust")
+            return finish()
+        }
+        let host = makeHostWindow(title: "AnnotKit Harness W13 (keyboard)")
+        host.window.setFrameOrigin(NSPoint(x: visibleFrame.minX + 160, y: visibleFrame.minY + 260))
+        NSApp.activate(ignoringOtherApps: true)
+        host.window.makeKeyAndOrderFront(nil)
+
+        let session = AnnotationSession(source: MacElementSource(), sink: NotesFileSink(path: "/dev/null"))
+        let controller = OverlayController(session: session)
+        controller.mount(on: host.window)
+        controller.start()
+        keyboardController = controller
+
+        runSteps([
+            {
+                // Open the composer on a real control. The card focuses itself and
+                // makes the panel key, which is what puts the field editor in the
+                // responder chain the keystrokes will reach.
+                NSApp.activate(ignoringOtherApps: true)
+                session.select(atAXPoint: axCenter(of: host.primary))
+                self.check13(session.selected != nil, "sanity: the composer is open on a real element")
+            },
+            {
+                // "a", Shift+Return, "b" — the sequence that used to leave "b".
+                self.typeKey(0)
+                self.typeKey(36, shift: true)
+                self.typeKey(11)
+            },
+            {
+                // Enter commits, which is the only way to read a draft that lives
+                // in the view's own @State.
+                self.typeKey(36)
+            },
+            {
+                let comment = session.pending.last?.comment
+                print("      filed comment = \(comment.map { "\"\($0.replacingOccurrences(of: "\n", with: "\\n"))\"" } ?? "nil")")
+                self.check13(session.pending.count == 1, "⏎ filed the note (got \(session.pending.count))")
+                self.check13(comment == "a\nb",
+                             "⇧⏎ inserted a LINE BREAK and kept what was already typed (the old behaviour filed \"b\")")
+                controller.unmount()
+                host.window.orderOut(nil)
+                self.finish()
+            }
+        ])
+    }
+
+    /// One real keystroke. Virtual key codes are hardware positions, so they are
+    /// layout-independent: 0 = "a", 11 = "b", 36 = Return.
+    func typeKey(_ code: CGKeyCode, shift: Bool = false) {
+        let source = CGEventSource(stateID: .hidSystemState)
+        guard let down = CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: true),
+              let up = CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: false) else { return }
+        if shift {
+            down.flags = .maskShift
+            up.flags = .maskShift
+        }
+        down.post(tap: .cghidEventTap)
+        up.post(tap: .cghidEventTap)
+    }
+
     func finish() {
         print("\n  issue-2 (per-control hit-test through the expanded overlay): \(passIssue2 ? "PASS" : "FAIL")")
         print("  issue-1 (retention / copy / export / pill persistence):       \(pass1 ? "PASS" : "FAIL")")
@@ -3142,8 +3228,9 @@ final class OverlayProbeDelegate: NSObject, NSApplicationDelegate {
         print("  Phase 10 (Escape closes the menu): \(passEscape ? "PASS" : "FAIL")")
         print("  Phase 11 (recallable marks: toolbar pass-through, pins inert in frame mode, hover recall): \(passMarks ? "PASS" : "FAIL")")
         print("  Phase 12 (the FIRST click on the overlay acts — no click tax): \(passFirstClick ? "PASS" : "FAIL")")
+        print("  Phase 13 (the card's keyboard contract: ⏎ saves, ⇧⏎ newlines): \(passKeyboard ? "PASS" : "FAIL")")
         print("\n=== AnnotKitOverlayProbe complete ===")
-        exit(pass1 && passIssue2 && passPins && passResize && passChrome && passCard && passSpec && passMarquee && passNav && passClamp && passEscape && passMarks && passFirstClick ? 0 : 1)
+        exit(pass1 && passIssue2 && passPins && passResize && passChrome && passCard && passSpec && passMarquee && passNav && passClamp && passEscape && passMarks && passFirstClick && passKeyboard ? 0 : 1)
     }
 
     func collectIDs(_ elements: [Element]) -> [String] {