agentix-cli 0.57.0 → 0.59.0

package/apps/mac-voice/Sources/AgentXVoice/Panel.swift

@@ -6,9 +6,24 @@ import AppKit
 /// focus out of whatever you were doing — the entire point of a voice
 /// assistant is that you don't stop working to use it. It floats above
 /// normal windows, joins every Space, and is deliberately small.
+///
+/// It is the one floating widget: a small live orb at its head (Orb.swift)
+/// in the answering agent's colour, the state or the words beside it, and
+/// a close button that shows on hover. Drag it anywhere; the place is
+/// remembered across launches.
 final class Panel: NSPanel {
+    static let size = NSSize(width: 284, height: 54)
+    /// The orb's diameter, and the square it draws in with room for its glow.
+    private static let orbDiameter: CGFloat = 36
+    private static let orbFrame: CGFloat = 52
+
     private let label = NSTextField(labelWithString: "")
-    private let orb = NSView()
+    let orb = PillOrb(diameter: Panel.orbDiameter, frameSize: Panel.orbFrame)
+    private let closeButton = NSButton()
+    /// Hidden by close, Esc or the menu until the next talk key.
+    private(set) var dismissed = false
+    /// Set while the app moves the pill, so only a drag is remembered.
+    private var placing = false
 
     /// Scrolls text too long for the pill instead of truncating it.
     ///
@@ -48,16 +63,24 @@ final class Panel: NSPanel {
     /// The target agent's name, shown while listening or answering.
     var agentName: () -> String = { "" }
 
+    /// The colour of the agent shown, for the orb.
+    var agentTint: () -> NSColor = { Brand.accent }
+
     /// Stay on screen when idle. Off: the pill shows only while active.
     var alwaysVisible = false
 
-    /// The orb overlay shows listening, thinking and speaking, so the
-    /// pill stays out of the way then; it still shows idle and errors.
-    var yieldsActiveStates = false
-
     /// Told of every state rendered, so the menu-bar icon can follow.
     var onRender: ((State) -> Void)?
 
+    /// Close button or Esc. The app stops speech and calls `dismiss()`.
+    var onDismiss: (() -> Void)?
+
+    /// The pill moved, by a drag or a reset. The answer card follows.
+    var onMove: (() -> Void)?
+
+    /// The last state rendered, to draw again after a dismiss or a move.
+    private var current = State.idle
+
     override func mouseUp(with event: NSEvent) {
         defer { pressedAt = nil }
         if let start = pressedAt {
@@ -112,11 +135,14 @@ final class Panel: NSPanel {
         /// is a running commentary and belongs in body type.
         var isMeta: Bool { if case .idle = self { return true }; return false }
 
-        /// Listening, thinking or speaking: what the orb shows.
-        var isActive: Bool {
+        /// What the orb does: follows the voice, turns a ring, or pulses.
+        /// Idle and errors hold it still.
+        var orbPhase: OrbModel.Phase {
             switch self {
-            case .idle, .error: return false
-            default: return true
+            case .idle, .error: return .idle
+            case .listening: return .listening
+            case .thinking, .working: return .thinking
+            case .speaking, .saying: return .speaking
             }
         }
     }
@@ -130,7 +156,7 @@ final class Panel: NSPanel {
     var onClick: (() -> Void)?
 
     init() {
-        super.init(contentRect: NSRect(x: 0, y: 0, width: 230, height: 54),
+        super.init(contentRect: NSRect(origin: .zero, size: Self.size),
                    styleMask: [.borderless, .nonactivatingPanel],
                    backing: .buffered, defer: false)
         isFloatingPanel = true
@@ -142,7 +168,7 @@ final class Panel: NSPanel {
         isMovableByWindowBackground = true
         hidesOnDeactivate = false
 
-        let blur = NSVisualEffectView(frame: NSRect(origin: .zero, size: NSSize(width: 230, height: 54)))
+        let blur = NSVisualEffectView(frame: NSRect(origin: .zero, size: Self.size))
         blur.material = .hudWindow
         blur.blendingMode = .behindWindow
         blur.state = .active
@@ -170,16 +196,19 @@ final class Panel: NSPanel {
         tint.autoresizingMask = [.width, .height]
         blur.addSubview(tint)
 
-        orb.wantsLayer = true
-        orb.layer?.cornerRadius = 4
-        orb.frame = NSRect(x: 18, y: 22, width: 8, height: 8)
+        // The orb, centred 28 points from the left edge; its square is
+        // larger than the orb so the glow is not cut off.
+        let h = Self.size.height
+        orb.frame = NSRect(x: 28 - Self.orbFrame / 2, y: (h - Self.orbFrame) / 2,
+                           width: Self.orbFrame, height: Self.orbFrame)
         blur.addSubview(orb)
 
-        // A clipping window the label slides behind.
-        let clipView = NSView(frame: NSRect(x: 38, y: 17, width: 180, height: 20))
+        // A clipping window the label slides behind. Clicks pass through
+        // it, so pressing on the words drags the pill too.
+        let clipView = PassThroughView(frame: NSRect(x: 54, y: 17, width: 196, height: 20))
         clipView.wantsLayer = true
         clipView.layer?.masksToBounds = true
-        label.frame = NSRect(x: 0, y: 0, width: 180, height: 20)
+        label.frame = NSRect(x: 0, y: 0, width: 196, height: 20)
         label.font = Brand.body(size: 12)
         label.lineBreakMode = .byClipping
         label.wantsLayer = true
@@ -187,15 +216,115 @@ final class Panel: NSPanel {
         blur.addSubview(clipView)
         clip = clipView
 
+        // Close, shown while the pointer is over the pill. Its space is
+        // kept when hidden, so the words never jump under it.
+        closeButton.frame = NSRect(x: Self.size.width - 28, y: (h - 18) / 2, width: 18, height: 18)
+        closeButton.isBordered = false
+        closeButton.bezelStyle = .regularSquare
+        closeButton.imagePosition = .imageOnly
+        closeButton.image = NSImage(systemSymbolName: "xmark.circle.fill", accessibilityDescription: "Hide")
+        closeButton.contentTintColor = .secondaryLabelColor
+        closeButton.toolTip = "Hide (Esc)"
+        closeButton.setAccessibilityLabel("Hide the pill")
+        closeButton.target = self
+        closeButton.action = #selector(closeClicked)
+        closeButton.isHidden = true
+        blur.addSubview(closeButton)
+        blur.addTrackingArea(NSTrackingArea(rect: .zero,
+                                            options: [.mouseEnteredAndExited, .activeAlways, .inVisibleRect],
+                                            owner: self, userInfo: nil))
+
         render(.idle)
-        positionBottomRight()
+        restorePosition()
+
+        NotificationCenter.default.addObserver(self, selector: #selector(moved),
+                                               name: NSWindow.didMoveNotification, object: self)
+        // A monitor unplugged or rearranged: bring the pill back on screen.
+        NotificationCenter.default.addObserver(self, selector: #selector(screensChanged),
+                                               name: NSApplication.didChangeScreenParametersNotification, object: nil)
+    }
+
+    // MARK: Place
+
+    /// Where it was left, kept on a screen that still exists; the
+    /// bottom-right corner the first time.
+    @MainActor
+    func restorePosition() {
+        let screens = NSScreen.screens.map(\.visibleFrame)
+        let fallback = (NSScreen.main ?? NSScreen.screens.first)?.visibleFrame ?? .zero
+        place(PillPlacement.clamp(saved: Config.pillOrigin, size: frame.size, screens: screens, fallback: fallback))
+    }
+
+    /// Back to the bottom-right corner, forgetting where it was dragged.
+    @MainActor
+    func resetPosition() {
+        Config.pillOrigin = nil
+        restorePosition()
+    }
+
+    @MainActor
+    private func place(_ origin: NSPoint) {
+        placing = true
+        setFrameOrigin(origin)
+        placing = false
+        onMove?()
+    }
+
+    /// Remember a drag. Moves the app makes itself are not saved, so a
+    /// reset or a clamp never overwrites where the user put it.
+    @objc private func moved() {
+        MainActor.assumeIsolated {
+            guard !placing else { return }
+            Config.pillOrigin = frame.origin
+            onMove?()
+        }
     }
 
-    /// Bottom-right, clear of the Dock — out of the way but visible.
-    private func positionBottomRight() {
-        guard let screen = NSScreen.main else { return }
-        let v = screen.visibleFrame
-        setFrameOrigin(NSPoint(x: v.maxX - frame.width - 24, y: v.minY + 24))
+    @objc private func screensChanged() {
+        MainActor.assumeIsolated { restorePosition() }
+    }
+
+    // MARK: Show and hide
+
+    /// Close, Esc or the menu: hidden until `summon()`, whatever is
+    /// rendered meanwhile.
+    @MainActor
+    func dismiss() {
+        dismissed = true
+        hide()
+    }
+
+    /// The talk key: allowed on screen again.
+    @MainActor
+    func summon() {
+        guard dismissed else { return }
+        dismissed = false
+        render(current)
+    }
+
+    @MainActor
+    private func show() {
+        orb.setOnScreen(true)
+        if !isVisible { orderFrontRegardless() }
+    }
+
+    @MainActor
+    private func hide() {
+        closeButton.isHidden = true
+        orb.setOnScreen(false)
+        if isVisible { orderOut(nil) }
+    }
+
+    @objc private func closeClicked() { onDismiss?() }
+
+    override func mouseEntered(with event: NSEvent) { closeButton.isHidden = false }
+    override func mouseExited(with event: NSEvent) { closeButton.isHidden = true }
+
+    /// Esc, once the pill has been clicked and so holds the keyboard.
+    override func cancelOperation(_ sender: Any?) { onDismiss?() }
+
+    override func keyDown(with event: NSEvent) {
+        if event.keyCode == 53 { onDismiss?() } else { super.keyDown(with: event) }
     }
 
     /// AppKit is not thread-safe. Marking this explicitly means a stray
@@ -203,25 +332,29 @@ final class Panel: NSPanel {
     /// corruption that traps somewhere unrelated an hour later.
     @MainActor
     func render(_ state: State) {
-        orb.layer?.backgroundColor = state.color.cgColor
-        // A soft halo on the dot while active: the same --nq-ring-accent
-        // idea, and the only ornament on the pill.
-        orb.layer?.shadowColor = state.color.cgColor
-        orb.layer?.shadowOpacity = state.isMeta ? 0 : 0.55
-        orb.layer?.shadowRadius = 5
-        orb.layer?.shadowOffset = .zero
+        current = state
+        // The agent's colour, except where the state is the message: an
+        // error, or notifications held.
+        let tint: NSColor
+        switch state {
+        case .error: tint = Brand.alert
+        case .idle where Hold.isOn: tint = Brand.warn
+        default: tint = agentTint()
+        }
+        orb.show(state.orbPhase, tint: tint)
 
         if state.isMeta {
             stopMarquee()
             label.attributedStringValue = Brand.metaString(state.text, color: state.color)
             label.frame.origin.x = 0
         } else {
-            label.textColor = state.color
+            // The orb carries the state now, so the words are plain text
+            // that reads in both themes. Errors keep their colour.
+            if case .error = state { label.textColor = state.color } else { label.textColor = .labelColor }
             setText(named(state))
         }
 
-        let yield = yieldsActiveStates && state.isActive
-        if (state.isMeta && !alwaysVisible) || yield { orderOut(nil) } else { orderFrontRegardless() }
+        if dismissed || (state.isMeta && !alwaysVisible) { hide() } else { show() }
         onRender?(state)
     }
 
@@ -283,7 +416,13 @@ final class Panel: NSPanel {
         marqueeText = ""
     }
 
-    // Borderless panels refuse key status unless told otherwise; without
-    // this the widget cannot show a caret or take any future text input.
+    // Borderless panels refuse key status unless told otherwise. The pill
+    // takes it only when clicked (showing it never does: that is
+    // orderFrontRegardless, not makeKey), so Esc can reach it then.
     override var canBecomeKey: Bool { true }
 }
+
+/// A view clicks go through, to the pill behind it.
+private final class PassThroughView: NSView {
+    override func hitTest(_ point: NSPoint) -> NSView? { nil }
+}

package/apps/mac-voice/Sources/AgentXVoice/Parakeet.swift

@@ -0,0 +1,264 @@
+import CoreML
+import Foundation
+
+/// NVIDIA Parakeet TDT 0.6B v3 on Core ML: on-device speech to text with
+/// no Python, from the model files ModelStore.parakeet fetches.
+///
+/// Four Core ML models, run in turn: the preprocessor turns 15 s of audio
+/// into a mel spectrogram, the encoder turns that into one vector per
+/// 80 ms, and the decoder (an LSTM over the words so far) and the joint
+/// network walk those vectors greedily. The joint picks a token and how
+/// many frames to skip (the "TDT" part), which is why it is fast.
+///
+/// v3 covers 25 European languages and detects which one on its own. It
+/// has NO Arabic; see the benchmark in docs/dashboard/voice.md.
+final class Parakeet: @unchecked Sendable {
+    enum ParakeetError: LocalizedError {
+        case notInstalled
+        case badOutput(String)
+        var errorDescription: String? {
+            switch self {
+            case .notInstalled: return "the Parakeet model is not downloaded yet"
+            case .badOutput(let what): return "Parakeet returned no \(what)"
+            }
+        }
+    }
+
+    static let sampleRate = 16_000
+    /// The Core ML export takes exactly 15 s.
+    static let window = 240_000
+    /// One encoder frame covers 80 ms.
+    static let samplesPerFrame = 1_280
+    static let blank = 8_192
+    static let durations = [0, 1, 2, 3, 4]
+    static let maxSymbolsPerFrame = 10
+
+    private let preprocessor: MLModel
+    private let encoder: MLModel
+    private let decoder: MLModel
+    private let joint: MLModel
+    private let vocabulary: [Int: String]
+
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var shared: Parakeet?
+
+    /// The loaded engine, kept for the life of the app: loading costs
+    /// seconds (Core ML prepares the encoder for the Neural Engine), a
+    /// transcription well under one.
+    static func loaded() throws -> Parakeet {
+        lock.lock(); defer { lock.unlock() }
+        if let shared { return shared }
+        let p = try Parakeet()
+        shared = p
+        return p
+    }
+
+    init() throws {
+        let store = ModelStore.parakeet
+        guard store.isInstalled else { throw ParakeetError.notInstalled }
+        func load(_ name: String, _ units: MLComputeUnits) throws -> MLModel {
+            let config = MLModelConfiguration()
+            config.computeUnits = units
+            return try MLModel(contentsOf: store.url(name), configuration: config)
+        }
+        // The same placement FluidAudio uses: the mel front end on the CPU,
+        // the rest wherever Core ML runs it best (the Neural Engine).
+        preprocessor = try load("Preprocessor.mlmodelc", .cpuOnly)
+        encoder = try load("Encoder.mlmodelc", .cpuAndNeuralEngine)
+        decoder = try load("Decoder.mlmodelc", .cpuAndNeuralEngine)
+        joint = try load("JointDecisionv3.mlmodelc", .cpuAndNeuralEngine)
+
+        let data = try Data(contentsOf: store.url("parakeet_vocab.json"))
+        let raw = try JSONSerialization.jsonObject(with: data) as? [String: String] ?? [:]
+        var vocab: [Int: String] = [:]
+        for (k, v) in raw { if let id = Int(k) { vocab[id] = v } }
+        vocabulary = vocab
+    }
+
+    /// A 16 kHz mono 16-bit WAV, as Recorder makes.
+    func transcribe(wav: Data) throws -> String {
+        try transcribe(samples: Self.samples(wav: wav))
+    }
+
+    func transcribe(samples: [Float]) throws -> String {
+        var tokens: [Int] = []
+        var state = try DecoderState(decoder: decoder)
+        for range in Self.windows(samples) {
+            tokens += try decode(Array(samples[range]), state: &state)
+        }
+        return Self.text(tokens, vocabulary: vocabulary)
+    }
+
+    // MARK: Pure helpers (tested)
+
+    /// Samples of a 16-bit PCM WAV as -1…1, found by its "data" chunk.
+    static func samples(wav: Data) -> [Float] {
+        let bytes = [UInt8](wav)
+        var offset = 12
+        while offset + 8 <= bytes.count {
+            let id = String(decoding: bytes[offset..<offset + 4], as: UTF8.self)
+            let size = Int(UInt32(bytes[offset + 4]) | UInt32(bytes[offset + 5]) << 8
+                | UInt32(bytes[offset + 6]) << 16 | UInt32(bytes[offset + 7]) << 24)
+            let body = offset + 8
+            if id == "data" {
+                let end = min(bytes.count, body + size)
+                var out = [Float]()
+                out.reserveCapacity((end - body) / 2)
+                var i = body
+                while i + 1 < end {
+                    out.append(Float(Int16(bitPattern: UInt16(bytes[i]) | UInt16(bytes[i + 1]) << 8)) / 32768)
+                    i += 2
+                }
+                return out
+            }
+            offset = body + size + (size & 1)
+        }
+        return []
+    }
+
+    /// Splits audio longer than the 15 s window, each cut at the quietest
+    /// 20 ms of the window's last 3 s, so a cut rarely lands in a word.
+    static func windows(_ samples: [Float], window: Int = Parakeet.window) -> [Range<Int>] {
+        var out: [Range<Int>] = []
+        var start = 0
+        let step = sampleRate / 50
+        while samples.count - start > window {
+            let searchFrom = start + window - 3 * sampleRate
+            var best = start + window, bestEnergy = Float.greatestFiniteMagnitude
+            var at = searchFrom
+            while at + step <= start + window {
+                var e: Float = 0
+                for i in at..<at + step { e += samples[i] * samples[i] }
+                if e < bestEnergy { bestEnergy = e; best = at + step / 2 }
+                at += step
+            }
+            out.append(start..<best)
+            start = best
+        }
+        if start < samples.count { out.append(start..<samples.count) }
+        return out
+    }
+
+    /// SentencePiece pieces to text: "▁" marks the start of a word.
+    static func text(_ tokens: [Int], vocabulary: [Int: String]) -> String {
+        var s = ""
+        for t in tokens {
+            guard let piece = vocabulary[t], !(piece.hasPrefix("<") && piece.hasSuffix(">")) else { continue }
+            s += piece.replacingOccurrences(of: "\u{2581}", with: " ")
+        }
+        return s.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    // MARK: Inference
+
+    private struct DecoderState {
+        var hidden: MLMultiArray
+        var cell: MLMultiArray
+        /// The decoder's output for the last token emitted (blank at first).
+        var output: MLMultiArray?
+        let target: MLMultiArray
+        let targetLength: MLMultiArray
+
+        init(decoder: MLModel) throws {
+            hidden = try MLMultiArray(shape: [2, 1, 640], dataType: .float32)
+            cell = try MLMultiArray(shape: [2, 1, 640], dataType: .float32)
+            for i in 0..<hidden.count { hidden[i] = 0; cell[i] = 0 }
+            target = try MLMultiArray(shape: [1, 1], dataType: .int32)
+            targetLength = try MLMultiArray(shape: [1], dataType: .int32)
+            targetLength[0] = 1
+        }
+    }
+
+    private func step(_ token: Int, _ state: inout DecoderState) throws {
+        state.target[0] = NSNumber(value: token)
+        let out = try decoder.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "targets": MLFeatureValue(multiArray: state.target),
+            "target_length": MLFeatureValue(multiArray: state.targetLength),
+            "h_in": MLFeatureValue(multiArray: state.hidden),
+            "c_in": MLFeatureValue(multiArray: state.cell),
+        ]))
+        guard let d = out.featureValue(for: "decoder")?.multiArrayValue,
+              let h = out.featureValue(for: "h_out")?.multiArrayValue,
+              let c = out.featureValue(for: "c_out")?.multiArrayValue else { throw ParakeetError.badOutput("decoder state") }
+        state.output = d; state.hidden = h; state.cell = c
+    }
+
+    /// One window: preprocessor, encoder, then greedy TDT decoding.
+    private func decode(_ chunk: [Float], state: inout DecoderState) throws -> [Int] {
+        guard chunk.count >= Self.samplesPerFrame else { return [] }
+        let audio = try MLMultiArray(shape: [1, NSNumber(value: Self.window)], dataType: .float32)
+        let ptr = audio.dataPointer.bindMemory(to: Float.self, capacity: Self.window)
+        ptr.initialize(repeating: 0, count: Self.window)
+        chunk.withUnsafeBufferPointer { src in ptr.update(from: src.baseAddress!, count: min(chunk.count, Self.window)) }
+        let length = try MLMultiArray(shape: [1], dataType: .int32)
+        length[0] = NSNumber(value: chunk.count)
+
+        let mel = try preprocessor.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "audio_signal": MLFeatureValue(multiArray: audio),
+            "audio_length": MLFeatureValue(multiArray: length),
+        ]))
+        guard let melArray = mel.featureValue(for: "mel")?.multiArrayValue,
+              let melLength = mel.featureValue(for: "mel_length")?.multiArrayValue else { throw ParakeetError.badOutput("mel") }
+        let enc = try encoder.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "mel": MLFeatureValue(multiArray: melArray),
+            "mel_length": MLFeatureValue(multiArray: melLength),
+        ]))
+        guard let frames = enc.featureValue(for: "encoder")?.multiArrayValue,
+              let encLength = enc.featureValue(for: "encoder_length")?.multiArrayValue else { throw ParakeetError.badOutput("encoder output") }
+
+        let hiddenSize = frames.shape[1].intValue
+        let available = frames.shape[2].intValue
+        let actual = (chunk.count + Self.samplesPerFrame - 1) / Self.samplesPerFrame
+        let count = min(encLength[0].intValue, available, actual)
+        let hStride = frames.strides[1].intValue, tStride = frames.strides[2].intValue
+
+        let encStep = try MLMultiArray(shape: [1, NSNumber(value: hiddenSize), 1], dataType: .float32)
+        let encStride = encStep.strides[1].intValue
+        let encDest = encStep.dataPointer.bindMemory(to: Float.self, capacity: encStep.count)
+        func load(frame t: Int) {
+            switch frames.dataType {
+            case .float16:
+                let src = frames.dataPointer.bindMemory(to: Float16.self, capacity: frames.count)
+                for h in 0..<hiddenSize { encDest[h * encStride] = Float(src[h * hStride + t * tStride]) }
+            default:
+                let src = frames.dataPointer.bindMemory(to: Float.self, capacity: frames.count)
+                for h in 0..<hiddenSize { encDest[h * encStride] = src[h * hStride + t * tStride] }
+            }
+        }
+
+        if state.output == nil { try step(Self.blank, &state) }
+        var tokens: [Int] = []
+        var t = 0
+        var symbolsHere = 0
+        var loaded = -1
+        while t < count {
+            if loaded != t { load(frame: t); loaded = t }
+            guard let decoderOut = state.output else { throw ParakeetError.badOutput("decoder output") }
+            let out = try joint.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+                "encoder_step": MLFeatureValue(multiArray: encStep),
+                "decoder_step": MLFeatureValue(multiArray: decoderOut),
+            ]))
+            guard let tokenArray = out.featureValue(for: "token_id")?.multiArrayValue,
+                  let durArray = out.featureValue(for: "duration")?.multiArrayValue else { throw ParakeetError.badOutput("joint decision") }
+            let token = tokenArray[0].intValue
+            let bin = durArray[0].intValue
+            let duration = Self.durations.indices.contains(bin) ? Self.durations[bin] : 1
+
+            if token == Self.blank {
+                t += max(duration, 1)
+                symbolsHere = 0
+                continue
+            }
+            tokens.append(token)
+            try step(token, &state)
+            if duration > 0 {
+                t += duration
+                symbolsHere = 0
+            } else {
+                symbolsHere += 1
+                if symbolsHere >= Self.maxSymbolsPerFrame { t += 1; symbolsHere = 0 }
+            }
+        }
+        return tokens
+    }
+}

package/apps/mac-voice/Sources/AgentXVoice/PillPlacement.swift

@@ -0,0 +1,70 @@
+import CoreGraphics
+
+/// Where the pill and its answer card go on screen, kept free of AppKit so
+/// the tests can check it without a window. Frames are in screen
+/// coordinates, origin bottom-left, as AppKit uses them.
+enum PillPlacement {
+    /// Distance from the screen's edges for the default corner.
+    static let inset: CGFloat = 24
+    /// Space between the pill and the answer card.
+    static let cardGap: CGFloat = 8
+
+    /// Bottom-right of `visible` (a screen's frame minus the menu bar and
+    /// Dock), clear of both.
+    static func defaultOrigin(size: CGSize, visible: CGRect) -> CGPoint {
+        CGPoint(x: visible.maxX - size.width - inset, y: visible.minY + inset)
+    }
+
+    /// A saved position made safe: the pill lands fully on the screen it
+    /// overlaps most. When it overlaps none (the monitor it was on has been
+    /// unplugged, or the saved value is nonsense) it goes back to the
+    /// default corner of `fallback`. Nil `saved`: the default corner.
+    static func clamp(saved: CGPoint?, size: CGSize, screens: [CGRect], fallback: CGRect) -> CGPoint {
+        guard let saved, saved.x.isFinite, saved.y.isFinite else {
+            return defaultOrigin(size: size, visible: fallback)
+        }
+        let frame = CGRect(origin: saved, size: size)
+        var best: CGRect?
+        var bestArea: CGFloat = 0
+        for screen in screens {
+            let overlap = screen.intersection(frame)
+            guard !overlap.isNull else { continue }
+            let area = overlap.width * overlap.height
+            if area > bestArea { bestArea = area; best = screen }
+        }
+        guard let screen = best, bestArea > 0 else {
+            return defaultOrigin(size: size, visible: fallback)
+        }
+        return inside(frame, screen).origin
+    }
+
+    /// Which side of the pill the answer card opens on, and where.
+    struct Card: Equatable {
+        let origin: CGPoint
+        /// True: above the pill. False: below it.
+        let above: Bool
+    }
+
+    /// Above the pill when there is at least as much room above it as
+    /// below, else below. Right edges line up with the pill's, and the
+    /// card is kept on the screen.
+    static func card(size: CGSize, pill: CGRect, visible: CGRect) -> Card {
+        let roomAbove = visible.maxY - pill.maxY
+        let roomBelow = pill.minY - visible.minY
+        let above = roomAbove >= roomBelow
+        let y = above ? pill.maxY + cardGap : pill.minY - cardGap - size.height
+        let frame = CGRect(x: pill.maxX - size.width, y: y, width: size.width, height: size.height)
+        return Card(origin: inside(frame, visible).origin, above: above)
+    }
+
+    /// `frame` moved the least distance that puts it inside `bounds`. A
+    /// frame larger than `bounds` keeps its top-left corner in view.
+    static func inside(_ frame: CGRect, _ bounds: CGRect) -> CGRect {
+        var f = frame
+        if f.maxX > bounds.maxX { f.origin.x = bounds.maxX - f.width }
+        if f.minX < bounds.minX { f.origin.x = bounds.minX }
+        if f.minY < bounds.minY { f.origin.y = bounds.minY }
+        if f.maxY > bounds.maxY { f.origin.y = bounds.maxY - f.height }
+        return f
+    }
+}