agentix-cli 0.102.2 → 0.103.1

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

@@ -32,6 +32,8 @@ final class CharacterHost {
     private var shown = false
     /// Hidden with its bubble, until the talk key or the menu (#502).
     private var hidden = false
+    /// On the page, playing (#580): its window is out until it is back.
+    private var away = false
     private var animated = true
     private var reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
     private var activity = CharacterMath.Activity.idle
@@ -64,6 +66,9 @@ final class CharacterHost {
     /// (#505) takes it from there.
     var stops: [NSColor] { view.stops }
     var foot: NSPoint { NSPoint(x: CGFloat(sim.x), y: rest.y) }
+    /// Its windows, by number: its own and its mark's. The picture of a
+    /// play leaves them out (#583).
+    var windows: [Int] { [window.windowNumber, guide.window] }
     /// 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)?
@@ -72,12 +77,14 @@ final class CharacterHost {
     /// Sent somewhere, and what its bubble says there (#562).
     var sent: Bool { guide.showing != nil }
     var caption: String? { guide.caption }
+    /// The state it was asked to show by name (#570), there or where it rests.
+    private var asked: CharacterMath.Mood?
     /// Told when it is sent somewhere, to its next stop or back.
     var onGuide: (() -> Void)?
     /// 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 }
+    var onScreen: Bool? { shown ? !hidden && !away : nil }
     /// Told when it comes on screen or leaves it: shown or hidden, or the look changed.
     var onScreenChanged: (() -> Void)?
 
@@ -117,6 +124,14 @@ final class CharacterHost {
         onScreenChanged?()
     }
 
+    /// Out for a play on the page, and back as it left, where it left.
+    func setAway(_ on: Bool) {
+        guard away != on else { return }
+        away = on
+        run()
+        onScreenChanged?()
+    }
+
     /// Hide it, as its bubble is hidden: gone until it is asked back.
     func setHidden(_ on: Bool) {
         guard hidden != on else { return }
@@ -136,6 +151,10 @@ final class CharacterHost {
 
     /// `voice.stroll`: a slow walk now and then while it has nothing to do.
     var strolls = false
+    /// `voice.animations` as the wait between two small animations by
+    /// itself (`IdlePlay.gap`), and AgentX's own hold, which stops them.
+    var animates = 0.0
+    private var quiet = false
 
     /// "Animated orb" in the menu.
     func setAnimated(_ on: Bool) {
@@ -151,9 +170,11 @@ 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, caption: String? = nil) {
-        if shown, !hidden, carried == nil, let rect {
+    /// Go beside `rect` and mark it, or with nil go back to where it
+    /// rests; in the state `asked`, or with nil its real one.
+    func guide(to rect: NSRect?, mark kind: GuideMath.Mark = .none, caption: String? = nil, asked mood: CharacterMath.Mood? = nil) {
+        asked = shown && !hidden && !away ? mood : nil
+        if shown, !hidden, !away, carried == nil, let rect {
             guide.show(rect, kind, caption: caption, color: view.stops[2], animated: !still)
         } else {
             guide.end()
@@ -172,7 +193,7 @@ final class CharacterHost {
     private func run() {
         timer?.invalidate()
         timer = nil
-        guard shown, !hidden else { carried = nil; guide(to: nil); window.orderOut(nil); return }
+        guard shown, !hidden, !away else { carried = nil; guide(to: nil); window.orderOut(nil); return }
         tick()
         window.orderFrontRegardless()
         // Still, it only watches for the hand that moves it.
@@ -239,10 +260,13 @@ final class CharacterHost {
 
         let frame: CharacterSim.Frame
         if still {
-            frame = CharacterSim.still(activity, home: home)
+            frame = CharacterSim.still(activity, asked: asked, sent: guide.showing != nil, home: home)
         } else {
             if activity == .listening, let read = levelSource {
                 level = OrbMath.smooth(level, toward: OrbMath.level(fromRMS: read()))
+            } else if asked == .listening {
+                // Asked to listen, there is no microphone to follow: a slow swell.
+                level = 0.45 + 0.3 * sin(now * 5)
             } else {
                 level = 0
             }
@@ -259,11 +283,12 @@ final class CharacterHost {
                 edgesRead = now
                 // The window list counts down from the top of the main screen.
                 let top = first.frame.maxY - rest.y
+                quiet = animates > 0 && Hold.isOn
                 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,
+                             CharacterSim.Input(activity: activity, level: level, pointer: pointer, held: held, sent: guide.showing != nil, asked: asked, strolls: strolls,
+                                                edges: edges, shows: bubbleShows?() ?? false, plays: Config.playMode, animates: quiet ? 0 : animates, 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())

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

@@ -31,6 +31,19 @@ enum CharacterMath {
         }
     }
 
+    /// The state shown when one was asked for by name, or it was sent to
+    /// show something (#570). Someone talking, a ringing call and a call
+    /// between turns always show: the real turn comes first. Otherwise
+    /// the state asked for; and sent somewhere with none asked for, it
+    /// does not take the busy look, which would hide the move.
+    static func mood(for activity: Activity, asked: Mood?, sent: Bool) -> Mood {
+        switch activity {
+        case .listening, .ringing, .waiting: return mood(for: activity)
+        case .thinking: return asked ?? (sent ? .idle : .working)
+        case .idle, .speaking: return asked ?? mood(for: activity)
+        }
+    }
+
     /// The state it goes through on the way from `from` to `to`, if any:
     /// it notices you before it listens and when it wakes, and nods once
     /// it has heard you.

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

@@ -44,6 +44,8 @@ struct CharacterSim {
     private var met: Double?
     /// Its games with the pointer, and the crouch and hop they give it.
     private(set) var play = PointerPlay()
+    /// Its small animations by itself (#571).
+    private(set) var idle = IdlePlay()
     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)
@@ -117,8 +119,8 @@ struct CharacterSim {
 
         // Which state. A change starts from the pose it has now, so a
         // change in the middle of another is still one smooth move.
-        if input.activity != .idle { restSince = now }
-        var want = M.mood(for: input.activity)
+        if input.activity != .idle || input.asked != nil { restSince = now }
+        var want = M.mood(for: input.activity, asked: input.asked, sent: input.sent)
         if want == .idle && now - restSince >= Self.dozeAfter { want = .dozing }
         if want != goal {
             goal = want
@@ -130,6 +132,10 @@ struct CharacterSim {
         }
         if let at = pending, now >= at { pending = nil; go(goal, now) }
         var pose = change.pose(at: now)
+        // Idle, left alone and standing: a small animation now and then.
+        let alone = mood == .idle && input.activity == .idle && input.asked == nil && !input.sent && !input.held && !input.shows
+            && !near && game == PointerPlay.Out() && play.game == nil && abs(speed) < 40 && strolled == 0 && strollTo == 0
+        let own = idle.step(now, dt, free: alone, gap: input.animates, dozeIn: restSince + Self.dozeAfter - now)
 
         // Along the edge: a spring a little short of critical, so it
         // arrives with a small overshoot.
@@ -144,11 +150,11 @@ struct CharacterSim {
         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)
+        toward(&lean, min(max(speed / 480, -1), 1) * 13 + own.tilt, 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)
+        toward(&crouch, game.crouch + own.crouch, 20)
+        toward(&hop, game.hop + own.hop, 20)
         pose.sx *= 1 + 0.14 * crouch
         pose.sy *= 1 - 0.22 * crouch
         pose.lift += hop - 8 * crouch
@@ -180,8 +186,8 @@ struct CharacterSim {
             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)
+        toward(&glance.x, look.x + face * 2 + own.gx, 9)
+        toward(&glance.y, look.y + own.gy, 9)
 
         // What keeps it alive: breath, bob, blinks, and the voice.
         let t = now - (began ?? now)
@@ -201,6 +207,7 @@ struct CharacterSim {
             nextBlink = now + 2.2 + 4.5 * M.rnd(blinks)  // uneven, never the same loop twice
         }
         if now >= nextBlink { pose.open *= 1 - sin(.pi * (now - nextBlink) / Self.blink) }
+        pose.open *= 1 - own.shut
 
         return Frame(pose: pose, x: x, face: face, level: input.level, voice: voice, t: t,
                      dots: dots.compactMap { dot(at: now, $0) }, stars: bursts.flatMap { stars(at: now, $0) })
@@ -248,15 +255,6 @@ struct CharacterSim {
         strolled = 0; strollTo = 0; strollNext = nil
     }
 
-    /// The state alone, where it rests: for Reduce Motion, which shows a
-    /// still picture that changes between states and never a loop.
-    static func still(_ activity: M.Activity, home: Double) -> Frame {
-        // Its marks at full strength, so each state reads without motion:
-        // the arcs of its voice only while it speaks.
-        let pose = M.pose(M.mood(for: activity))
-        return Frame(pose: pose, x: home, level: 1, voice: pose.speak)
-    }
-
     private mutating func go(_ to: M.Mood, _ now: Double) {
         change = M.Transition(from: change.pose(at: now), to: M.pose(to), start: now, duration: M.duration(into: to))
         mood = to

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

@@ -15,6 +15,9 @@ extension CharacterSim {
         /// The answering agent sent it to show something (#482): it goes
         /// to `home` at once, awake, whatever the pointer did before.
         var sent = false
+        /// The state it was asked to show by name (#570), in place of
+        /// what the assistant is doing.
+        var asked: M.Mood?
         /// `voice.stroll`: with nothing to do, it takes a slow stroll
         /// beside where it rests now and then (#482).
         var strolls = false
@@ -26,6 +29,9 @@ extension CharacterSim {
         var shows = false
         /// "Play mode" is ticked: idle, it plays with the pointer (#505).
         var plays = false
+        /// `voice.animations`: the shortest wait between two small
+        /// animations by itself, in seconds (#571). 0: none.
+        var animates = 0.0
         /// The mouse button is down.
         var down = false
         /// Where it rests, and how far it may go.
@@ -56,4 +62,13 @@ extension CharacterSim {
         var dots: [Mark] = []
         var stars: [Mark] = []
     }
+
+    /// The state alone, where it rests: for Reduce Motion, which shows a
+    /// still picture that changes between states and never a loop.
+    static func still(_ activity: M.Activity, asked: M.Mood? = nil, sent: Bool = false, home: Double) -> Frame {
+        // Its marks at full strength, so each state reads without motion:
+        // the arcs of its voice only while it speaks.
+        let pose = M.pose(M.mood(for: activity, asked: asked, sent: sent))
+        return Frame(pose: pose, x: home, level: 1, voice: pose.speak)
+    }
 }

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

@@ -13,6 +13,9 @@ enum GuideClient {
         /// What its bubble says at the stop (#562). Nil: no bubble there,
         /// and a daemon too old to send one.
         let text: String?
+        /// The state it shows meanwhile (#570). Nil: its real state, and
+        /// a daemon too old to send one.
+        let expression: String?
     }
 
     /// GET /voice/guide: the command after `seq`, as soon as there is
@@ -37,8 +40,9 @@ final class GuideWatcher {
     private var task: Task<Void, Never>?
     /// The character is on screen.
     var wanted: (() -> Bool)?
-    /// Show this, in AppKit coordinates, with this caption, or go home.
-    var onCommand: ((NSRect?, GuideMath.Mark, String?) -> Void)?
+    /// Show this, in AppKit coordinates, with this caption and in this
+    /// state, or go home.
+    var onCommand: ((NSRect?, GuideMath.Mark, String?, CharacterMath.Mood?) -> 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
@@ -56,7 +60,7 @@ final class GuideWatcher {
     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, nil) }
+            if away { away = false; onCommand?(nil, .none, nil, nil) }
             try? await Task.sleep(nanoseconds: 2_000_000_000)
             return
         }
@@ -66,9 +70,10 @@ final class GuideWatcher {
             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, rect == nil ? nil : command.text)
+        let asked = command.expression.flatMap { CharacterMath.Mood(rawValue: $0) }
+        away = rect != nil || asked != nil
+        Log.info("guide: \(rect.map { "to \(Int($0.minX)),\(Int($0.minY)) \(Int($0.width))x\(Int($0.height)) \(command.mark)" } ?? "home")\(asked.map { ", \($0.rawValue)" } ?? "")")
+        onCommand?(rect, GuideMath.Mark(rawValue: command.mark) ?? .box, rect == nil ? nil : command.text, asked)
     }
 }
 
@@ -80,6 +85,8 @@ final class CharacterGuide {
     /// What its bubble says there (#562).
     private(set) var caption: String?
     private let mark = GuideMark()
+    /// The number of its mark's window.
+    var window: Int { mark.number }
     /// 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
@@ -125,6 +132,7 @@ final class GuideMark {
     private static let margin: CGFloat = 6
     private let window: NSPanel
     private let shape = CAShapeLayer()
+    var number: Int { window.windowNumber }
 
     init() {
         window = NSPanel(contentRect: .zero, styleMask: [.borderless, .nonactivatingPanel], backing: .buffered, defer: false)

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

@@ -46,9 +46,21 @@ enum GuideMath {
     /// At a stop the bubble says the command's caption, and with none
     /// there is no bubble; the idle hint is for where it rests, not for
     /// a stop, the way there or a play. `away`: sent somewhere, or playing.
-    static func idle(caption: String?, away: Bool) -> Idle {
+    /// `hint`: the hint may show (hintShows).
+    static func idle(caption: String?, away: Bool, hint: Bool = true) -> Idle {
         if let caption, !caption.isEmpty { return .caption(caption) }
-        return away ? .nothing : .hint
+        return away || !hint ? .nothing : .hint
+    }
+
+    /// Seconds after the app starts that the character's bubble says the hint.
+    static let hintSeconds = 6.0
+
+    /// Whether the idle hint may show (#576). A pill of its own always
+    /// says it. The character's bubble says it only for the first seconds
+    /// after the app starts, then there is no bubble at idle; "notifications
+    /// held" stays, since nothing else on screen says it.
+    static func hintShows(character: Bool, sinceStart: Double, held: Bool) -> Bool {
+        !character || held || sinceStart < hintSeconds
     }
 
     /// What a label needs beyond the width of its words (#569): a text

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

@@ -0,0 +1,113 @@
+import Foundation
+
+/// Small animations by itself (#571): idle and left alone, the character
+/// now and then looks around, hops or sways, just for the fun of it, and
+/// stretches with a yawn before it dozes. `voice.animations` says how
+/// often, or not at all.
+///
+/// It only decides what an animation adds to the pose; `CharacterSim`
+/// follows it, so one cut short by work does not snap. Foundation only,
+/// and the same animations in the same order on every run, so the tests
+/// can count on them.
+struct IdlePlay {
+    typealias M = CharacterMath
+
+    /// The animations, by name. The yawn comes before it dozes; the
+    /// others are picked now and then.
+    enum Act: String, CaseIterable { case look, hop, sway, yawn }
+
+    /// `voice.animations` as the shortest wait between two, in seconds.
+    /// The wait is up to twice that. 0: none.
+    static func gap(_ often: String?) -> Double {
+        switch often {
+        case "rarely": return 60
+        case "sometimes": return 25
+        case "often": return 10
+        default: return 0
+        }
+    }
+
+    /// Seconds an animation takes.
+    static func length(_ act: Act) -> Double {
+        switch act {
+        case .look, .yawn: return 2.6
+        case .hop: return 0.9
+        case .sway: return 1.8
+        }
+    }
+
+    /// This close to dozing, in seconds, no animation starts but the yawn.
+    static let calm = 6.0
+
+    /// What an animation adds to the pose: gaze and height in drawing
+    /// units, lean in degrees, 0…1 crouched (below 0: stretched tall) and
+    /// 0…1 how far the eyes are shut.
+    struct Out: Equatable {
+        var gx = 0.0, gy = 0.0, tilt = 0.0, hop = 0.0, crouch = 0.0, shut = 0.0
+    }
+
+    private(set) var act: Act?
+    private(set) var played = 0
+    private var began = 0.0
+    private var next: Double?
+    private var yawned = false
+    private var turn = 0
+    private var shut = 0.0
+
+    /// One frame. `free`: idle, left alone and standing where it is.
+    /// `dozeIn`: seconds until it dozes.
+    mutating func step(_ now: Double, _ dt: Double, free: Bool, gap: Double, dozeIn: Double) -> Out {
+        var out = Out()
+        if !free || gap <= 0 {
+            act = nil; next = nil
+        } else {
+            if dozeIn > Self.calm { yawned = false }
+            if let on = act, now - began >= Self.length(on) { act = nil; next = nil }
+            if act == nil {
+                if !yawned && dozeIn <= Self.length(.yawn) {
+                    yawned = true
+                    start(.yawn, now)
+                } else if next == nil {
+                    next = now + gap * (1 + M.rnd(played, 5))
+                } else if now >= next!, dozeIn > Self.calm {
+                    // One of the other two, so the same never comes twice.
+                    turn = (turn + 1 + min(Int(M.rnd(played, 6) * 2), 1)) % 3
+                    start([Act.look, .hop, .sway][turn], now)
+                }
+            }
+            if let on = act { out = Self.shape(on, (now - began) / Self.length(on)) }
+        }
+        // The eyes are followed here; the rest by the sim.
+        shut += (out.shut - shut) * (1 - exp(-dt * 20))
+        out.shut = shut
+        return out
+    }
+
+    /// Play `act` now, whatever the wait.
+    mutating func start(_ act: Act, _ now: Double) {
+        self.act = act
+        began = now
+        played += 1
+    }
+
+    /// An animation `p` of the way through, 0…1. Each starts and ends at
+    /// nothing, so it joins the resting pose at both ends.
+    static func shape(_ act: Act, _ p: Double) -> Out {
+        switch act {
+        case .look:
+            // To one side, to the other, and back.
+            return Out(gx: 8 * sin(2 * .pi * p), gy: -1.5 * sin(.pi * p))
+        case .hop:
+            // A short crouch, then up and down again.
+            return Out(hop: 26 * sin(.pi * M.span(p, 0.3, 1)),
+                       crouch: 0.7 * M.ease(p / 0.3) * (1 - M.ease(M.span(p, 0.3, 0.5))))
+        case .sway:
+            // Two swings from side to side, the widest in the middle.
+            return Out(tilt: 10 * sin(4 * .pi * p) * sin(.pi * p))
+        case .yawn:
+            // It stretches tall, looks up, and shuts its eyes a moment.
+            return Out(gy: -2 * sin(.pi * p), crouch: -0.8 * sin(.pi * M.span(p, 0, 0.8)),
+                       shut: M.ease(M.span(p, 0.15, 0.4)) * (1 - M.ease(M.span(p, 0.75, 1))))
+        }
+    }
+}

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

@@ -65,6 +65,22 @@ extension PlayMath {
         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)
     }
 
+    /// A word's letters: the word's rectangle cut into equal parts, one a
+    /// character. An estimate, close enough to take them one at a time.
+    static func letters(of word: Word) -> [Rect] {
+        let n = max(word.text.count, 1), w = word.rect.w / Double(n)
+        return (0..<n).map { Rect(x: word.rect.x + Double($0) * w, y: word.rect.y, w: w, h: word.rect.h) }
+    }
+
+    /// The colour most of `samples` share: the page around a line. Close
+    /// shades count as one, so the soft edge of a letter does not win.
+    static func common(_ samples: [UInt32]) -> UInt32? {
+        var count: [UInt32: Int] = [:]
+        for s in samples { count[s & 0xF8F8F8, default: 0] += 1 }
+        guard let best = count.max(by: { ($0.value, $0.key) < ($1.value, $1.key) })?.key else { return nil }
+        return samples.first { $0 & 0xF8F8F8 == best }
+    }
+
     /// What it can do to a line.
     enum Act: CaseIterable { case eat, wipe, kick, stomp, carry }
 
@@ -82,24 +98,31 @@ extension PlayMath {
         }
     }
 
-    /// A play, different for each seed: it jumps onto one of the lines
-    /// near the middle of the page and walks it, then does one thing to
-    /// each of up to four others, never the same thing twice. Lines too
-    /// close to the top to stand on, too short or of one word are left
-    /// alone.
+    /// A play, different for each page and each seed. It jumps onto the
+    /// page's heading, the line clearly taller than the others, or with
+    /// no heading onto one of the lines near the middle, and walks it.
+    /// Then it does one thing to each of up to four others, never the same
+    /// thing twice, and each thing to the line that suits it (`suits`).
+    /// Then it goes home. Lines too close to the top to stand on, too
+    /// short or of one word are left alone.
     static func script(_ lines: [Line], width: Double, height: Double, seed: UInt64) -> [Step] {
         var rng = Seeded(seed)
         let fit = lines.indices.filter { lines[$0].words.count >= 2 && lines[$0].rect.w >= 120 && lines[$0].rect.y >= top + 40 }
         func far(_ i: Int) -> Double { hypot(lines[i].rect.midX - width / 2, lines[i].rect.midY - height / 2) }
-        let near = fit.sorted { far($0) < far($1) }.prefix(8).shuffled(using: &rng)
-        guard let first = near.first else { return [] }
-        let acts = Act.allCases.shuffled(using: &rng)
+        var near = Array(fit.sorted { far($0) < far($1) }.prefix(8))
+        let usual = fit.map { lines[$0].rect.h }.sorted()[safe: fit.count / 2] ?? 0
+        let heading = fit.filter { lines[$0].rect.h >= usual * 1.4 }.max { lines[$0].rect.h < lines[$1].rect.h }
+        guard let first = heading ?? near.randomElement(using: &rng) else { return [] }
+        near.removeAll { $0 == first }
         var steps: [Step] = [.jump(line: first), .walk(line: first)]
         // With one line only, it plays on the line it walked.
-        let stage = near.count > 1 ? Array(near.dropFirst().prefix(4)) : [first]
-        for (k, i) in stage.enumerated() {
-            let n = lines[i].words.count, word = Int.random(in: 0..<n, using: &rng)
-            switch acts[k] {
+        if near.isEmpty { near = [first] }
+        for act in Act.allCases.shuffled(using: &rng).prefix(4) {
+            let luck = near.map { _ in Double.random(in: 0..<1, using: &rng) }
+            guard let k = near.indices.max(by: { suits(act, lines[near[$0]], luck[$0]) < suits(act, lines[near[$1]], luck[$1]) }) else { break }
+            let i = near.remove(at: k), words = lines[i].words
+            let n = words.count, word = Int.random(in: 0..<n, using: &rng)
+            switch act {
             case .eat:
                 let from = Int.random(in: 0..<n - 1, using: &rng)
                 steps.append(.eat(line: i, words: from..<min(from + 3, n)))
@@ -107,14 +130,44 @@ extension PlayMath {
             case .stomp: steps.append(.stomp(line: i))
             // The walked line is whole: the word goes to its end.
             case .carry where i != first: steps.append(.carry(line: i, word: word, to: first))
-            case .kick, .carry: steps.append(.kick(line: i, word: word))
+            // Its longest word: the most letters to fly.
+            case .kick, .carry: steps.append(.kick(line: i, word: words.indices.max { words[$0].text.count < words[$1].text.count } ?? word))
             }
         }
-        return steps + [.rest(1.2)]
+        return steps + [.rest(0.6), .home, .rest(0.3)]
     }
+
+    /// How well a line suits an act, the page deciding what happens
+    /// where (#580): the widest line is wiped, the one with the most words
+    /// stomped, the one with the longest word kicked, the shortest gives
+    /// the word that is carried. Any line can be eaten: `luck` decides.
+    static func suits(_ act: Act, _ line: Line, _ luck: Double) -> Double {
+        switch act {
+        case .wipe: return line.rect.w
+        case .stomp: return Double(line.words.count)
+        case .kick: return Double(line.words.map(\.text.count).max() ?? 0)
+        case .carry: return -line.rect.w
+        case .eat: return luck
+        }
+    }
+}
+
+private extension Array {
+    subscript(safe i: Int) -> Element? { indices.contains(i) ? self[i] : nil }
 }
 
 extension Play {
+    /// Its size at `t`, in play sizes (#580): as big as on its edge when
+    /// it leaves it and when it is back, shrinking in the air of its
+    /// first jump and growing in the air of its last. It never changes
+    /// size at once.
+    func scale(at t: Double) -> Double {
+        func air(_ m: Move) -> Double { M.ease(M.span(t, m.start + Mo.crouch, m.end - Mo.landing)) }
+        if let back, t >= moves[back].start { return 1 + (P.edge - 1) * air(moves[back]) }
+        guard let first = moves.first, first.kind == .jump, back != 0 else { return 1 }
+        return P.edge - (P.edge - 1) * air(first)
+    }
+
     /// The pieces that have left their place by this frame: each place is
     /// covered, and the piece is drawn where it is now.
     func move(_ f: inout Frame) {

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

@@ -52,11 +52,15 @@ enum PlayMath {
         case carry(line: Int, word: Int, to: Int)
         /// Stand still, facing you, for so many seconds.
         case rest(Double)
+        /// Jump back to where it left its edge, growing to its size there.
+        case home
     }
 
     /// Points per drawing unit on the page: a body 40 points across,
     /// smaller than on the bottom edge so it fits between lines.
     static let unit = 0.4
+    /// How many times bigger it is on its edge: 56 points across there.
+    static let edge = 1.4
     /// The middle of its body above its feet, and its top, in points.
     static let middle = (M.Pose().lift + 50) * unit
     static let top = (M.Pose().lift + 100) * unit + 8
@@ -66,22 +70,6 @@ enum PlayMath {
     static let perLetter = 0.09
     /// Its mouth, ahead of its middle.
     static let mouth = 10.0
-
-    /// A word's letters: the word's rectangle cut into equal parts, one a
-    /// character. An estimate, close enough to take them one at a time.
-    static func letters(of word: Word) -> [Rect] {
-        let n = max(word.text.count, 1), w = word.rect.w / Double(n)
-        return (0..<n).map { Rect(x: word.rect.x + Double($0) * w, y: word.rect.y, w: w, h: word.rect.h) }
-    }
-
-    /// The colour most of `samples` share: the page around a line. Close
-    /// shades count as one, so the soft edge of a letter does not win.
-    static func common(_ samples: [UInt32]) -> UInt32? {
-        var count: [UInt32: Int] = [:]
-        for s in samples { count[s & 0xF8F8F8, default: 0] += 1 }
-        guard let best = count.max(by: { ($0.value, $0.key) < ($1.value, $1.key) })?.key else { return nil }
-        return samples.first { $0 & 0xF8F8F8 == best }
-    }
 }
 
 /// A script laid out in time: every move has its start and its end, so
@@ -110,6 +98,8 @@ struct Play {
         var face = 0.0
         var pose = M.Pose()
         var t = 0.0
+        /// Its size, in play sizes: bigger as it leaves its edge and comes back.
+        var scale = 1.0
         /// What is covered with the page's colour, and which colour.
         var gone: [(rect: P.Rect, paper: UInt32)] = []
         /// The cloth, while it wipes.
@@ -124,6 +114,8 @@ struct Play {
     let size: P.Point
     private(set) var moves: [Move] = []
     private(set) var cuts: [P.Cut] = []
+    /// The jump that takes it back to its place, if the script has one.
+    private(set) var back: Int?
     var duration: Double { moves.last?.end ?? 0 }
 
     /// `start` is where its feet are when play begins. Steps that name a
@@ -223,6 +215,10 @@ struct Play {
             case .rest(let seconds):
                 let m = add(.rest, to: at, max(seconds, 0))
                 list.append(m); now = m.end
+            case .home:
+                guard at != start else { continue }
+                back = list.count
+                reach(start, into: &list)
             }
         }
         moves = list
@@ -232,7 +228,7 @@ struct Play {
     func frame(at t: Double) -> Frame {
         guard let i = moves.lastIndex(where: { $0.start <= t }) else { return Frame(done: true) }
         let m = moves[i], p = M.span(t, m.start, m.end)
-        var f = Frame(t: t, done: t >= duration)
+        var f = Frame(t: t, scale: scale(at: t), done: t >= duration)
 
         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)