agentix-cli 0.98.0 → 0.99.0

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

@@ -4,7 +4,8 @@ import AppKit
 /// agent's palette, with two eyes, no mouth and no legs. It hovers above
 /// the bottom edge of the screen, or where it was dragged to (#502),
 /// shows what the assistant is doing, and gets out of the pointer's way.
-/// Chosen with `voice.look`; the orb stays the default.
+/// The answering agent can send it to something on screen, which it
+/// marks (#482). Chosen with `voice.look`; the orb stays the default.
 ///
 /// It reacts and never interrupts: its window takes no keys, no clicks
 /// but a drag of its body with ⌘ held, and never comes forward by itself.
@@ -44,6 +45,12 @@ final class CharacterHost {
     /// bubble is, or nil while it is hidden. Set by the app.
     var bubble: ((NSPoint, NSRect) -> NSRect?)?
     private var bubbleFrame: NSRect?
+    /// What stands on its line (#539): the sides of the windows there,
+    /// read once a second while it may stroll and play mode is ticked.
+    private var edges: [Double] = []
+    private var edgesRead = 0.0
+    /// Its bubble holds something to use: no play with the pointer then.
+    var bubbleShows: (() -> Bool)?
 
     /// Where it was dragged to: the point under it. Nil: its corner.
     private var place = Config.characterPlace
@@ -58,10 +65,14 @@ final class CharacterHost {
     /// Carried by the pointer: where the pointer took hold, and where it
     /// stood then, which is not where it rests once it has stepped aside.
     private var carried: (from: NSPoint, rest: CGPoint)?
+    /// What the answering agent sent it to show (#482), and its mark.
+    private let guide = CharacterGuide()
     /// A still picture: Reduce Motion, or "Animated orb" off.
     private var still: Bool { !animated || reduceMotion }
     /// The look is the character: whether it is on screen. Nil with the orb.
     var onScreen: Bool? { shown ? !hidden : nil }
+    /// Told when it comes on screen or leaves it: shown or hidden, or the look changed.
+    var onScreenChanged: (() -> Void)?
 
     init() {
         window = NSPanel(contentRect: NSRect(origin: .zero, size: Self.size),
@@ -95,6 +106,7 @@ final class CharacterHost {
         shown = on
         if on { sim = CharacterSim(unit: Double(Self.diameter) / 100) }
         run()
+        onScreenChanged?()
     }
 
     /// Hide it, as its bubble is hidden: gone until it is asked back.
@@ -102,6 +114,7 @@ final class CharacterHost {
         guard hidden != on else { return }
         hidden = on
         run()
+        onScreenChanged?()
     }
 
     /// "Reset position" in the menu: back to its corner, forgetting where
@@ -130,6 +143,16 @@ final class CharacterHost {
         redraw()
     }
 
+    /// Go beside `rect` and mark it, or with nil go back to where it rests.
+    func guide(to rect: NSRect?, mark kind: GuideMath.Mark = .none) {
+        if shown, !hidden, carried == nil, let rect {
+            guide.show(rect, kind, color: view.stops[2], animated: !still)
+        } else {
+            guide.end()
+        }
+        redraw()
+    }
+
     /// Standing still, it is drawn again when something changes: its
     /// state, or its bubble showing or hiding.
     func redraw() {
@@ -140,7 +163,7 @@ final class CharacterHost {
     private func run() {
         timer?.invalidate()
         timer = nil
-        guard shown, !hidden else { carried = nil; window.orderOut(nil); return }
+        guard shown, !hidden else { carried = nil; guide(to: nil); window.orderOut(nil); return }
         tick()
         window.orderFrontRegardless()
         // Still, it only watches for the hand that moves it.
@@ -166,7 +189,7 @@ final class CharacterHost {
         switch phase {
         case .began:
             let mouse = pointerSource()
-            if body.contains(mouse) { carried = (mouse, CGPoint(x: body.midX, y: rest.y)) }
+            if body.contains(mouse) { guide.end(glide: false); carried = (mouse, CGPoint(x: body.midX, y: rest.y)) }
         case .moved:
             if carried != nil { tick() }
         case .ended:
@@ -194,11 +217,14 @@ final class CharacterHost {
         var wanted = place
         if let carried {
             wanted = CGPoint(x: carried.rest.x + mouse.x - carried.from.x, y: carried.rest.y + mouse.y - carried.from.y)
+        } else if let beside = guide.stand(screens: screens, body: Self.diameter, tall: Self.head) {
+            wanted = beside
         }
         let spot = PillPlacement.character(saved: wanted, room: Self.head + PillPlacement.tail + Panel.size.height,
                                            screens: screens.map(\.visibleFrame), fallback: first.visibleFrame)
         let visible = spot.visible
-        rest = spot.place
+        let now = ProcessInfo.processInfo.systemUptime
+        rest = CGPoint(x: spot.place.x, y: guide.height(from: rest.y, toward: spot.place.y, now: now, still: still))
         let home = Double(rest.x)
         if carried != nil { sim.carry(to: home) }
 
@@ -212,15 +238,23 @@ final class CharacterHost {
                 level = 0
             }
             let near = screens.first { $0.visibleFrame == visible }?.frame.contains(mouse) ?? false
-            let pointer = near ? (x: Double(mouse.x), y: Double(mouse.y - rest.y)) : nil
+            // Showing something, it does not step aside for the pointer.
+            let pointer = near && guide.showing == nil ? (x: Double(mouse.x), y: Double(mouse.y - rest.y)) : nil
             // The gap its tail fills counts as the bubble, so a pointer a
             // little under a button does not send both away. With ⌘ held
             // it waits too, to be taken hold of.
             let held = carried != nil
                 || (bubbleFrame?.insetBy(dx: 0, dy: -PillPlacement.tail).contains(mouse) ?? false)
                 || (NSEvent.modifierFlags.contains(.command) && window.frame.contains(mouse))
-            frame = sim.step(to: ProcessInfo.processInfo.systemUptime,
-                             CharacterSim.Input(activity: activity, level: level, pointer: pointer, held: held, strolls: strolls,
+            if now - edgesRead >= 1 {
+                edgesRead = now
+                // The window list counts down from the top of the main screen.
+                let top = first.frame.maxY - rest.y
+                edges = strolls && Config.playMode ? Meets.edges(of: Meets.windows(), band: (top - Self.head)...top) : []
+            }
+            frame = sim.step(to: now,
+                             CharacterSim.Input(activity: activity, level: level, pointer: pointer, held: held, sent: guide.showing != nil, strolls: strolls,
+                                                edges: edges, shows: bubbleShows?() ?? false, plays: Config.playMode, down: NSEvent.pressedMouseButtons & 1 != 0,
                                                 home: home, range: Double(spot.ends.lowerBound)...Double(spot.ends.upperBound)))
         }
         let origin = NSPoint(x: (CGFloat(frame.x) - Self.size.width / 2).rounded(), y: (rest.y - Self.ground).rounded())
@@ -235,59 +269,3 @@ final class CharacterHost {
         aim()
     }
 }
-
-/// The character's drawing surface. Flipped, so the drawing's y grows
-/// downwards as in the pose sheet it was ported from.
-final class CharacterView: NSView {
-    var shown = CharacterSim.Frame()
-    var stops = CharacterDraw.stops(tint: Brand.accent, colors: nil)
-    var unit: CGFloat = 0.56
-    /// Under the character, in this view; and the view's left edge on screen.
-    var edge = CGPoint.zero
-    var origin: CGFloat = 0
-    /// Its speech bubble in this window, origin bottom-left; nil while hidden.
-    var bubble: NSRect?
-
-    /// A drag of its body. Its window takes the mouse for nothing else.
-    enum Drag { case began, moved, ended }
-    var onDrag: ((Drag) -> Void)?
-
-    override var isFlipped: Bool { true }
-    override func acceptsFirstMouse(for event: NSEvent?) -> Bool { true }
-    override func mouseDown(with event: NSEvent) { onDrag?(.began) }
-    override func mouseDragged(with event: NSEvent) { onDrag?(.moved) }
-    override func mouseUp(with event: NSEvent) { onDrag?(.ended) }
-
-    override func draw(_ dirtyRect: NSRect) {
-        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
-        // The body is drawn where the window is, which follows the frame
-        // to the nearest point; the rest of the way is drawn here.
-        let at = CGPoint(x: CGFloat(shown.x) - origin, y: edge.y)
-        CharacterDraw.draw(shown, in: ctx, edge: at, origin: origin, unit: unit, stops: stops)
-        if let bubble { drawTail(in: ctx, from: bubble) }
-    }
-
-    /// The bubble's tail: a small point from its bottom edge down to the
-    /// character, in the bubble's own colours.
-    private func drawTail(in ctx: CGContext, from bubble: NSRect) {
-        let half: CGFloat = 7, corner = Brand.Radius.lg + half
-        let x = min(max(bounds.midX, bubble.minX + corner), bubble.maxX - corner)
-        // One point up into the bubble, so no gap shows between the two.
-        let top = bounds.height - bubble.minY - 1
-        let tip = CGPoint(x: x, y: top + 1 + PillPlacement.tail)
-        effectiveAppearance.performAsCurrentDrawingAppearance {
-            ctx.move(to: CGPoint(x: x - half, y: top))
-            ctx.addLine(to: tip)
-            ctx.addLine(to: CGPoint(x: x + half, y: top))
-            ctx.closePath()
-            ctx.setFillColor(NSColor.windowBackgroundColor.withAlphaComponent(0.92).cgColor)
-            ctx.fillPath()
-            ctx.move(to: CGPoint(x: x - half, y: top + 1))
-            ctx.addLine(to: tip)
-            ctx.addLine(to: CGPoint(x: x + half, y: top + 1))
-            ctx.setStrokeColor(NSColor.separatorColor.cgColor)
-            ctx.setLineWidth(1)
-            ctx.strokePath()
-        }
-    }
-}

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

@@ -142,4 +142,13 @@ enum CharacterMath {
         if range.contains(there) { return there }
         return min(max(pointer - side * clear, range.lowerBound), range.upperBound)
     }
+
+    /// Walking from `from` to `to`: the nearest of `edges` in its way, and
+    /// where it stops, `gap` short of it and never back from where it is.
+    static func stop(from: Double, to: Double, edges: [Double], gap: Double) -> (edge: Double, at: Double)? {
+        let way: Double = to >= from ? 1 : -1
+        let ahead = edges.filter { way * ($0 - from) > 0 && way * ($0 - to) < gap }
+        guard let edge = ahead.min(by: { abs($0 - from) < abs($1 - from) }) else { return nil }
+        return (edge, from + way * max(way * (edge - from) - gap, 0))
+    }
 }

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

@@ -10,48 +10,6 @@ import Foundation
 struct CharacterSim {
     typealias M = CharacterMath
 
-    struct Input {
-        var activity = M.Activity.idle
-        /// 0…1: the microphone while listening.
-        var level = 0.0
-        /// The pointer: along the edge, and its height above it. Nil when
-        /// it is on another screen.
-        var pointer: (x: Double, y: Double)?
-        /// The pointer is on its speech bubble: it stays where it is, so
-        /// the bubble is not pulled from under the pointer.
-        var held = false
-        /// `voice.stroll`: with nothing to do, it takes a slow stroll
-        /// beside where it rests now and then (#482).
-        var strolls = false
-        /// Where it rests, and how far it may go.
-        var home = 0.0
-        var range: ClosedRange<Double> = 0...0
-    }
-
-    /// A trail dot or a star, where and how it is drawn this frame.
-    struct Mark: Equatable {
-        /// Along the edge and above it, in points.
-        var x, y: Double
-        /// Radius in drawing units, opacity, turn in degrees, and which
-        /// palette stop colours it.
-        var r, alpha, turn: Double
-        var shade: Int
-    }
-
-    struct Frame {
-        var pose = M.Pose()
-        var x = 0.0
-        /// -1 turned left, 0 facing you, 1 turned right.
-        var face = 0.0
-        var level = 0.0
-        /// 0…1: the rise and fall of its own voice while speaking.
-        var voice = 0.0
-        /// Seconds since it appeared, for the marks' own loops.
-        var t = 0.0
-        var dots: [Mark] = []
-        var stars: [Mark] = []
-    }
-
     /// Points per drawing unit: a body 56 points across.
     let unit: Double
     /// Idle this long, it dozes.
@@ -82,6 +40,11 @@ struct CharacterSim {
     private var strollTo = 0.0, strolled = 0.0
     private var strollNext: Double?
     private var strolls = 0
+    /// What stopped the stroll it is on.
+    private var met: Double?
+    /// Its games with the pointer, and the crouch and hop they give it.
+    private(set) var play = PointerPlay()
+    private var crouch = 0.0, hop = 0.0
     private var face = 0.0, lean = 0.0
     private var glance = (x: 0.0, y: 0.0)
 
@@ -113,9 +76,28 @@ struct CharacterSim {
         // The pointer comes close: out of its way. Left alone: back home,
         // unless the pointer is resting there.
         let near = input.pointer.map { abs($0.x - x) < reach && abs($0.y) < tall } ?? false
-        if input.held {
+        // Idle with play mode on, a game with the pointer comes first.
+        // Sent to show something, it does not play.
+        var game = PointerPlay.Out()
+        if input.plays && !input.sent && !input.held && !input.shows && mood == .idle && input.activity == .idle {
+            game = play.step(now, dt, x: x, pointer: input.pointer, down: input.down, range: input.range)
+        } else {
+            play.stop(now, down: input.down)
+        }
+        if input.sent {
+            target = min(max(input.home, input.range.lowerBound), input.range.upperBound)
+            restSince = now
+            // The stroll is over: sent home again, it rests there.
+            strolled = 0; strollTo = 0; strollNext = nil
+        } else if input.held {
             target = x
             awayUntil = max(awayUntil, now + Self.awayFor)
+        } else if let to = game.target {
+            target = to
+            awayUntil = now + 1
+            restSince = now
+            // A game ends a stroll, as stepping aside does.
+            strolled = 0; strollTo = 0; strollNext = nil
         } else if near {
             target = M.aside(x: x, pointer: input.pointer!.x, clear: Self.clear, range: input.range)
             awayUntil = now + Self.awayFor
@@ -158,8 +140,19 @@ struct CharacterSim {
         let moving = abs(speed) > 40
         let way: Double = speed >= 0 ? 1 : -1
         func toward(_ value: inout Double, _ to: Double, _ rate: Double) { value += (to - value) * (1 - exp(-dt * rate)) }
-        toward(&face, min(max(speed / 200, -1), 1), 10)
+        // Stopped at something in its way: it turns to look at it.
+        let stopped = strollTo != 0 && abs(strollTo - strolled) < 0.5 ? met : nil
+        let turned = stopped.map { $0 > x ? 0.7 : -0.7 } ?? 0
+        toward(&face, min(max(speed / 200 + turned, -1), 1), 10)
         toward(&lean, min(max(speed / 480, -1), 1) * 13, 8)
+        // A game's crouch and hop are followed, not taken at once, so a
+        // game cut short by work does not snap.
+        toward(&crouch, game.crouch, 20)
+        toward(&hop, game.hop, 20)
+        pose.sx *= 1 + 0.14 * crouch
+        pose.sy *= 1 - 0.22 * crouch
+        pose.lift += hop - 8 * crouch
+        if game.caught { burst(now, pose) }
 
         // It leaves dots behind while it moves, and stars when it has
         // stepped aside or understood.
@@ -186,6 +179,7 @@ struct CharacterSim {
             let pull = min(far / 60, 1) * 4.5
             look = (dx / far * pull, dy / far * pull)
         }
+        if stopped != nil { look = (turned * 5, -2) }
         toward(&glance.x, look.x + face * 2, 9)
         toward(&glance.y, look.y, 9)
 
@@ -229,12 +223,20 @@ struct CharacterSim {
                 var way: Double = M.rnd(strolls, 2) < 0.5 ? -1 : 1
                 if (way > 0 ? room.right : room.left) < far { way = -way }
                 strollTo = way * min(far, way > 0 ? room.right : room.left)
+                met = nil
                 strollNext = now + abs(strollTo) / Self.strollSpeed + 5 + 6 * M.rnd(strolls, 4)
             } else {
                 strollTo = 0
                 strollNext = nil
             }
         }
+        // Something in its way: it goes no further than just short of it.
+        // Only on the way out: nothing keeps it from going home.
+        if strollTo != 0, strollTo != strolled, let stop = M.stop(from: input.home + strolled, to: input.home + strollTo,
+                                            edges: input.edges, gap: 50 * unit + 10) {
+            strollTo = stop.at - input.home
+            met = stop.edge
+        }
         let pace = Self.strollSpeed * dt
         strolled += min(max(strollTo - strolled, -pace), pace)
     }

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

@@ -0,0 +1,59 @@
+import Foundation
+
+/// What the character sim is given and returns each frame (CharacterSim.swift).
+extension CharacterSim {
+    struct Input {
+        var activity = M.Activity.idle
+        /// 0…1: the microphone while listening.
+        var level = 0.0
+        /// The pointer: along the edge, and its height above it. Nil when
+        /// it is on another screen.
+        var pointer: (x: Double, y: Double)?
+        /// The pointer is on its speech bubble: it stays where it is, so
+        /// the bubble is not pulled from under the pointer.
+        var held = false
+        /// The answering agent sent it to show something (#482): it goes
+        /// to `home` at once, awake, whatever the pointer did before.
+        var sent = false
+        /// `voice.stroll`: with nothing to do, it takes a slow stroll
+        /// beside where it rests now and then (#482).
+        var strolls = false
+        /// What stands on its line, along the edge: the sides of the
+        /// windows there (#539). On a stroll it stops short of the first.
+        var edges: [Double] = []
+        /// Its bubble holds something to use (an answer, an error, the
+        /// call buttons): no game, so the bubble waits for the hand.
+        var shows = false
+        /// "Play mode" is ticked: idle, it plays with the pointer (#505).
+        var plays = false
+        /// The mouse button is down.
+        var down = false
+        /// Where it rests, and how far it may go.
+        var home = 0.0
+        var range: ClosedRange<Double> = 0...0
+    }
+
+    /// A trail dot or a star, where and how it is drawn this frame.
+    struct Mark: Equatable {
+        /// Along the edge and above it, in points.
+        var x, y: Double
+        /// Radius in drawing units, opacity, turn in degrees, and which
+        /// palette stop colours it.
+        var r, alpha, turn: Double
+        var shade: Int
+    }
+
+    struct Frame {
+        var pose = M.Pose()
+        var x = 0.0
+        /// -1 turned left, 0 facing you, 1 turned right.
+        var face = 0.0
+        var level = 0.0
+        /// 0…1: the rise and fall of its own voice while speaking.
+        var voice = 0.0
+        /// Seconds since it appeared, for the marks' own loops.
+        var t = 0.0
+        var dots: [Mark] = []
+        var stars: [Mark] = []
+    }
+}

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

@@ -0,0 +1,57 @@
+import AppKit
+
+/// The character's drawing surface. Flipped, so the drawing's y grows
+/// downwards as in the pose sheet it was ported from.
+final class CharacterView: NSView {
+    var shown = CharacterSim.Frame()
+    var stops = CharacterDraw.stops(tint: Brand.accent, colors: nil)
+    var unit: CGFloat = 0.56
+    /// Under the character, in this view; and the view's left edge on screen.
+    var edge = CGPoint.zero
+    var origin: CGFloat = 0
+    /// Its speech bubble in this window, origin bottom-left; nil while hidden.
+    var bubble: NSRect?
+
+    /// A drag of its body. Its window takes the mouse for nothing else.
+    enum Drag { case began, moved, ended }
+    var onDrag: ((Drag) -> Void)?
+
+    override var isFlipped: Bool { true }
+    override func acceptsFirstMouse(for event: NSEvent?) -> Bool { true }
+    override func mouseDown(with event: NSEvent) { onDrag?(.began) }
+    override func mouseDragged(with event: NSEvent) { onDrag?(.moved) }
+    override func mouseUp(with event: NSEvent) { onDrag?(.ended) }
+
+    override func draw(_ dirtyRect: NSRect) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+        // The body is drawn where the window is, which follows the frame
+        // to the nearest point; the rest of the way is drawn here.
+        let at = CGPoint(x: CGFloat(shown.x) - origin, y: edge.y)
+        CharacterDraw.draw(shown, in: ctx, edge: at, origin: origin, unit: unit, stops: stops)
+        if let bubble { drawTail(in: ctx, from: bubble) }
+    }
+
+    /// The bubble's tail: a small point from its bottom edge down to the
+    /// character, in the bubble's own colours.
+    private func drawTail(in ctx: CGContext, from bubble: NSRect) {
+        let half: CGFloat = 7, corner = Brand.Radius.lg + half
+        let x = min(max(bounds.midX, bubble.minX + corner), bubble.maxX - corner)
+        // One point up into the bubble, so no gap shows between the two.
+        let top = bounds.height - bubble.minY - 1
+        let tip = CGPoint(x: x, y: top + 1 + PillPlacement.tail)
+        effectiveAppearance.performAsCurrentDrawingAppearance {
+            ctx.move(to: CGPoint(x: x - half, y: top))
+            ctx.addLine(to: tip)
+            ctx.addLine(to: CGPoint(x: x + half, y: top))
+            ctx.closePath()
+            ctx.setFillColor(NSColor.windowBackgroundColor.withAlphaComponent(0.92).cgColor)
+            ctx.fillPath()
+            ctx.move(to: CGPoint(x: x - half, y: top + 1))
+            ctx.addLine(to: tip)
+            ctx.addLine(to: CGPoint(x: x + half, y: top + 1))
+            ctx.setStrokeColor(NSColor.separatorColor.cgColor)
+            ctx.setLineWidth(1)
+            ctx.strokePath()
+        }
+    }
+}

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

@@ -36,7 +36,8 @@ enum Config {
     }
 
     /// "Play mode" in the menu (#505): the character may play on a frozen
-    /// picture of the screen when asked. Off by default.
+    /// picture of the screen when asked, and plays with the pointer while
+    /// idle. Off by default.
     static var playMode: Bool {
         get { UserDefaults.standard.bool(forKey: "playMode") }
         set { UserDefaults.standard.set(newValue, forKey: "playMode") }

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

@@ -0,0 +1,185 @@
+import AppKit
+
+/// Guiding (#482): the daemon's /voice/guide route, the wait on it, and
+/// the mark the character leaves on what it shows. Where it stands is in
+/// GuideMath.swift; Character.swift moves it there.
+enum GuideClient {
+    struct Command: Decodable {
+        struct Rect: Decodable { let x, y, width, height: Double }
+        let seq: Int
+        /// Nil: back to where it rests.
+        let rect: Rect?
+        let mark: String
+    }
+
+    /// GET /voice/guide: the command after `seq`, as soon as there is
+    /// one; the current one after 25 s; nil when the daemon cannot be
+    /// reached or is too old to know the route.
+    static func next(after seq: Int) async -> Command? {
+        guard let url = URL(string: "\(Config.daemonURL)/voice/guide?after=\(seq)") else { return nil }
+        var req = URLRequest(url: url)
+        req.timeoutInterval = 35
+        guard let (data, response) = try? await URLSession.shared.data(for: req),
+              (response as? HTTPURLResponse)?.statusCode == 200 else { return nil }
+        return try? JSONDecoder().decode(Command.self, from: data)
+    }
+}
+
+/// Waits on the daemon while the character is on screen. The wait is
+/// also how the daemon knows there is a character to send.
+@MainActor
+final class GuideWatcher {
+    private var seq = 0
+    private var away = false
+    private var task: Task<Void, Never>?
+    /// The character is on screen.
+    var wanted: (() -> Bool)?
+    /// Show this, in AppKit coordinates, or go home.
+    var onCommand: ((NSRect?, GuideMath.Mark) -> Void)?
+
+    /// (Re)start the wait. Called again when the character comes on screen
+    /// or leaves it, so a wait already open is ended: cancelling it closes
+    /// its socket, and the daemon stops counting a character as there.
+    func start() {
+        task?.cancel()
+        task = Task { [weak self] in
+            while !Task.isCancelled {
+                guard let self else { return }
+                await self.turn()
+            }
+        }
+    }
+
+    private func turn() async {
+        guard wanted?() == true, let command = await GuideClient.next(after: seq) else {
+            // Hidden, or the daemon is gone: nothing is left on screen.
+            if away { away = false; onCommand?(nil, .none) }
+            try? await Task.sleep(nanoseconds: 2_000_000_000)
+            return
+        }
+        guard command.seq != seq else { return }
+        seq = command.seq
+        let rect = command.rect.map {
+            GuideMath.toAppKit(CGRect(x: $0.x, y: $0.y, width: $0.width, height: $0.height),
+                               primaryHeight: NSScreen.screens.first?.frame.maxY ?? 0)
+        }
+        away = rect != nil
+        Log.info("guide: \(rect.map { "to \(Int($0.minX)),\(Int($0.minY)) \(Int($0.width))x\(Int($0.height)) \(command.mark)" } ?? "home")")
+        onCommand?(rect, GuideMath.Mark(rawValue: command.mark) ?? .box)
+    }
+}
+
+/// What the character was sent to show (#482): it stands beside it until
+/// it is sent home, taken hold of or hidden; its mark; its glide there and back.
+@MainActor
+final class CharacterGuide {
+    private(set) var showing: NSRect?
+    private let mark = GuideMark()
+    /// On its way up or down, to what it shows or back; and the last frame.
+    private var gliding = false
+    private var ticked = 0.0
+
+    func show(_ rect: NSRect, _ kind: GuideMath.Mark, color: NSColor, animated: Bool) {
+        showing = rect
+        gliding = true
+        mark.show(kind, around: rect, color: color, animated: animated)
+    }
+
+    /// Back to where it rests, gliding there unless it was taken hold of.
+    func end(glide: Bool = true) {
+        gliding = glide && showing != nil
+        showing = nil
+        mark.hide()
+    }
+
+    /// Where it stands beside what it shows, on that thing's screen.
+    func stand(screens: [NSScreen], body: CGFloat, tall: CGFloat) -> CGPoint? {
+        guard let showing, let first = screens.first else { return nil }
+        let middle = CGPoint(x: showing.midX, y: showing.midY)
+        return GuideMath.stand(beside: showing, in: (screens.first { $0.frame.contains(middle) } ?? first).visibleFrame,
+                               body: body, tall: tall, inset: PillPlacement.characterInset)
+    }
+
+    /// Its height this frame: sent somewhere or back, it glides up or down
+    /// to `y`; otherwise it is there at once.
+    func height(from: CGFloat, toward y: CGFloat, now: Double, still: Bool) -> CGFloat {
+        let h = gliding && !still ? GuideMath.glide(from, toward: y, dt: now - ticked) : y
+        gliding = h != y
+        ticked = now
+        return h
+    }
+}
+
+/// The mark on what the character shows: drawn on its own click-through
+/// window over the page, which is never touched.
+@MainActor
+final class GuideMark {
+    /// Room around the outline for the stroke.
+    private static let margin: CGFloat = 6
+    private let window: NSPanel
+    private let shape = CAShapeLayer()
+
+    init() {
+        window = NSPanel(contentRect: .zero, styleMask: [.borderless, .nonactivatingPanel], backing: .buffered, defer: false)
+        window.level = .floating
+        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        window.isOpaque = false
+        window.backgroundColor = .clear
+        window.hasShadow = false
+        window.hidesOnDeactivate = false
+        window.ignoresMouseEvents = true
+        let view = NSView()
+        view.wantsLayer = true
+        view.layer?.addSublayer(shape)
+        window.contentView = view
+        shape.lineWidth = 3
+        shape.lineCap = .round
+        shape.lineJoin = .round
+    }
+
+    /// Draw `mark` around `rect`. Animated, it is drawn on once the
+    /// character has had time to get there.
+    func show(_ mark: GuideMath.Mark, around rect: NSRect, color: NSColor, animated: Bool) {
+        // Kept to the screen it is on, whatever size it was sent.
+        let screen = NSScreen.screens.first { $0.frame.intersects(rect) }?.frame ?? .null
+        let outline = GuideMath.outline(mark, around: rect).intersection(screen)
+        guard !outline.isNull, !outline.isEmpty else { return hide() }
+        let frame = outline.insetBy(dx: -Self.margin, dy: -Self.margin)
+        window.setFrame(frame, display: false)
+        let inner = CGRect(x: Self.margin, y: Self.margin, width: outline.width, height: outline.height)
+        let path = CGMutablePath()
+        switch mark {
+        case .circle: path.addEllipse(in: inner)
+        case .underline: path.move(to: inner.origin); path.addLine(to: CGPoint(x: inner.maxX, y: inner.minY))
+        default: path.addRoundedRect(in: inner, cornerWidth: min(6, inner.width / 2), cornerHeight: min(6, inner.height / 2))
+        }
+        shape.frame = CGRect(origin: .zero, size: frame.size)
+        shape.path = path
+        shape.strokeColor = color.cgColor
+        shape.fillColor = mark == .box ? color.withAlphaComponent(0.12).cgColor : nil
+        shape.removeAllAnimations()
+        if animated {
+            let draw = CABasicAnimation(keyPath: "strokeEnd")
+            draw.fromValue = 0
+            draw.toValue = 1
+            draw.beginTime = CACurrentMediaTime() + 0.35
+            draw.duration = 0.45
+            draw.fillMode = .backwards
+            draw.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+            shape.add(draw, forKey: "draw")
+            let appear = CABasicAnimation(keyPath: "opacity")
+            appear.fromValue = 0
+            appear.toValue = 1
+            appear.beginTime = draw.beginTime
+            appear.duration = 0.15
+            appear.fillMode = .backwards
+            shape.add(appear, forKey: "appear")
+        }
+        window.orderFrontRegardless()
+    }
+
+    func hide() {
+        shape.removeAllAnimations()
+        window.orderOut(nil)
+    }
+}