@forsion/tangu-computer-use 0.5.8

package/native/linux/bridge-rs/tests/protocol_tests.rs

@@ -0,0 +1,73 @@
+use linux_bridge::protocol::PROTOCOL_VERSION;
+use linux_bridge::{ErrorCode, ProtocolError, Request, Response};
+use serde_json::json;
+use std::io::Write;
+use std::process::{Command, Stdio};
+
+#[test]
+fn protocol_round_trip_matches_other_helpers() {
+    let request: Request = serde_json::from_value(json!({
+        "protocolVersion": PROTOCOL_VERSION,
+        "id": "linux-1",
+        "cmd": "diagnostics",
+        "args": {}
+    }))
+    .unwrap();
+    let response = Response::ok(&request.id, json!({"backend":"at-spi2"}));
+    let value = serde_json::to_value(response).unwrap();
+    assert_eq!(value["protocolVersion"], 4);
+    assert_eq!(value["id"], "linux-1");
+    assert_eq!(value["result"]["backend"], "at-spi2");
+}
+
+#[test]
+fn errors_have_stable_machine_codes() {
+    let response = Response::err(
+        "linux-2",
+        ProtocolError::new("no screenshot", ErrorCode::CaptureFailed),
+    );
+    let value = serde_json::to_value(response).unwrap();
+    assert_eq!(value["ok"], false);
+    assert_eq!(value["error"]["code"], "capture_failed");
+}
+
+#[test]
+fn diagnostics_response_is_flushed_after_stdin_eof() {
+    let mut child = Command::new(env!("CARGO_BIN_EXE_linux-bridge"))
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn linux helper");
+    let request = json!({
+        "protocolVersion": PROTOCOL_VERSION,
+        "id": "eof-1",
+        "cmd": "diagnostics",
+        "args": {}
+    });
+    writeln!(
+        child.stdin.as_mut().expect("piped stdin"),
+        "{}",
+        serde_json::to_string(&request).unwrap()
+    )
+    .expect("write diagnostics request");
+    drop(child.stdin.take());
+
+    let output = child.wait_with_output().expect("helper exits after EOF");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(output.status.success(), "helper failed: {stderr}");
+    assert!(
+        !stderr.contains("panicked"),
+        "helper panicked during shutdown: {stderr}"
+    );
+    let lines = String::from_utf8(output.stdout)
+        .expect("UTF-8 stdout")
+        .lines()
+        .map(str::to_owned)
+        .collect::<Vec<_>>();
+    assert_eq!(lines.len(), 1, "expected one response: {lines:?}");
+    let response: serde_json::Value = serde_json::from_str(&lines[0]).expect("valid JSON response");
+    assert_eq!(response["id"], "eof-1");
+    assert_eq!(response["ok"], true);
+    assert_eq!(response["result"]["protocolVersion"], PROTOCOL_VERSION);
+}

package/native/macos/agent_cursor.swift

@@ -0,0 +1,184 @@
+import AppKit
+import SwiftUI
+
+/// Visual-only cursor; native action delivery remains authoritative.
+@MainActor
+final class AgentCursor {
+    typealias IdleHideScheduler = @MainActor (@escaping @MainActor () -> Void) -> Task<Void, Never>
+
+    static let shared = AgentCursor(scheduleIdleHide: scheduleDefaultIdleHide)
+
+    private var overlay: AgentCursorOverlayWindow?
+    private var idleHideTask: Task<Void, Never>?
+    private var idleGeneration: UInt = 0
+    private let scheduleIdleHide: IdleHideScheduler
+
+    init(scheduleIdleHide: @escaping IdleHideScheduler) {
+        self.scheduleIdleHide = scheduleIdleHide
+    }
+
+    /// `above` 这个标签是上游的,但**跨进程的相对排序已经做不到了**(见下面被删掉的那行),
+    /// 现在完全靠 window level 置顶。参数名留成 `_` 以免有人以为传进来的窗口号还起作用。
+    func animate(to point: CGPoint, above _: UInt32) {
+        idleHideTask?.cancel()
+        idleHideTask = nil
+        idleGeneration &+= 1
+
+        let window = ensureWindow()
+        // Tangu 补丁:覆盖层必须横跨**所有**屏幕,并且每次都重新对齐 —— 显示器可能中途插拔/改摆位。
+        // 上游只开主屏那么大(见 ensureWindow),于是副屏上的点击把光标画到了覆盖层之外 = 用户看不见,
+        // 报上来就是"辅助鼠标还是没有出现"。渲染器吃的是画布局部坐标,所以点也要跟着换算。
+        let bounds = Self.overlayBounds()
+        if window.frame != bounds.union { window.setFrame(bounds.union, display: false) }
+        if !window.isVisible { window.orderFrontRegardless() }
+        // ⚠️上游这里是 window.order(.above, relativeTo: Int(windowId)) —— 对**别的进程**的 window number
+        // 是空操作(实测:窗口既不上移也不消失),它只在同一 App 自己的窗口之间有意义。
+        // 跨进程置顶只能靠 window level,见 AgentCursorOverlayWindow.init。
+
+        let local = OverlayGeometry.canvasPoint(point, union: bounds.union, primaryHeight: bounds.primaryHeight)
+        let renderer = AgentCursorRenderer.shared
+        if renderer.position.x < -100 {
+            let frame = CGRect(origin: .zero, size: bounds.union.size)
+            renderer.setInitialPosition(CGPoint(
+                x: min(max(local.x - 140, frame.minX + 2), frame.maxX - 2),
+                y: min(max(local.y - 140, frame.minY + 2), frame.maxY - 2)
+            ))
+        }
+        renderer.moveTo(point: local)
+
+        let generation = idleGeneration
+        idleHideTask = scheduleIdleHide { [weak self, weak window] in
+            guard let self, let window else { return }
+            guard generation == idleGeneration, self.overlay === window else { return }
+
+            renderer.cancelAnimation()
+            window.orderOut(nil)
+            window.contentView = nil
+            window.close()
+            overlay = nil
+            idleHideTask = nil
+        }
+    }
+
+    private static func scheduleDefaultIdleHide(_ hide: @escaping @MainActor () -> Void) -> Task<Void, Never> {
+        Task { @MainActor in
+            try? await Task.sleep(for: .seconds(8))
+            guard !Task.isCancelled else { return }
+            hide()
+        }
+    }
+
+    /// 所有屏幕的并集 + 主屏高度(全局 CG 坐标换算要用)。没有屏幕时退化成零矩形。
+    static func overlayBounds() -> (union: CGRect, primaryHeight: CGFloat) {
+        let frames = NSScreen.screens.map(\.frame)
+        let union = OverlayGeometry.union(of: frames)
+        // ⚠️主屏 = frame 原点在 (0,0) 的那块(全局 CG 坐标的原点就定在它的左上角),**不是** NSScreen.main
+        // (那是"当前有 key window 的那块",会跟着焦点跑)、也不保证是 screens.first。
+        let primary = NSScreen.screens.first { $0.frame.origin == .zero } ?? NSScreen.screens.first
+        return (union.isNull ? .zero : union, primary?.frame.height ?? union.height)
+    }
+
+    private func ensureWindow() -> AgentCursorOverlayWindow {
+        if let overlay { return overlay }
+        let window = AgentCursorOverlayWindow(
+            contentRect: Self.overlayBounds().union,
+            styleMask: .borderless,
+            backing: .buffered,
+            defer: false
+        )
+        window.contentView = NSHostingView(rootView: AgentCursorView())
+        overlay = window
+        return window
+    }
+}
+
+/// Click-through overlay spanning every display; can never take focus.
+private final class AgentCursorOverlayWindow: NSWindow {
+    override var canBecomeKey: Bool { false }
+    override var canBecomeMain: Bool { false }
+
+    override init(contentRect: NSRect, styleMask: NSWindow.StyleMask, backing: NSWindow.BackingStoreType, defer flag: Bool) {
+        super.init(contentRect: contentRect, styleMask: styleMask, backing: backing, defer: flag)
+        isOpaque = false
+        backgroundColor = .clear
+        hasShadow = false
+        ignoresMouseEvents = true
+        // Tangu 补丁:跨进程置顶只能靠 level(order(.above, relativeTo: 外部窗口号) 是空操作)。
+        // 取「能盖住 agent 会碰到的一切」的**最低**档:比光效(.floating=3)高,比目标 App 自己弹的
+        // 菜单(.popUpMenu=101)高一档 —— 指针指到哪儿是最关键的信息,菜单项被点时尤其不能被挡。
+        // ⚠️别调到 .screenSaver(1000):那会连屏保、系统警告一起盖住,而光标最长要停留 8 秒。
+        level = NSWindow.Level(rawValue: NSWindow.Level.popUpMenu.rawValue + 1)
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        isReleasedWhenClosed = false
+        hidesOnDeactivate = false
+    }
+}
+
+@MainActor
+private struct AgentCursorView: View {
+    @Bindable private var renderer = AgentCursorRenderer.shared
+
+    var body: some View {
+        TimelineView(.animation(minimumInterval: 1.0 / 120.0, paused: !renderer.isAnimating)) { context in
+            Canvas { graphics, _ in
+                renderer.tick(now: context.date.timeIntervalSinceReferenceDate)
+                drawCursor(in: graphics)
+            }
+            .ignoresSafeArea()
+            .allowsHitTesting(false)
+        }
+    }
+
+    private func drawCursor(in graphics: GraphicsContext) {
+        let point = renderer.position
+        guard point.x > -100 else { return }
+
+        let bloom = Color(nsColor: NSColor(red: 1, green: 0x78 / 255, blue: 0x18 / 255, alpha: 1))
+        let radius: CGFloat = 22
+        graphics.fill(
+            Path(ellipseIn: CGRect(x: point.x - radius, y: point.y - radius, width: radius * 2, height: radius * 2)),
+            with: .radialGradient(
+                Gradient(colors: [bloom.opacity(0.55), bloom.opacity(0.15), bloom.opacity(0)]),
+                center: point,
+                startRadius: 0,
+                endRadius: radius
+            )
+        )
+
+        let points = [
+            CGPoint(x: 14, y: 0),
+            CGPoint(x: -8, y: -9),
+            CGPoint(x: -3, y: 0),
+            CGPoint(x: -8, y: 9),
+        ]
+        var shape = Path()
+        for index in points.indices {
+            let previous = points[(index + points.count - 1) % points.count]
+            let current = points[index]
+            let next = points[(index + 1) % points.count]
+            let entry = CGPoint(x: current.x + (previous.x - current.x) * 0.16, y: current.y + (previous.y - current.y) * 0.16)
+            let exit = CGPoint(x: current.x + (next.x - current.x) * 0.16, y: current.y + (next.y - current.y) * 0.16)
+            if index == points.startIndex { shape.move(to: entry) } else { shape.addLine(to: entry) }
+            shape.addQuadCurve(to: exit, control: current)
+        }
+        shape.closeSubpath()
+
+        let transformed = shape.applying(
+            CGAffineTransform(translationX: point.x, y: point.y)
+                .rotated(by: CGFloat(renderer.heading + .pi))
+        )
+        graphics.fill(
+            transformed,
+            with: .linearGradient(
+                Gradient(colors: [
+                    Color(red: 1, green: 0xD0 / 255, blue: 0x76 / 255),
+                    Color(red: 1, green: 0x78 / 255, blue: 0x18 / 255),
+                    Color(red: 0xE8 / 255, green: 0x4A / 255, blue: 0x0C / 255),
+                ]),
+                startPoint: CGPoint(x: point.x + 14, y: point.y - 9),
+                endPoint: CGPoint(x: point.x - 8, y: point.y + 9)
+            )
+        )
+        graphics.stroke(transformed, with: .color(.white), lineWidth: 2)
+    }
+}

package/native/macos/agent_cursor_motion.swift

@@ -0,0 +1,252 @@
+import CoreGraphics
+import Foundation
+import Observation
+
+/// Main-actor Dubins-path animation state consumed by the SwiftUI overlay.
+@Observable
+@MainActor
+final class AgentCursorRenderer {
+    static let shared = AgentCursorRenderer()
+
+    private(set) var position = CGPoint(x: -200, y: -200)
+    private(set) var heading: Double = .pi / 4
+    private(set) var isAnimating = false
+
+    private var path: PlannedPath?
+    private var spring: Spring?
+    private var distanceSoFar: Double = 0
+    private var lastFrameTime: CFTimeInterval?
+    private var springTarget: (point: CGPoint, heading: Double)?
+
+    func moveTo(point clickPoint: CGPoint) {
+        let endAngle = Double.pi / 4
+        let targetPoint = CGPoint(
+            x: clickPoint.x + CGFloat(cos(endAngle) * 16),
+            y: clickPoint.y + CGFloat(sin(endAngle) * 16)
+        )
+        path = planPath(
+            x0: Double(position.x), y0: Double(position.y), th0: heading + .pi,
+            x1: Double(targetPoint.x), y1: Double(targetPoint.y), th1: endAngle + .pi,
+            R: 80, endVisualHeading: endAngle, targetPoint: targetPoint)
+        spring = nil
+        springTarget = nil
+        distanceSoFar = 0
+        lastFrameTime = nil
+        isAnimating = true
+    }
+
+    func setInitialPosition(_ point: CGPoint) {
+        position = point
+        cancelAnimation()
+    }
+
+    func cancelAnimation() {
+        path = nil
+        spring = nil
+        springTarget = nil
+        distanceSoFar = 0
+        lastFrameTime = nil
+        isAnimating = false
+    }
+
+    func tick(now: CFTimeInterval) {
+        guard isAnimating else { return }
+        let previous = lastFrameTime ?? now
+        let dt = min(0.05, now - previous)
+        lastFrameTime = now
+
+        if let path {
+            let progress = min(1.0, distanceSoFar / max(path.length, 1))
+            let profile = 16 * progress * progress * (1 - progress) * (1 - progress)
+            let minimumSpeed = progress < 0.5 ? 300.0 : 200.0
+            let speed = minimumSpeed + (900 - minimumSpeed) * profile
+            distanceSoFar += speed * dt
+
+            if distanceSoFar >= path.length {
+                let endState = path.sample(at: path.length)
+                spring = Spring(
+                    ox: 0,
+                    oy: 0,
+                    vx: cos(endState.heading) * speed * 0.8,
+                    vy: sin(endState.heading) * speed * 0.8
+                )
+                springTarget = (path.targetPoint, path.endVisualHeading)
+                position = path.targetPoint
+                heading = path.endVisualHeading
+                self.path = nil
+                distanceSoFar = 0
+            } else {
+                let state = path.sample(at: distanceSoFar)
+                position = CGPoint(x: state.x, y: state.y)
+                heading = rotateToward(current: heading, desired: state.heading + .pi, maxStep: 14 * dt)
+            }
+        } else if var spring, let target = springTarget {
+            let substep = dt / 4
+            for _ in 0..<4 {
+                spring.vx += (-400 * spring.ox - 17 * spring.vx) * substep
+                spring.vy += (-400 * spring.oy - 17 * spring.vy) * substep
+                spring.ox += spring.vx * substep
+                spring.oy += spring.vy * substep
+            }
+            position = CGPoint(x: target.point.x + CGFloat(spring.ox), y: target.point.y + CGFloat(spring.oy))
+            heading = target.heading
+            if hypot(spring.ox, spring.oy) < 0.3 && hypot(spring.vx, spring.vy) < 2 {
+                position = target.point
+                self.spring = nil
+                springTarget = nil
+                lastFrameTime = nil
+                isAnimating = false
+            } else {
+                self.spring = spring
+            }
+        }
+    }
+
+    private func rotateToward(current: Double, desired: Double, maxStep: Double) -> Double {
+        var difference = desired - current
+        while difference > .pi { difference -= 2 * .pi }
+        while difference < -.pi { difference += 2 * .pi }
+        return current + max(-maxStep, min(maxStep, difference))
+    }
+}
+
+private struct Spring { var ox, oy, vx, vy: Double }
+
+struct DubinsPlannedPath {
+    enum Kind { case dubins, linear }
+    let kind: Kind
+    let length: Double
+    let endVisualHeading: Double
+    let targetPoint: CGPoint
+    let x0, y0, th0, R, seg1, seg2, seg3: Double
+    let types: [Character]
+    let x1, y1, th1: Double
+
+    struct State { let x, y, heading: Double }
+
+    func sample(at s: Double) -> State {
+        switch kind { case .linear: return sampleLinear(s); case .dubins: return sampleDubins(s) }
+    }
+
+    private func sampleLinear(_ s: Double) -> State {
+        let u = max(0, min(1, s / length))
+        var diff = th1 - th0
+        while diff > .pi  { diff -= 2 * .pi }
+        while diff < -.pi { diff += 2 * .pi }
+        return State(x: x0 + (x1 - x0) * u, y: y0 + (y1 - y0) * u, heading: th0 + diff * u)
+    }
+
+    private func sampleDubins(_ sIn: Double) -> State {
+        guard sIn > 0 else { return State(x: x0, y: y0, heading: th0) }
+        let L1 = seg1 * R, L2 = seg2 * R, L3 = seg3 * R
+        let s = min(sIn, L1 + L2 + L3)
+        var x = x0, y = y0, th = th0
+
+        func advance(length L: Double, type: Character) {
+            if type == "S" { x += cos(th) * L; y += sin(th) * L }
+            else {
+                let dth = L / R * (type == "L" ? 1.0 : -1.0)
+                let perp: Double = (type == "L") ? .pi / 2 : -.pi / 2
+                let cx = x + cos(th + perp) * R, cy = y + sin(th + perp) * R
+                let ang = atan2(y - cy, x - cx)
+                x = cx + cos(ang + dth) * R; y = cy + sin(ang + dth) * R; th += dth
+            }
+        }
+        if s <= L1 { advance(length: s, type: types[0]); return State(x: x, y: y, heading: th) }
+        advance(length: L1, type: types[0])
+        if s <= L1 + L2 { advance(length: s - L1, type: types[1]); return State(x: x, y: y, heading: th) }
+        advance(length: L2, type: types[1])
+        advance(length: s - L1 - L2, type: types[2])
+        return State(x: x, y: y, heading: th)
+    }
+}
+
+private typealias PlannedPath = DubinsPlannedPath
+
+private func mod2pi(_ x: Double) -> Double {
+    let tau = 2 * Double.pi; let r = x - tau * floor(x / tau); return r < 0 ? r + tau : r
+}
+
+private struct DubinsSolution { let t, p, q: Double; let types: [Character]; var length: Double { t + p + q } }
+
+private func dubinsLSL(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let tmp0 = d + sin(a) - sin(b)
+    let p2 = 2 + d * d - 2 * cos(a - b) + 2 * d * (sin(a) - sin(b))
+    guard p2 >= 0 else { return nil }
+    let tmp1 = atan2(cos(b) - cos(a), tmp0)
+    return DubinsSolution(t: mod2pi(-a + tmp1), p: sqrt(p2), q: mod2pi(b - tmp1), types: ["L","S","L"])
+}
+private func dubinsRSR(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let tmp0 = d - sin(a) + sin(b)
+    let p2 = 2 + d * d - 2 * cos(a - b) + 2 * d * (sin(b) - sin(a))
+    guard p2 >= 0 else { return nil }
+    let tmp1 = atan2(cos(a) - cos(b), tmp0)
+    return DubinsSolution(t: mod2pi(a - tmp1), p: sqrt(p2), q: mod2pi(-b + tmp1), types: ["R","S","R"])
+}
+private func dubinsLSR(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let p2 = -2 + d * d + 2 * cos(a - b) + 2 * d * (sin(a) + sin(b))
+    guard p2 >= 0 else { return nil }
+    let p = sqrt(p2)
+    let tmp1 = atan2(-cos(a) - cos(b), d + sin(a) + sin(b)) - atan2(-2, p)
+    return DubinsSolution(t: mod2pi(-a + tmp1), p: p, q: mod2pi(-mod2pi(b) + tmp1), types: ["L","S","R"])
+}
+private func dubinsRSL(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let p2 = d * d - 2 + 2 * cos(a - b) - 2 * d * (sin(a) + sin(b))
+    guard p2 >= 0 else { return nil }
+    let p = sqrt(p2)
+    let tmp1 = atan2(cos(a) + cos(b), d - sin(a) - sin(b)) - atan2(2, p)
+    return DubinsSolution(t: mod2pi(a - tmp1), p: p, q: mod2pi(b - tmp1), types: ["R","S","L"])
+}
+private func dubinsRLR(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let tmp = (6 - d * d + 2 * cos(a - b) + 2 * d * (sin(a) - sin(b))) / 8
+    guard abs(tmp) <= 1 else { return nil }
+    let p = mod2pi(2 * .pi - acos(tmp))
+    let t = mod2pi(a - atan2(cos(a) - cos(b), d - sin(a) + sin(b)) + p / 2)
+    return DubinsSolution(t: t, p: p, q: mod2pi(a - b - t + p), types: ["R","L","R"])
+}
+private func dubinsLRL(_ d: Double, _ a: Double, _ b: Double) -> DubinsSolution? {
+    let tmp = (6 - d * d + 2 * cos(a - b) + 2 * d * (sin(b) - sin(a))) / 8
+    guard abs(tmp) <= 1 else { return nil }
+    let p = mod2pi(2 * .pi - acos(tmp))
+    let t = mod2pi(-a + atan2(-cos(a) + cos(b), d + sin(a) - sin(b)) + p / 2)
+    return DubinsSolution(t: t, p: p, q: mod2pi(mod2pi(b) - a - t + p), types: ["L","R","L"])
+}
+
+private func planPath(x0: Double, y0: Double, th0: Double,
+                      x1: Double, y1: Double, th1: Double,
+                      R: Double, endVisualHeading: Double,
+                      targetPoint: CGPoint) -> PlannedPath {
+    if let p = planDubins(x0: x0, y0: y0, th0: th0, x1: x1, y1: y1, th1: th1,
+                          R: R, endVisualHeading: endVisualHeading, targetPoint: targetPoint) {
+        return p
+    }
+    let D = max(1, hypot(x1 - x0, y1 - y0))
+    return PlannedPath(kind: .linear, length: D, endVisualHeading: endVisualHeading,
+                       targetPoint: targetPoint, x0: x0, y0: y0, th0: th0, R: R,
+                       seg1: 0, seg2: 0, seg3: 0, types: [], x1: x1, y1: y1, th1: th1)
+}
+
+private func planDubins(x0: Double, y0: Double, th0: Double,
+                        x1: Double, y1: Double, th1: Double,
+                        R: Double, endVisualHeading: Double,
+                        targetPoint: CGPoint) -> PlannedPath? {
+    let dx = x1 - x0, dy = y1 - y0, D = hypot(dx, dy)
+    guard D > 0.5 else { return nil }
+    let d = D / R, theta = mod2pi(atan2(dy, dx))
+    let a = mod2pi(th0 - theta), b = mod2pi(th1 - theta)
+    let solvers: [(Double, Double, Double) -> DubinsSolution?] = [
+        dubinsLSL, dubinsRSR, dubinsLSR, dubinsRSL, dubinsRLR, dubinsLRL,
+    ]
+    var best: DubinsSolution?; var bestLen = Double.infinity
+    for s in solvers {
+        if let sol = s(d, a, b), sol.length.isFinite, sol.length >= 0, sol.length < bestLen {
+            bestLen = sol.length; best = sol
+        }
+    }
+    guard let b = best else { return nil }
+    return PlannedPath(kind: .dubins, length: (b.t + b.p + b.q) * R,
+                       endVisualHeading: endVisualHeading, targetPoint: targetPoint,
+                       x0: x0, y0: y0, th0: th0, R: R,
+                       seg1: b.t, seg2: b.p, seg3: b.q, types: b.types,
+                       x1: x1, y1: y1, th1: th1)
+}

package/native/macos/agent_cursor_tests.swift

@@ -0,0 +1,128 @@
+import AppKit
+import CoreGraphics
+import Foundation
+
+@main
+struct AgentCursorTests {
+    @MainActor
+    static func main() {
+        testMotionLifecycle()
+        testOverlayLifecycle()
+    }
+
+    @MainActor
+    private static func testMotionLifecycle() {
+        let renderer = AgentCursorRenderer()
+        renderer.setInitialPosition(CGPoint(x: 100, y: 100))
+
+        expect(!renderer.isAnimating, "renderer should start idle")
+
+        renderer.moveTo(point: CGPoint(x: 500, y: 400))
+        expect(renderer.isAnimating, "renderer should become active when motion starts")
+
+        var now: CFTimeInterval = 0
+        for _ in 0..<12_000 where renderer.isAnimating {
+            now += 1.0 / 120.0
+            renderer.tick(now: now)
+        }
+
+        expect(!renderer.isAnimating, "renderer should become idle after motion settles")
+
+        renderer.moveTo(point: CGPoint(x: 800, y: 600))
+        renderer.tick(now: now + 1.0 / 120.0)
+        let stoppedPosition = renderer.position
+
+        renderer.cancelAnimation()
+        expect(!renderer.isAnimating, "cancelled motion should become idle")
+
+        renderer.tick(now: now + 1)
+        expect(renderer.position == stoppedPosition, "idle ticks should not change the cancelled position")
+
+        renderer.setInitialPosition(CGPoint(x: 100, y: 100))
+        renderer.moveTo(point: CGPoint(x: 300, y: 300))
+        for _ in 0..<12 {
+            now += 1.0 / 120.0
+            renderer.tick(now: now)
+        }
+        let latestTarget = CGPoint(x: 900, y: 700)
+        renderer.moveTo(point: latestTarget)
+        for _ in 0..<12_000 where renderer.isAnimating {
+            now += 1.0 / 120.0
+            renderer.tick(now: now)
+        }
+
+        let endpointOffset = CGFloat(cos(Double.pi / 4) * 16)
+        let expectedPosition = CGPoint(
+            x: latestTarget.x + endpointOffset,
+            y: latestTarget.y + endpointOffset
+        )
+        expect(distance(renderer.position, expectedPosition) < 0.001, "latest target should supersede in-flight motion")
+    }
+
+    @MainActor
+    private static func testOverlayLifecycle() {
+        let application = NSApplication.shared
+        let existingWindows = Set(application.windows.map(ObjectIdentifier.init))
+        let scheduler = ManualIdleHideScheduler()
+        let cursor = AgentCursor(scheduleIdleHide: scheduler.schedule)
+
+        cursor.animate(to: CGPoint(x: 300, y: 300), above: 0)
+        guard let firstWindow = application.windows.first(where: {
+            !existingWindows.contains(ObjectIdentifier($0)) && $0.isVisible
+        }) else {
+            fail("first action should create a visible overlay")
+        }
+
+        cursor.animate(to: CGPoint(x: 500, y: 500), above: 0)
+        expect(scheduler.count == 2, "each action should replace the idle timeout")
+
+        scheduler.fire(0)
+        expect(firstWindow.isVisible, "a stale timeout should not hide the current overlay")
+        expect(firstWindow.contentView != nil, "a stale timeout should not release the current view")
+
+        scheduler.fire(1)
+        expect(!AgentCursorRenderer.shared.isAnimating, "the current timeout should stop rendering")
+        expect(!firstWindow.isVisible, "the current timeout should hide the overlay")
+        expect(firstWindow.contentView == nil, "the current timeout should release the view tree")
+
+        cursor.animate(to: CGPoint(x: 700, y: 700), above: 0)
+        guard let recreatedWindow = application.windows.first(where: {
+            !existingWindows.contains(ObjectIdentifier($0)) && $0 !== firstWindow && $0.isVisible
+        }) else {
+            fail("a later action should recreate the overlay")
+        }
+
+        scheduler.fire(2)
+        expect(!recreatedWindow.isVisible, "the recreated overlay should retain the idle lifecycle")
+        expect(recreatedWindow.contentView == nil, "the recreated overlay should release its view tree")
+    }
+
+    private static func expect(_ condition: @autoclosure () -> Bool, _ message: String) {
+        guard condition() else { fail(message) }
+    }
+
+    private static func fail(_ message: String) -> Never {
+        FileHandle.standardError.write(Data("FAIL: \(message)\n".utf8))
+        exit(1)
+    }
+
+    private static func distance(_ lhs: CGPoint, _ rhs: CGPoint) -> CGFloat {
+        hypot(lhs.x - rhs.x, lhs.y - rhs.y)
+    }
+}
+
+@MainActor
+private final class ManualIdleHideScheduler {
+    private var actions: [@MainActor () -> Void] = []
+
+    var count: Int { actions.count }
+
+    func schedule(_ action: @escaping @MainActor () -> Void) -> Task<Void, Never> {
+        actions.append(action)
+        return Task {}
+    }
+
+    func fire(_ index: Int) {
+        actions[index]()
+    }
+}