agentix-cli 0.97.0 → 0.99.0

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

@@ -0,0 +1,49 @@
+import CoreGraphics
+import Foundation
+
+/// Guiding (#482): the answering agent sends the character to something
+/// on screen. Where it stands to show it, and the mark it leaves there.
+/// Kept free of AppKit so the tests can check it without a window.
+/// Rectangles are in screen coordinates, origin bottom-left, as AppKit
+/// uses them, once toAppKit has turned them.
+enum GuideMath {
+    enum Mark: String {
+        case box, circle, underline, none
+    }
+
+    /// Accessibility → AppKit: the daemon's rectangles are measured from
+    /// the top of the primary display, whichever screen they are on.
+    static func toAppKit(_ r: CGRect, primaryHeight: CGFloat) -> CGRect {
+        CGRect(x: r.minX, y: primaryHeight - r.maxY, width: r.width, height: r.height)
+    }
+
+    /// The point under the character while it shows `rect`: beside it,
+    /// its body level with the middle. On the left, away from which its
+    /// bubble reaches, so the bubble does not cover what it shows; on the
+    /// right when the left has no room in `visible`.
+    static func stand(beside rect: CGRect, in visible: CGRect, body: CGFloat, tall: CGFloat,
+                      inset: CGFloat, gap: CGFloat = 14) -> CGPoint {
+        let left = rect.minX - gap - body / 2
+        let x = left >= visible.minX + inset ? left : rect.maxX + gap + body / 2
+        return CGPoint(x: x, y: rect.midY - tall / 2)
+    }
+
+    /// What the mark is drawn along, around `rect`: a box a little wider
+    /// than it, an oval that clears its corners, or a line under it.
+    static func outline(_ mark: Mark, around rect: CGRect) -> CGRect {
+        switch mark {
+        case .box: return rect.insetBy(dx: -5, dy: -5)
+        // An oval through a rectangle's corners is √2 times its size.
+        case .circle: return rect.insetBy(dx: -(rect.width * 0.21 + 6), dy: -(rect.height * 0.21 + 6))
+        case .underline: return CGRect(x: rect.minX - 2, y: rect.minY - 5, width: rect.width + 4, height: 0)
+        case .none: return .null
+        }
+    }
+
+    /// One frame of its way up or down to where it is sent: most of the
+    /// way in a third of a second, and there once it is within a point.
+    static func glide(_ y: CGFloat, toward goal: CGFloat, dt: Double) -> CGFloat {
+        let next = y + (goal - y) * CGFloat(1 - exp(-7 * min(max(dt, 0), 0.1)))
+        return abs(goal - next) < 1 ? goal : next
+    }
+}

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

@@ -0,0 +1,39 @@
+import CoreGraphics
+import Foundation
+
+/// What the character meets on the live screen (#539): the sides of the
+/// windows that stand on its line. Read from the window list, which gives
+/// each window's rectangle and no picture, title or text, so it needs no
+/// permission.
+enum Meets {
+    /// A window smaller than this is not something to stop at.
+    static let least = CGSize(width: 80, height: 40)
+
+    /// Where the sides of `windows`, front to back, cross `band`: each
+    /// side only where no window in front covers it. One set of
+    /// coordinates for both.
+    static func edges(of windows: [CGRect], band: ClosedRange<CGFloat>) -> [Double] {
+        var found: [Double] = []
+        for (i, window) in windows.enumerated() {
+            let low = max(window.minY, band.lowerBound), high = min(window.maxY, band.upperBound)
+            guard window.width >= least.width, window.height >= least.height, low < high else { continue }
+            let y = (low + high) / 2
+            for x in [window.minX, window.maxX] {
+                let covered = windows[..<i].contains { $0.minX < x && x < $0.maxX && $0.minY <= y && y < $0.maxY }
+                if !covered { found.append(Double(x)) }
+            }
+        }
+        return found
+    }
+
+    /// The ordinary windows on screen, front to back, measured from the
+    /// top left of the main screen.
+    static func windows() -> [CGRect] {
+        let list = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
+        return list.compactMap { window in
+            guard window[kCGWindowLayer as String] as? Int == 0, window[kCGWindowAlpha as String] as? Double != 0,
+                  let bounds = window[kCGWindowBounds as String] else { return nil }
+            return CGRect(dictionaryRepresentation: bounds as! CFDictionary)
+        }
+    }
+}

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

@@ -570,6 +570,15 @@ final class Panel: NSPanel {
         onRender?(state)
     }
 
+    /// On screen with something to use: an answer, an error or the call
+    /// buttons. The character does not play with the pointer then (#537).
+    @MainActor
+    var holdsSomething: Bool {
+        guard isVisible else { return false }
+        if case .error = current { return true }
+        return expanded || callBar.mode != .hidden
+    }
+
     /// The call buttons for this moment of a call; `.hidden` outside one.
     @MainActor
     func showCall(_ mode: CallBar.Mode) {

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

@@ -5,12 +5,23 @@ import Foundation
 /// different play each time. Numbers only, like `PlayMath`.
 extension PlayMath {
     /// A piece cut out of the picture and drawn somewhere else: which
-    /// part of the picture, where its top-left corner is now, and how far
-    /// it has turned (radians).
+    /// part of the picture, where its top-left corner is now, how far it
+    /// has turned (radians), and the page's colour around it, which is
+    /// left out so only its ink moves.
     struct Piece: Equatable {
         var from: Rect
         var at: Point
         var turn = 0.0
+        var paper: UInt32 = 0xFFFFFF
+    }
+
+    /// How much of a pixel of a moved piece is drawn, 0…1: none of the
+    /// page's colour, all of the ink, and the soft edge of a letter in
+    /// between. Without it a flying letter carries a box of page with it
+    /// and covers the text it passes.
+    static func ink(r: UInt8, g: UInt8, b: UInt8, paper: UInt32) -> Double {
+        let far = max(abs(Int(r) - Int(paper >> 16 & 0xFF)), abs(Int(g) - Int(paper >> 8 & 0xFF)), abs(Int(b) - Int(paper & 0xFF)))
+        return min(max(Double(far - 10) / 40, 0), 1)
     }
 
     /// A piece from the moment it leaves its place. Its place is covered
@@ -36,18 +47,22 @@ extension PlayMath {
     static let gravity = 1400.0
     static let lift = 0.35
 
-    /// Where a thrown piece is `seconds` after it left. It stops on the
-    /// bottom of the picture and at its sides.
+    /// Where a thrown piece is `seconds` after it left. It bounces once
+    /// on the bottom of the picture and lies still, and stops at its sides.
     static func thrown(_ source: Rect, v: Point, spin: Double, rise: Double, after seconds: Double,
                        width: Double, height: Double) -> Piece {
         let floor = max(height - source.h - rise, source.y)
         let landing = (-v.y + (v.y * v.y + 2 * gravity * (floor - source.y)).squareRoot()) / gravity
         let s = min(max(seconds, 0), landing)
-        let x = min(max(source.x + v.x * s, 0), max(width - source.w, 0))
+        // How fast it comes down, and the bounce that makes: a third as
+        // fast, sideways too.
+        let hit = v.y + gravity * landing
+        let more = min(max(seconds - landing, 0), PlayMotion.bounceTime(speed: hit, gravity: gravity))
+        let x = min(max(source.x + v.x * (s + more / 3), 0), max(width - source.w, 0))
         // It turns about as fast as `spin`, and lands flat: the right way
         // up or upside down.
         let flat = (spin * landing / .pi).rounded() * .pi
-        return Piece(from: source, at: Point(x: x, y: source.y + v.y * s + gravity * s * s / 2), turn: landing > 0 ? flat * s / landing : 0)
+        return Piece(from: source, at: Point(x: x, y: source.y + v.y * s + gravity * s * s / 2 - PlayMotion.bounce(more, speed: hit, gravity: gravity)), turn: landing > 0 ? flat * s / landing : 0)
     }
 
     /// What it can do to a line.
@@ -107,17 +122,29 @@ extension Play {
             f.gone.append((cover(cut.source), cut.paper))
             switch cut.path {
             case .thrown(let v, let spin, let rise):
-                f.pieces.append(P.thrown(cut.source, v: v, spin: spin, rise: rise, after: f.t - cut.start, width: size.x, height: size.y))
+                var piece = P.thrown(cut.source, v: v, spin: spin, rise: rise, after: f.t - cut.start, width: size.x, height: size.y)
+                piece.paper = cut.paper
+                f.pieces.append(piece)
             case .held(let until, let to):
                 // From its place to above the head, and from there down.
                 let head = P.Point(x: f.at.x - cut.source.w / 2, y: f.at.y - P.top - cut.source.h)
                 let a = f.t < until ? P.Point(x: cut.source.x, y: cut.source.y) : head, b = f.t < until ? head : to
                 let q = M.ease(f.t < until ? M.span(f.t, cut.start, cut.start + P.lift) : M.span(f.t, until, until + P.lift))
-                f.pieces.append(P.Piece(from: cut.source, at: P.Point(x: a.x + (b.x - a.x) * q, y: a.y + (b.y - a.y) * q)))
+                f.pieces.append(P.Piece(from: cut.source, at: P.Point(x: a.x + (b.x - a.x) * q, y: a.y + (b.y - a.y) * q), paper: cut.paper))
             }
         }
     }
 
+    /// How far along a move it is: a jump crouches first and lands at the
+    /// end, a walk and a wipe start and stop, the rest keep one pace.
+    func body(_ m: Move, at t: Double) -> PlayMotion.Body {
+        switch m.kind {
+        case .jump, .carry: return PlayMotion.jump(t - m.start, of: m.duration)
+        case .walk, .wipe: return PlayMotion.glide(t - m.start, of: m.duration)
+        default: return PlayMotion.Body(travel: M.span(t, m.start, m.end))
+        }
+    }
+
     /// Which way it faces during a move, and its pose without the motion.
     func look(_ m: Move) -> (face: Double, pose: M.Pose) {
         let way: Double = m.to.x >= m.from.x ? 1 : -1

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

@@ -90,6 +90,7 @@ enum PlayMath {
 struct Play {
     typealias P = PlayMath
     typealias M = CharacterMath
+    typealias Mo = PlayMotion
 
     enum Kind { case jump, walk, eat, wipe, kick, stomp, fall, lift, carry, drop, rest }
 
@@ -131,13 +132,16 @@ struct Play {
         self.lines = lines
         self.size = size
         var at = start, now = 0.0
+        /// The seconds of a jump over `points`: its crouch, its time in
+        /// the air and its landing.
+        func leap(_ points: Double) -> Double { Mo.crouch + 0.34 + points / 900 + Mo.landing }
         func add(_ kind: Kind, to: P.Point, _ seconds: Double, line: Int = 0, words: Range<Int> = 0..<0) -> Move {
             Move(kind: kind, from: at, to: to, start: now, duration: seconds, line: line, words: words)
         }
         /// Get to `to` first: a jump, unless it is already there.
         func reach(_ to: P.Point, into list: inout [Move]) {
             guard at != to else { return }
-            let m = add(.jump, to: to, 0.5 + hypot(to.x - at.x, to.y - at.y) / 900)
+            let m = add(.jump, to: to, leap(hypot(to.x - at.x, to.y - at.y)))
             list.append(m); at = to; now = m.end
         }
         var list: [Move] = [], cuts: [P.Cut] = []
@@ -183,8 +187,10 @@ struct Play {
                 let word = lines[i].words[w]
                 reach(P.Point(x: word.rect.x - P.mouth - 4, y: lines[i].rect.midY + P.middle), into: &list)
                 let m = stay(.kick, 0.6, line: i)
-                for (k, letter) in P.letters(of: word).enumerated() {
-                    throwing(letter, line: i, at: m.start + 0.25, v: P.Point(x: 150 + 40 * Double(k), y: -320 - 30 * Double(k % 3)),
+                // The letters leave one after the other, the nearest first.
+                let letters = P.letters(of: word)
+                for (k, letter) in letters.enumerated() {
+                    throwing(letter, line: i, at: m.start + 0.25 + Mo.stagger(k, of: letters.count), v: P.Point(x: 150 + 40 * Double(k), y: -320 - 30 * Double(k % 3)),
                              spin: 4 + Double(k % 3))
                 }
             case .stomp(let i):
@@ -207,7 +213,7 @@ struct Play {
                 let word = lines[i].words[w].rect, home = lines[j].rect
                 reach(P.Point(x: word.x - P.mouth - 4, y: lines[i].rect.midY + P.middle), into: &list)
                 let up = stay(.lift, P.lift, line: i)
-                let m = add(.carry, to: P.Point(x: home.maxX - 4, y: home.y), 0.5 + hypot(home.maxX - 4 - at.x, home.y - at.y) / 900, line: j)
+                let m = add(.carry, to: P.Point(x: home.maxX - 4, y: home.y), leap(hypot(home.maxX - 4 - at.x, home.y - at.y)), line: j)
                 list.append(m); at = m.to; now = m.end
                 let down = stay(.drop, P.lift, line: j)
                 // After the line, or on top of its end when the page stops there.
@@ -228,12 +234,13 @@ struct Play {
         let m = moves[i], p = M.span(t, m.start, m.end)
         var f = Frame(t: t, done: t >= duration)
 
-        f.at = P.Point(x: m.from.x + (m.to.x - m.from.x) * p, y: m.from.y + (m.to.y - m.from.y) * p)
+        let body = body(m, at: t)
+        f.at = P.Point(x: m.from.x + (m.to.x - m.from.x) * body.travel, y: m.from.y + (m.to.y - m.from.y) * body.travel)
         switch m.kind {
         case .jump, .carry:
             // An arc over both ends, kept inside the picture.
             let rise = 30 + hypot(m.to.x - m.from.x, m.to.y - m.from.y) * 0.12
-            f.at.y -= min(rise, max(min(m.from.y, m.to.y) - P.top, 0)) * 4 * p * (1 - p)
+            f.at.y -= min(rise, max(min(m.from.y, m.to.y) - P.top, 0)) * body.air
         // Three hops on the spot.
         case .stomp: f.at.y -= min(22, max(m.from.y - P.top, 0)) * abs(sin(3 * .pi * p))
         // Faster and faster.
@@ -249,10 +256,11 @@ struct Play {
         f.face = before.face + (now.face - before.face) * into
         f.pose = M.blend(before.pose, now.pose, eyes: into, body: into, marks: into)
         switch m.kind {
-        case .walk: f.pose.lift += 3 * into * abs(sin(2 * .pi * t * 2.2))
+        // A step every 50 points, smaller while it starts and stops.
+        case .walk: f.pose.lift += 3 * body.speed * abs(sin(.pi * abs(f.at.x - m.from.x) / 50))
         case .jump, .carry:
-            let air = sin(.pi * p)
-            f.pose.sy *= 1 + 0.12 * air; f.pose.sx *= 1 - 0.08 * air
+            f.pose.sy *= body.sy; f.pose.sx *= body.sx
+            f.pose.lift *= 1 - 0.5 * body.dip
         case .eat:
             let bite = into * (0.5 + 0.5 * sin(2 * .pi * t / P.perLetter))
             f.pose.sy *= 1 - 0.08 * bite; f.pose.sx *= 1 + 0.05 * bite

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

@@ -0,0 +1,110 @@
+import Foundation
+
+/// How things move in play mode (#505), after the rules the videos are
+/// made with: nothing starts or stops at full speed, a jump is announced
+/// by a crouch and ends in a soft landing, letters leave one after the
+/// other, and what falls bounces once before it lies still. Numbers only.
+enum PlayMotion {
+    typealias M = CharacterMath
+
+    /// Fast start, slow stop; and slow start, fast end.
+    static func out(_ p: Double) -> Double { 1 - into(1 - p) }
+    static func into(_ p: Double) -> Double {
+        let p = min(max(p, 0), 1)
+        return p * p
+    }
+
+    /// The body at one moment of a move: how far along its way (0…1),
+    /// how high in its arc (0…1), its stretch, how deep it sits on its
+    /// feet (0…1) and how fast it goes (0…1).
+    struct Body: Equatable {
+        var travel = 0.0, air = 0.0
+        var sx = 1.0, sy = 1.0
+        var dip = 0.0
+        var speed = 0.0
+    }
+
+    /// Seconds: the crouch before a jump, the landing after it, and the
+    /// start and the stop of a walk.
+    static let crouch = 0.16
+    static let landing = 0.26
+    static let walkUp = 0.2
+    static let walkDown = 0.26
+    /// How much taller the body is at full stretch, and how much shorter
+    /// at the deepest of a crouch and of a landing.
+    static let stretch = 0.14
+    static let squat = 0.16
+    static let squash = 0.2
+
+    /// A jump of `duration` seconds, `t` seconds in. It crouches first
+    /// and goes nowhere, leaves stretched, is round at the top, comes
+    /// down stretched, and lands: squashed, a little too tall once, then
+    /// still. It has arrived when the landing begins.
+    static func jump(_ t: Double, of duration: Double) -> Body {
+        guard duration > 0 else { return Body(travel: 1) }
+        let t = min(max(t, 0), duration)
+        let before = min(crouch, duration * 0.25), after = min(landing, duration * 0.3)
+        // A jump too short for a whole landing changes shape less, not faster.
+        let long = stretch * after / landing, flat = squash * after / landing
+        if t < before {
+            // Down slowly, up fast: the push.
+            let q = t / before
+            let deep = q < 0.65 ? out(q / 0.65) : 1 - into((q - 0.65) / 0.35)
+            return Body(sx: 1 + squat * 0.7 * deep, sy: 1 - squat * deep, dip: deep)
+        }
+        if t <= duration - after {
+            let u = M.span(t, before, duration - after)
+            // Stretched while it moves fast up or down, round at the top.
+            let more = long * abs(1 - 2 * u) * min(u / 0.12, 1)
+            return Body(travel: u, air: 4 * u * (1 - u), sx: 1 - more * 0.6, sy: 1 + more, speed: 1)
+        }
+        let more = keys([(0, long), (0.4, -flat), (0.72, 0.04), (1, 0)], at: (t - (duration - after)) / after)
+        return Body(travel: 1, sx: 1 - more * 0.6, sy: 1 + more, dip: max(-more / flat, 0))
+    }
+
+    /// A walk, or a wipe, of `duration` seconds, `t` seconds in: it gets
+    /// up to speed, keeps it, and slows to a stop.
+    static func glide(_ t: Double, of duration: Double) -> Body {
+        guard duration > 0 else { return Body(travel: 1) }
+        let t = min(max(t, 0), duration)
+        let up = min(walkUp, duration / 3), down = min(walkDown, duration / 3)
+        // Full speed, in ways a second.
+        let top = 1 / (duration - up / 2 - down / 2)
+        if t < up { return Body(travel: top * t * t / (2 * up), speed: t / up) }
+        if t <= duration - down { return Body(travel: top * (t - up / 2), speed: 1) }
+        let left = duration - t
+        return Body(travel: 1 - top * left * left / (2 * down), speed: left / down)
+    }
+
+    /// When the `k`th of `count` things starts after the first: one after
+    /// the other, and all gone within 0.4 seconds, so it reads as one go.
+    static func stagger(_ k: Int, of count: Int) -> Double {
+        guard count > 1 else { return 0 }
+        return Double(k) * min(0.035, 0.4 / Double(count - 1))
+    }
+
+    /// How high something is above where it landed, `seconds` after it
+    /// hit at `speed` (points a second) under `gravity`: one bounce, a
+    /// third as fast as it came down, then it lies still.
+    static func bounce(_ seconds: Double, speed: Double, gravity: Double) -> Double {
+        let up = abs(speed) / 3
+        guard seconds > 0, gravity > 0 else { return 0 }
+        return max(up * seconds - gravity * seconds * seconds / 2, 0)
+    }
+
+    /// The seconds that bounce lasts.
+    static func bounceTime(speed: Double, gravity: Double) -> Double {
+        gravity > 0 ? 2 * abs(speed) / 3 / gravity : 0
+    }
+
+    /// The value at `p` between (place, value) keys in order, eased from
+    /// each key to the next.
+    static func keys(_ keys: [(at: Double, value: Double)], at p: Double) -> Double {
+        guard let first = keys.first, let last = keys.last else { return 0 }
+        if p <= first.at { return first.value }
+        for (a, b) in zip(keys, keys.dropFirst()) where p <= b.at {
+            return a.value + (b.value - a.value) * M.ease(M.span(p, a.at, b.at))
+        }
+        return last.value
+    }
+}

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

@@ -4,7 +4,7 @@ import AppKit
 /// words are gone, the pieces that moved, the cloth, and the character. The context is flipped,
 /// in the picture's points.
 enum PlayDraw {
-    static func draw(_ frame: Play.Frame, in ctx: CGContext, stops: [NSColor], picture: CGImage?, scale: CGFloat) {
+    static func draw(_ frame: Play.Frame, in ctx: CGContext, stops: [NSColor], cutouts: PlayCutouts?) {
         for gone in frame.gone {
             let c = gone.paper
             ctx.setFillColor(CGColor(srgbRed: CGFloat(c >> 16 & 0xFF) / 255, green: CGFloat(c >> 8 & 0xFF) / 255,
@@ -13,7 +13,7 @@ enum PlayDraw {
         }
         for piece in frame.pieces {
             let from = cg(piece.from)
-            guard let part = picture?.cropping(to: from.applying(CGAffineTransform(scaleX: scale, y: scale))) else { continue }
+            guard let part = cutouts?.image(from, paper: piece.paper) else { continue }
             ctx.saveGState()
             ctx.translateBy(x: piece.at.x + from.width / 2, y: piece.at.y + from.height / 2)
             ctx.rotate(by: piece.turn)
@@ -40,6 +40,41 @@ enum PlayDraw {
     private static func cg(_ r: PlayMath.Rect) -> CGRect { CGRect(x: r.x, y: r.y, width: r.w, height: r.h) }
 }
 
+/// The pieces of the picture that move, each cut out once: the ink alone,
+/// the page's colour around it left out (`PlayMath.ink`).
+final class PlayCutouts {
+    private let picture: CGImage
+    /// Pixels of the picture per point.
+    private let scale: CGFloat
+    private var made: [[CGFloat]: CGImage] = [:]
+
+    init(picture: CGImage, scale: CGFloat) {
+        self.picture = picture
+        self.scale = scale
+    }
+
+    /// The part of the picture at `from` (points), without its paper.
+    func image(_ from: CGRect, paper: UInt32) -> CGImage? {
+        let key = [from.minX, from.minY, from.width, from.height]
+        if let done = made[key] { return done }
+        guard let part = picture.cropping(to: from.applying(CGAffineTransform(scaleX: scale, y: scale))),
+              let ctx = CGContext(data: nil, width: part.width, height: part.height, bitsPerComponent: 8, bytesPerRow: part.width * 4,
+                                  space: CGColorSpace(name: CGColorSpace.sRGB)!, bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue),
+              let data = ctx.data else { return nil }
+        ctx.draw(part, in: CGRect(x: 0, y: 0, width: part.width, height: part.height))
+        let px = data.bindMemory(to: UInt8.self, capacity: part.width * part.height * 4)
+        for i in stride(from: 0, to: part.width * part.height * 4, by: 4) {
+            let a = PlayMath.ink(r: px[i], g: px[i + 1], b: px[i + 2], paper: paper)
+            // Premultiplied: the colour fades with it.
+            for k in 0..<3 { px[i + k] = UInt8(Double(px[i + k]) * a) }
+            px[i + 3] = UInt8(255 * a)
+        }
+        let image = ctx.makeImage()
+        made[key] = image
+        return image
+    }
+}
+
 /// The stage: a frozen picture of the screen laid over everything, with
 /// the character playing on it. The real page is never touched: nothing
 /// is clicked, typed or changed, and what looks eaten or wiped is only
@@ -157,7 +192,8 @@ private final class PlayView: NSView {
     var shown = Play.Frame()
     var stops = CharacterDraw.stops(tint: Brand.accent, colors: nil)
     /// The picture under it: moved pieces are cut from it.
-    var picture: CGImage?
+    var picture: CGImage? { didSet { cutouts = nil } }
+    private var cutouts: PlayCutouts?
     var onInput: (() -> Void)?
 
     override var isFlipped: Bool { true }
@@ -166,8 +202,10 @@ private final class PlayView: NSView {
 
     override func draw(_ dirtyRect: NSRect) {
         guard let ctx = NSGraphicsContext.current?.cgContext else { return }
-        PlayDraw.draw(shown, in: ctx, stops: stops, picture: picture,
-                      scale: CGFloat(picture?.width ?? 0) / max(bounds.width, 1))
+        if cutouts == nil, let picture {
+            cutouts = PlayCutouts(picture: picture, scale: CGFloat(picture.width) / max(bounds.width, 1))
+        }
+        PlayDraw.draw(shown, in: ctx, stops: stops, cutouts: cutouts)
     }
 
     override func keyDown(with event: NSEvent) { onInput?() }

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

@@ -0,0 +1,137 @@
+import Foundation
+
+/// Play with the pointer (#505): with "Play mode" ticked, an idle
+/// character does more than step aside. When the pointer moves within
+/// its sight it starts a game: it follows it along the edge, crouches
+/// and jumps at it like a cat, or runs away from it. Between games it
+/// rests, and the usual rules hold. A click in its sight makes it jump.
+///
+/// It only decides where the character wants to be and how it crouches
+/// and hops; `CharacterSim` moves it. Foundation only, and the same
+/// games in the same order on every run, so the tests can count on them.
+struct PointerPlay {
+    typealias M = CharacterMath
+
+    enum Game: Equatable { case follow, pounce, flee }
+
+    struct Out: Equatable {
+        /// Where it wants to be along the edge. Nil: no game, the usual rules.
+        var target: Double?
+        /// 0…1 crouched, and the height of a hop in drawing units.
+        var crouch = 0.0
+        var hop = 0.0
+        /// It came down on the pointer just now.
+        var caught = false
+    }
+
+    /// How far along the edge and above it the pointer is seen, in points.
+    static let sight = (x: 520.0, y: 360.0)
+    /// A pointer slower than this, in points a second, starts no game.
+    static let stir = 80.0
+    /// Following, it stops this short of the pointer.
+    static let gap = 70.0
+    /// It jumps at a pointer no further than this, and no higher.
+    static let leap = (x: 220.0, y: 150.0)
+    /// It has caught a pointer this close to where it comes down.
+    static let grip = 45.0
+    /// Running away, it puts this much between the pointer and itself.
+    static let far = 320.0
+    /// Seconds: the crouch before a jump, the jump, running away, and
+    /// the jump a click gives it.
+    static let wind = 0.5, air = 0.6, flight = 2.5, start = 0.35
+    /// Drawing units: how high it jumps at the pointer, and at a click.
+    static let high = 70.0, jolt = 34.0
+
+    private(set) var game: Game?
+    private(set) var games = 0
+    private var began = 0.0, until = 0.0, next = 0.0
+    private var jumpTo: Double?
+    private var seen: (x: Double, y: Double)?
+    private var down = false
+    private var jolted: Double?
+
+    /// One frame. `x` is where the character is; `pointer` along the edge
+    /// and above it, nil on another screen; `down` the mouse button.
+    mutating func step(_ now: Double, _ dt: Double, x: Double, pointer: (x: Double, y: Double)?,
+                       down: Bool, range: ClosedRange<Double>) -> Out {
+        let clicked = down && !self.down
+        self.down = down
+        let before = seen
+        seen = pointer
+        guard let p = pointer, abs(p.x - x) < Self.sight.x, abs(p.y) < Self.sight.y else {
+            if game != nil { end(now) }
+            return Out(hop: hop(now))
+        }
+        func inside(_ v: Double) -> Double { min(max(v, range.lowerBound), range.upperBound) }
+
+        // A click startles it: a small jump, and the game is over.
+        if clicked && jumpTo == nil {
+            jolted = now
+            if game != nil { end(now) }
+        }
+
+        if game == nil, now >= next, jolted == nil, let was = before, dt > 0,
+           hypot(p.x - was.x, p.y - was.y) / dt > Self.stir {
+            games += 1
+            let pick = M.rnd(games, 7)
+            let reach = abs(p.x - x) < Self.leap.x && abs(p.y) < Self.leap.y
+            game = pick < 0.5 ? .follow : pick < 0.8 ? (reach ? .pounce : .follow) : .flee
+            began = now
+            jumpTo = nil
+            until = now + (game == .follow ? 4 + 3 * M.rnd(games, 2) : game == .flee ? Self.flight : Self.wind + Self.air)
+        }
+
+        var out = Out(hop: hop(now))
+        switch game {
+        case nil:
+            break
+        case .follow:
+            // On the side it is on, a little short of the pointer.
+            out.target = inside(p.x + (x >= p.x ? Self.gap : -Self.gap))
+        case .pounce:
+            let t = now - began
+            if t < Self.wind {
+                out.target = x
+                out.crouch = M.ease(t / (Self.wind * 0.8))
+            } else {
+                // It jumps at where the pointer was when it let go.
+                if jumpTo == nil { jumpTo = inside(p.x) }
+                let a = M.span(t, Self.wind, Self.wind + Self.air)
+                out.target = jumpTo
+                out.crouch = 1 - M.ease(a / 0.25)
+                out.hop = Self.high * sin(.pi * a)
+            }
+        case .flee:
+            out.target = abs(p.x - x) < Self.far ? M.aside(x: x, pointer: p.x, clear: Self.far, range: range) : x
+        }
+        if game != nil && now >= until {
+            out.caught = game == .pounce && abs(p.x - x) < Self.grip && abs(p.y) < Self.leap.y
+            end(now)
+        }
+        return out
+    }
+
+    /// The assistant has work, or play is off: no game, and none at once
+    /// after. The button is still followed, so one held through it is no click.
+    mutating func stop(_ now: Double, down: Bool) {
+        if game != nil { end(now) }
+        self.down = down
+        jolted = nil
+        seen = nil
+    }
+
+    /// A game is over: a rest of five to thirteen seconds before the next.
+    private mutating func end(_ now: Double) {
+        game = nil
+        jumpTo = nil
+        next = now + 5 + 8 * M.rnd(games, 3)
+    }
+
+    /// The jump a click gives it.
+    private mutating func hop(_ now: Double) -> Double {
+        guard let at = jolted else { return 0 }
+        let a = (now - at) / Self.start
+        if a >= 1 { jolted = nil; return 0 }
+        return Self.jolt * sin(.pi * a)
+    }
+}

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

@@ -85,6 +85,7 @@ final class App: NSObject, NSApplicationDelegate {
 
     // An agent ringing the owner (#321).
     private let callWatcher = CallWatcher()
+    private let guideWatcher = GuideWatcher()
     private let ringer = Ringer()
     /// The call ringing on the pill now.
     private var ringingCall: IncomingCall?
@@ -392,6 +393,7 @@ final class App: NSObject, NSApplicationDelegate {
             panel.attach(head: head, visible: visible)
             return panel.isVisible ? panel.frame : nil
         }
+        character.bubbleShows = { [weak self] in self?.panel.holdsSomething ?? false }
         panel.onLook = { [weak self] state, tint, colors in
             self?.character.show(state.activity, tint: tint, colors: colors)
             // The assistant has something to show: play gives way.
@@ -507,6 +509,11 @@ final class App: NSObject, NSApplicationDelegate {
             return CallModel.pollQuery(ringing: self.ringingCall?.id ?? self.answeringCall, canRing: self.canRing)
         }
         callWatcher.start()
+        // The answering agent sends the character to something (#482).
+        guideWatcher.wanted = { [weak self] in self?.character.onScreen == true }
+        guideWatcher.onCommand = { [weak self] rect, mark in self?.character.guide(to: rect, mark: mark) }
+        guideWatcher.start()
+        character.onScreenChanged = { [weak self] in self?.guideWatcher.start() }
 
         // The target does not wait for the microphone: the menu shows it
         // either way.