Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

30.0 KB
Raw Blame
#!/usr/bin/env python3
"""Opt-in end-to-end test of the Omarchy image (libs/images/omarchy).

Boots the image through the cua CLI and checks that Omarchy's own Cua Driver
integration drives the Hyprland desktop:

* SDK/CLI path (``cua do``, cua-spacesd, input through the cua-hyprland-plugin):
  launch a terminal, click it (focus), type a command into it (the file it
  writes proves the keystrokes), and a Hyprland window action (resize).
* cua-driver MCP, twice: cua-spacesd's Streamable HTTP ``/mcp`` (``cua sb mcp``)
  and Omarchy's built-in ``cua-driver mcp`` (cua-driver-bin, over stdio in the
  guest), including a click through the built-in driver.
* The cua-driver cursor overlay, from both drivers: screenshots taken through
  the SDK right after each driver's pointer action (saved to --evidence), and
  the overlay's coloured arrow found in the pixels next to the click.
* Stream viewer input (``cua sb stream-probe``, a media session like the
  Spaces apps'): on the desktop stream and on a window stream, a click, typing
  and a scroll sent on the media socket are acknowledged as delivered and
  have their effect (focus, the typed file, the terminal's text moving). The
  viewer's click shows one cursor, the viewer's own: no agent participant
  joins presence for it and no agent cursor overlay is drawn at it.
* Stream frame rate while a terminal rewrites a counter nonstop: a window
  stream of a small window, asserted against --min-fps (the Omarchy release
  gate passes 12: Hyprland renders in software on a GPU-less KVM runner and
  holds 13-16 fps under this load; 0, the default, only reports it, for
  emulated guests), and the desktop
  stream under that load and under a scrolling terminal (reported; software
  rendering bounds it), each with Hyprland's and cua-spacesd's CPU and
  cua-spacesd's capture and encoder counters.

Opt-in: runs only with CUA_E2E_OMARCHY=1 (it starts a VM). Standard library only.

    CUA_E2E_OMARCHY=1 tests/e2e/omarchy/omarchy_e2e.py --disk ~/.cache/cua-images/omarchy/amd64/disk.img \\
        [--cua PATH] [--evidence DIR]
    # or against a machine that already runs the image:
    CUA_E2E_OMARCHY=1 tests/e2e/omarchy/omarchy_e2e.py --direct 127.0.0.1:3211 --token TOKEN
"""

from __future__ import annotations

import argparse
import json
import os
import secrets
import shlex
import shutil
import struct
import subprocess
import sys
import threading
import time
import zlib
from pathlib import Path

CUA = "cua"
NAME = ""
MIN_FPS = 0.0
RESULTS: list[tuple[str, bool, str]] = []


def log(msg: str) -> None:
    print(f"[omarchy-e2e {time.strftime('%H:%M:%S')}] {msg}", flush=True)


def cua(*args: str, timeout: float = 300, check: bool = True, stdin: str | None = None) -> str:
    cmd = [CUA, *args]
    p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, input=stdin)
    if check and p.returncode != 0:
        raise RuntimeError(f"{shlex.join(cmd)} -> {p.returncode}: {p.stderr.strip()[-800:]}")
    return p.stdout


def sh(command: str, timeout: float = 120, check: bool = True) -> str:
    """Run a shell line in the guest (cua sb exec, as the desktop user)."""
    return cua("sb", "exec", NAME, command, timeout=timeout, check=check)


def poll(what: str, fn, timeout: float, every: float = 3.0):
    deadline = time.monotonic() + timeout
    last: object = None
    while time.monotonic() < deadline:
        try:
            last = fn()
            if last:
                return last
        except Exception as e:  # noqa: BLE001 - keep polling; report the last error
            last = e
        time.sleep(every)
    raise TimeoutError(f"{what}: gave up after {timeout:.0f}s (last: {last!r})")


def check(name: str, fn) -> None:
    t0 = time.monotonic()
    try:
        detail = fn() or ""
        RESULTS.append((name, True, str(detail)))
        log(f"PASS {name} ({time.monotonic() - t0:.0f}s) {detail}")
    except Exception as e:  # noqa: BLE001
        RESULTS.append((name, False, str(e)))
        log(f"FAIL {name}: {e}")


def clients() -> list[dict]:
    return json.loads(sh("hyprctl -j clients"))


def window(app_id: str) -> dict | None:
    """The Hyprland client with this app id (class): shells rewrite titles."""
    return next((c for c in clients() if c.get("class") == app_id), None)


def active_class() -> str:
    return json.loads(sh("hyprctl -j activewindow") or "{}").get("class", "")


def target_of(w: dict) -> str:
    """The cua window id of a Hyprland client (matched by geometry)."""
    for line in cua("do", "window", "ls").splitlines():
        parts = line.split()
        if len(parts) >= 2 and parts[0].startswith("target-"):
            box = line[line.rfind("[") + 1 : line.rfind("]")].split(",")
            if [int(float(v)) for v in box[:2]] == w["at"]:
                return parts[0]
    raise RuntimeError(f"no cua window at {w['at']}")


def shot(evidence: Path, name: str) -> Path:
    out = evidence / f"{name}.png"
    for attempt in range(3):  # a busy (or emulated) guest can miss one frame deadline
        try:
            cua("do", "screenshot", "--save", str(out), timeout=120)
            return out
        except RuntimeError:
            if attempt == 2:
                raise
            time.sleep(3)
    return out


def read_png_rgb(path: Path) -> tuple[int, int, list[bytearray]]:
    """Decode an 8-bit RGB/RGBA non-interlaced PNG (what screenshots are) to RGB rows."""
    data = path.read_bytes()
    assert data[:8] == b"\x89PNG\r\n\x1a\n", "not a PNG"
    pos, idat, width = 8, b"", 0
    height = depth = color = interlace = 0
    while pos < len(data):
        (length,) = struct.unpack(">I", data[pos : pos + 4])
        kind, body = data[pos + 4 : pos + 8], data[pos + 8 : pos + 8 + length]
        pos += 12 + length
        if kind == b"IHDR":
            width, height, depth, color, _, _, interlace = struct.unpack(">IIBBBBB", body)
        elif kind == b"IDAT":
            idat += body
        elif kind == b"IEND":
            break
    assert depth == 8 and color in (2, 6) and not interlace, (depth, color, interlace)
    bpp = 3 if color == 2 else 4
    raw, stride, rows = zlib.decompress(idat), width * bpp, []
    prev = bytearray(stride)
    for y in range(height):
        f, line = raw[y * (stride + 1)], bytearray(
            raw[y * (stride + 1) + 1 : (y + 1) * (stride + 1)]
        )
        for i in range(stride):
            a = line[i - bpp] if i >= bpp else 0
            b, c = prev[i], prev[i - bpp] if i >= bpp else 0
            if f == 1:
                line[i] = (line[i] + a) & 255
            elif f == 2:
                line[i] = (line[i] + b) & 255
            elif f == 3:
                line[i] = (line[i] + (a + b) // 2) & 255
            elif f == 4:
                pa, pb, pc = abs(b - c), abs(a - c), abs(a + b - 2 * c)
                line[i] = (line[i] + (a if pa <= pb and pa <= pc else b if pb <= pc else c)) & 255
        rows.append(bytearray(v for i, v in enumerate(line) if bpp == 3 or i % 4 != 3))
        prev = line
    return width, height, rows


def overlay_pixels_near(path: Path, x: float, y: float, screen_w: int, radius: int = 90) -> int:
    """Saturated pixels (the agent cursor's coloured arrow and badge) within
    `radius` screen points of (x, y). Omarchy's desktop, terminals and pointer
    are greyscale, so these are the overlay's."""
    width, height, rows = read_png_rgb(path)
    scale = width / screen_w
    cx, cy, r = int(x * scale), int(y * scale), int(radius * scale)
    count = 0
    for py in range(max(0, cy - r), min(height, cy + r)):
        row = rows[py]
        for px in range(max(0, cx - r), min(width, cx + r)):
            red, green, blue = row[3 * px : 3 * px + 3]
            if max(red, green, blue) - min(red, green, blue) > 90 and max(red, green, blue) > 120:
                count += 1
    return count


def overlay_shot(
    evidence: Path, name: str, x: float, y: float, timeout: float = 30, image_coords: bool = False
) -> str:
    """Screenshot until the agent cursor is drawn at (x, y), in desktop points
    or, with image_coords, in the screenshot's pixels (what `cua do click`
    takes). Pointer actions wait for the glide, but an emulated guest paints
    slowly, so allow a few frames to land."""
    deadline, overlay = time.monotonic() + timeout, 0
    for _ in range(20):
        path = shot(evidence, name)
        screen_w = read_png_rgb(path)[0] if image_coords else 1280
        overlay = overlay_pixels_near(path, x, y, screen_w=screen_w)
        if overlay >= 40 or time.monotonic() >= deadline:
            break
        time.sleep(2)
    assert overlay >= 40, f"no agent cursor overlay near ({x},{y}) ({overlay} coloured pixels)"
    return f"overlay {overlay} coloured px"


def main() -> int:
    global CUA, NAME, MIN_FPS
    ap = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    ap.add_argument(
        "--disk", help="omarchy disk.img to boot with `cua sb create vm:<disk> --on local`"
    )
    ap.add_argument(
        "--image", help="image ref to create instead (e.g. ghcr.io/trycua/omarchy:edge)"
    )
    ap.add_argument("--direct", help="host:port of a running image's cua-spacesd instead of --disk")
    ap.add_argument("--token", help="spacesd token (default: generated for --disk)")
    ap.add_argument("--cua", default=shutil.which("cua") or "cua")
    ap.add_argument("--evidence", default="omarchy-e2e-evidence")
    ap.add_argument("--boot-timeout", type=float, default=2400)
    ap.add_argument("--keep", action="store_true", help="leave the sandbox running")
    ap.add_argument("--reuse", help="run the checks against this existing sandbox name")
    ap.add_argument(
        "--min-fps",
        type=float,
        default=0,
        help="desktop stream fps required under load (0: report only)",
    )
    a = ap.parse_args()
    if os.environ.get("CUA_E2E_OMARCHY") != "1":
        print("skipped: set CUA_E2E_OMARCHY=1 to boot the Omarchy VM", file=sys.stderr)
        return 0
    if not a.reuse and sum(map(bool, (a.disk, a.image, a.direct))) != 1:
        ap.error("pass exactly one of --disk, --image and --direct")
    CUA = a.cua
    MIN_FPS = a.min_fps
    evidence = Path(a.evidence)
    evidence.mkdir(parents=True, exist_ok=True)
    token = a.token or secrets.token_hex(16)
    NAME = f"cua-e2e-omarchy-{secrets.token_hex(3)}"

    if a.reuse:
        NAME = a.reuse
        cua("do", "switch", NAME)
        run_checks(evidence, a.boot_timeout)
        return finish(evidence)
    log(f"creating {NAME}")
    if a.disk or a.image:
        image = a.image or f"vm:{Path(a.disk).resolve()}"
        cua(
            "sb",
            "create",
            image,
            "--on",
            "local",
            "--kind",
            "vm",
            "--name",
            NAME,
            "--cpu",
            "4",
            "--memory",
            "4GB",
            "--port",
            "3211",
            "--wait",
            "tcp:3211",
            "--ready-timeout",
            str(int(a.boot_timeout)),
            "--token",
            token,
            "--env",
            f"CUA_ENV_TOKEN={token}",
            timeout=a.boot_timeout + 300,
        )
    else:
        cua(
            "sb",
            "create",
            "--on",
            f"direct:{a.direct}",
            "--name",
            NAME,
            "--token",
            token,
            timeout=300,
        )
    try:
        cua("do", "switch", NAME)
        run_checks(evidence, a.boot_timeout)
    finally:
        if not a.keep:
            cua("sb", "rm", "--force", NAME, timeout=600, check=False)
    return finish(evidence)


def finish(evidence: Path) -> int:
    ok = all(r[1] for r in RESULTS)
    (evidence / "results.json").write_text(
        json.dumps([{"check": n, "pass": p, "detail": d} for n, p, d in RESULTS], indent=2) + "\n"
    )
    log(f"{sum(r[1] for r in RESULTS)}/{len(RESULTS)} checks passed")
    return 0 if ok and RESULTS else 1


def run_checks(evidence: Path, boot_timeout: float) -> None:
    log("waiting for the Hyprland session")
    poll(
        "Hyprland session",
        lambda: sh(
            'test -S "$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY" && hyprctl -j monitors', check=False
        )
        .strip()
        .startswith("["),
        boot_timeout,
        every=10,
    )

    def facts():
        versions = sh("pacman -Q omarchy-dev cua-driver-bin cua-hyprland-plugin hyprland").strip()
        (evidence / "versions.txt").write_text(versions + "\n")
        status = json.loads(sh("hyprctl -j cua:status"))
        (evidence / "cua-status.json").write_text(json.dumps(status, indent=2) + "\n")
        assert "cua-driver-bin" in versions and "cua-hyprland-plugin" in versions, versions
        return versions.replace("\n", ", ")

    check("omarchy edge packages and loaded cua-hyprland-plugin", facts)

    title = "cua-e2e-foot"  # the terminal's app id

    def launch():
        cua("do", "launch", "foot", "--app-id", title, timeout=120)
        w = poll("foot window", lambda: window(title), 180)
        return f"{w['address']} at {w['at']} size {w['size']}"

    check("SDK launch_app: foot on Hyprland", launch)

    def click():
        w = window(title)
        assert w, "no foot window"
        # Focus another window first, so the click is what focuses the terminal.
        cua("do", "launch", "foot", "--app-id", "cua-e2e-other", timeout=120)
        poll("other focused", lambda: active_class() == "cua-e2e-other", 60, 1)
        w = window(title)
        x, y = w["at"][0] + w["size"][0] // 2, w["at"][1] + w["size"][1] // 2
        cua("do", "click", str(x), str(y))
        overlay = overlay_shot(evidence, "overlay-sdk-click", x, y, image_coords=True)
        focused = poll(
            "foot focused",
            lambda: active_class() == title and f"focused {title} at ({x},{y})",
            30,
            1,
        )
        return f"{focused}; {overlay}"

    check("SDK click focuses the window", click)

    def type_text():
        marker = f"cua-e2e-typed-{secrets.token_hex(3)}"
        cua("do", "type", f"echo {marker} > /tmp/cua-e2e-typed")
        cua("do", "key", "enter")
        got = poll(
            "typed file",
            lambda: sh("cat /tmp/cua-e2e-typed 2>/dev/null", check=False).strip(),
            30,
            1,
        )
        assert got == marker, got
        shot(evidence, "typed")
        return got

    check("SDK type + key into foot", type_text)

    def window_action():
        before = window(title)
        assert before
        cua("do", "window", "maximize", target_of(before))
        after = poll(
            "maximized", lambda: (w := window(title)) and w["size"] != before["size"] and w, 30, 1
        )
        shot(evidence, "window-maximized")
        return f"size {before['size']} -> {after['size']}"

    check("SDK Hyprland window action (maximize)", window_action)

    def spacesd_mcp():
        tools = cua("sb", "mcp", NAME, "env", "tools", timeout=120)
        assert "click" in tools, tools[:400]
        size = cua("sb", "mcp", NAME, "env", "call", "get_screen_size", "{}", timeout=120)
        return f"{len(tools.splitlines())} tool lines; get_screen_size: {size.strip()[:120]}"

    check("cua-driver MCP via cua-spacesd /mcp", spacesd_mcp)

    def builtin_mcp():
        # Omarchy's own cua-driver (cua-driver-bin): its stdio MCP server,
        # piped transparently, lists its tools.
        req = "\n".join(
            json.dumps(m)
            for m in [
                {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                        "protocolVersion": "2025-06-18",
                        "capabilities": {},
                        "clientInfo": {"name": "cua-e2e-omarchy", "version": "1"},
                    },
                },
                {"jsonrpc": "2.0", "method": "notifications/initialized"},
                {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
            ]
        )
        out = sh(
            f"printf '%s\\n' {shlex.quote(req)} | timeout 60 /usr/bin/cua-driver mcp", timeout=120
        )
        lines = [json.loads(line) for line in out.splitlines() if line.startswith("{")]
        tools = next(line for line in lines if line.get("id") == 2)["result"]["tools"]
        names = {t["name"] for t in tools}
        assert "click" in names, sorted(names)[:20]
        return f"/usr/bin/cua-driver mcp: {len(names)} tools"

    check("Omarchy built-in cua-driver MCP (stdio)", builtin_mcp)

    def builtin_click():
        # Omarchy's daemon (cua-driver.service) clicks in desktop coordinates;
        # Hyprland's pointer must end up there, with the daemon's own agent
        # cursor drawn at the click. The call names its session: an anonymous
        # one-shot `cua-driver call` ends its session (and removes its cursor)
        # as soon as it returns, the way an MCP client's session does not.
        x, y = 900, 300
        args = json.dumps({"x": x, "y": y, "scope": "desktop", "session": "cua-e2e-omarchy"})
        out = json.loads(sh(f"/usr/bin/cua-driver call click '{args}'", timeout=120))
        assert "code" not in out, out
        pos = json.loads(sh("hyprctl -j cursorpos"))
        assert (round(pos["x"]), round(pos["y"])) == (x, y), pos
        overlay = overlay_shot(evidence, "builtin-driver-click", x, y)
        # End the session: its cursor hides at once, so the stream checks
        # below see only what a viewer's input draws.
        sh(
            f"/usr/bin/cua-driver call end_session '{json.dumps({'session': 'cua-e2e-omarchy'})}'",
            timeout=60,
            check=False,
        )
        return f"route {out.get('route')}; Hyprland pointer at ({x},{y}); {overlay}"

    check("Omarchy built-in cua-driver click", builtin_click)

    stream_checks(evidence, title)


def probe(evidence: Path, name: str, *args: str, seconds: float = 2) -> dict:
    """`cua sb stream-probe`: a media session like a Spaces viewer's, with
    input sent as interactive_input batches on the media socket. The report
    is saved as evidence."""
    out = cua(
        "sb",
        "stream-probe",
        NAME,
        "--seconds",
        str(seconds),
        "--pings",
        "5",
        "--action-timeout",
        "180",
        *args,
        timeout=1500,
    )
    report = json.loads(out.strip().splitlines()[-1])
    (evidence / f"{name}.json").write_text(json.dumps(report, indent=2) + "\n")
    assert report["width"] and report["height"], report
    assert report["ping"]["answered"] == report["ping"]["sent"], report["ping"]
    refused = [a for a in report["actions"] if "delivered" in a and not a["delivered"]]
    assert not refused, f"input not delivered: {refused}"
    return report


def region_changed(
    before: Path,
    after: Path,
    box: tuple[int, int, int, int],
    skip: tuple[float, float],
    screen_w: int,
) -> int:
    """Pixels that differ inside `box` (x, y, w, h in desktop points) between
    two screenshots, leaving out 120 points around `skip` (where the agent
    cursor is drawn)."""
    wb, hb, a = read_png_rgb(before)
    wa, ha, b = read_png_rgb(after)
    assert (wb, hb) == (wa, ha), "screenshot size changed"
    s = wb / screen_w
    x0, y0, x1, y1 = (
        int(box[0] * s),
        int(box[1] * s),
        int((box[0] + box[2]) * s),
        int((box[1] + box[3]) * s),
    )
    sx, sy, r = skip[0] * s, skip[1] * s, 120 * s
    count = 0
    for py in range(max(0, y0), min(hb, y1)):
        for px in range(max(0, x0), min(wb, x1)):
            if abs(px - sx) < r and abs(py - sy) < r:
                continue
            if max(abs(a[py][3 * px + c] - b[py][3 * px + c]) for c in range(3)) > 40:
                count += 1
    return count


def stream_checks(evidence: Path, title: str) -> None:
    """Input from stream viewers (the Spaces apps and the HTML5 viewer): the
    desktop stream and a window stream each deliver a click, typing and a
    scroll through the media session, and each has a visible effect."""
    mon = json.loads(sh("hyprctl -j monitors"))[0]
    screen = (mon["width"] / mon["scale"], mon["height"] / mon["scale"])

    def norm(x: float, y: float) -> str:
        return f"{x / screen[0]:.4f},{y / screen[1]:.4f}"

    def fill_terminal() -> dict:
        """Numbered lines in the focused terminal, so a scroll moves text."""
        cua("do", "type", "clear; seq 1 400")
        cua("do", "key", "enter")
        time.sleep(3)
        w = window(title)
        assert w
        return w

    def scrolled(name: str, w: dict, scroll_args: list[str], point: tuple[float, float]) -> str:
        before = shot(evidence, f"{name}-before-scroll")
        report = probe(evidence, f"{name}-scroll", *scroll_args)
        time.sleep(2)
        after = shot(evidence, f"{name}-after-scroll")
        n = region_changed(before, after, (*w["at"], *w["size"]), point, int(screen[0]))
        assert n > 500, f"the scroll changed {n} pixels of the terminal"
        return f"ack {report['actions'][0].get('ack_ms')} ms; {n} px changed"

    def desktop_click():
        # The window action above maximized the terminal; tile it again so
        # the other terminal cannot cover the point clicked.
        w = window(title)
        if w and w.get("fullscreen"):
            cua("do", "window", "restore", target_of(w), check=False)
            try:
                poll("foot tiled", lambda: not (window(title) or {}).get("fullscreen"), 15, 1)
            except TimeoutError:
                sh(
                    f"hyprctl dispatch focuswindow address:{w['address']}; hyprctl dispatch fullscreen 1",
                    check=False,
                )
                poll("foot tiled", lambda: not (window(title) or {}).get("fullscreen"), 30, 1)
        cua("do", "launch", "foot", "--app-id", "cua-e2e-other2", timeout=120)
        poll("other focused", lambda: active_class() == "cua-e2e-other2", 60, 1)
        time.sleep(2)  # the layout animation settles
        w = window(title)
        assert w
        x, y = w["at"][0] + w["size"][0] // 2, w["at"][1] + w["size"][1] // 2
        covering = [
            c["class"]
            for c in clients()
            if c.get("class") != title
            and c.get("mapped", True)
            and c["at"][0] <= x < c["at"][0] + c["size"][0]
            and c["at"][1] <= y < c["at"][1] + c["size"][1]
        ]
        assert not covering, f"({x},{y}) is also inside {covering}"
        report = probe(
            evidence, "stream-desktop-click", "--action", f"click:{norm(x, y)}", "--presence-check"
        )
        focused = poll("foot focused", lambda: active_class() == title, 60, 1)
        a = report["actions"][0]
        # A viewer's click shows one cursor, the viewer's own: no agent joins
        # presence for it and no agent cursor overlay is drawn at it.
        assert report["presence"]["new_agents"] == [], report["presence"]
        after = shot(evidence, "stream-desktop-click-after")
        overlay = overlay_pixels_near(after, x, y, screen_w=int(screen[0]))
        assert (
            overlay < 40
        ), f"an agent cursor overlay at the viewer's click ({overlay} coloured px)"
        return (
            f"{report['codec']} {report['width']}x{report['height']}, first frame "
            f"{report['first_frame_ms']} ms, ping {report['ping']['median_ms']} ms; "
            f"click ack {a.get('ack_ms')} ms; focused {focused}; no agent cursor "
            f"({overlay} coloured px, agents {report['presence']['agents_after']})"
        )

    check("desktop stream: click focuses the window", desktop_click)

    def desktop_type():
        marker = f"cua-e2e-stream-{secrets.token_hex(3)}"
        report = probe(
            evidence,
            "stream-desktop-type",
            "--action",
            f"type:echo {marker} > /tmp/cua-e2e-stream-typed",
            "--action",
            "key:enter",
        )
        got = poll(
            "typed file",
            lambda: sh("cat /tmp/cua-e2e-stream-typed 2>/dev/null", check=False).strip(),
            60,
            1,
        )
        assert got == marker, got
        return f"{got}; acks {[a.get('ack_ms') for a in report['actions']]} ms"

    check("desktop stream: type + key into foot", desktop_type)

    def desktop_scroll():
        w = fill_terminal()
        x, y = w["at"][0] + w["size"][0] // 2, w["at"][1] + w["size"][1] // 2
        return scrolled("stream-desktop", w, ["--action", f"scroll:{norm(x, y)},-5"], (x, y))

    check("desktop stream: scroll moves the terminal", desktop_scroll)

    target = target_of(window(title))

    def window_type():
        marker = f"cua-e2e-window-{secrets.token_hex(3)}"
        report = probe(
            evidence,
            "stream-window-type",
            "--window",
            target,
            "--action",
            "click:0.5,0.5",
            "--action",
            f"type:echo {marker} > /tmp/cua-e2e-window-typed",
            "--action",
            "key:enter",
        )
        got = poll(
            "typed file",
            lambda: sh("cat /tmp/cua-e2e-window-typed 2>/dev/null", check=False).strip(),
            60,
            1,
        )
        assert got == marker, got
        return (
            f"{got}; policy {report['policy']}; "
            f"acks {[a.get('ack_ms') for a in report['actions']]} ms"
        )

    check("window stream: click, type + key into foot", window_type)

    def window_scroll():
        w = fill_terminal()
        x, y = w["at"][0] + w["size"][0] // 2, w["at"][1] + w["size"][1] // 2
        return scrolled(
            "stream-window", w, ["--window", target, "--action", "scroll:0.5,0.5,-5"], (x, y)
        )

    check("window stream: scroll moves the terminal", window_scroll)

    def cpu_during(seconds: int) -> dict:
        """% of one core used by Hyprland and cua-spacesd over `seconds`."""
        script = (
            "pids() { pgrep -x Hyprland | sed 's/^/Hyprland /'; "
            "for p in $(pgrep -x cua-spacesd); do "
            'grep -q token-sync /proc/$p/cmdline || echo "cua-spacesd $p"; done; }; '
            "snap() { pids | while read n p; do echo \"$n $(awk '{print $14+$15}' /proc/$p/stat)\"; done; }; "
            f"snap; echo --; sleep {seconds}; snap; getconf CLK_TCK"
        )
        out = sh(script, timeout=seconds + 60, check=False).split()
        try:
            sep, hz = out.index("--"), int(out[-1])
            before = dict(zip(out[0:sep:2], map(int, out[1:sep:2])))
            after = dict(zip(out[sep + 1 : -1 : 2], map(int, out[sep + 2 : -1 : 2])))
            return {
                k: round((after[k] - before[k]) / hz / seconds * 100) for k in after if k in before
            }
        except (ValueError, IndexError):
            return {}

    def fps_under(name: str, loop: str, size: tuple[int, int] | None = None) -> tuple[float, str]:
        """Stream fps while a terminal runs `loop`, with CPU use: the desktop
        stream, or with `size` a window stream of the terminal floated at
        that size."""
        app = f"cua-e2e-{name}"
        cua("do", "launch", "foot", "--app-id", app, "sh", "-c", loop, timeout=120)
        poll(f"{name} terminal", lambda: window(app), 60, 1)
        time.sleep(3)
        args: list[str] = []
        if size:
            target = target_of(window(app))
            cua("do", "window", "resize", target, str(size[0]), str(size[1]))
            poll(
                f"{name} resized",
                lambda: all(
                    abs(a - b) <= 24 for a, b in zip((window(app) or {}).get("size", [0, 0]), size)
                ),
                30,
                1,
            )
            time.sleep(2)
            args = ["--window", target]
        cpu: dict = {}
        sampler = threading.Thread(target=lambda: cpu.update(cpu_during(6)))
        try:
            sampler.start()
            report = probe(evidence, f"stream-fps-{name}", *args, seconds=10)
        finally:
            sampler.join()
            w = window(app)
            if w and int(w.get("pid", 0)) > 0:
                sh(f"kill {int(w['pid'])}", check=False)
        cpu_text = ", ".join(f"{k} {v}%" for k, v in sorted(cpu.items()))
        return report["fps"], (
            f"{report['fps']} fps at {report['width']}x{report['height']} "
            f"({report['frames']} frames; {cpu_text})"
        )

    def stream_fps():
        # The capture skips unchanged frames, so an idle desktop is not a
        # load; a terminal rewriting a counter in place changes every frame
        # (bash, as /bin/sh on Arch, has $EPOCHREALTIME).
        # Hyprland renders in software here and its screencopy readback of
        # the whole 1280x800 output bounds the desktop stream (reported).
        # A small window's stream is not bounded by the compositor, so it
        # measures what capture and encoding keep up with (asserted).
        # About 100 updates a second without forking a process per update,
        # so the load itself does not saturate the guest.
        counter = "while :; do printf '\\r%s ' \"$EPOCHREALTIME\"; sleep 0.01; done"
        since = sh("date '+%Y-%m-%d %H:%M:%S'").strip()
        window_fps, window_text = fps_under("fps-window", counter, size=(480, 270))
        _, desktop_text = fps_under("fps-desktop", counter)
        _, scroll_text = fps_under("fps-scroll", "while :; do date +%s.%N; done")
        # cua-spacesd logs each stream's capture and encoder counters when
        # it ends: they place a low frame rate (compositor, capture, encoder).
        journal = sh(
            f"(sudo -n journalctl -u cua-spacesd --since '{since}' -o cat 2>/dev/null "
            f"|| journalctl -u cua-spacesd --since '{since}' -o cat) "
            "| grep -E 'wayland capture ended|encoder stopped' | tail -12",
            check=False,
        )
        (evidence / "stream-fps-journal.txt").write_text(journal)
        pipeline = " | ".join(line.strip() for line in journal.splitlines())
        detail = (
            f"window (counter) {window_text}; desktop (counter) {desktop_text}; "
            f"desktop (scrolling) {scroll_text}; min {MIN_FPS}; pipeline: {pipeline}"
        )
        assert (
            window_fps >= MIN_FPS
        ), f"window stream {window_fps} fps under load, want >= {MIN_FPS}; {detail}"
        return detail

    check("stream frame rate under load", stream_fps)


if __name__ == "__main__":
    sys.exit(main())