noracu 0.1.0 → 0.1.1

package/imctl/src/imctl/cli.py

@@ -0,0 +1,236 @@
+"""imctl CLI — control iPhone Mirroring from the command line.
+
+Usage:
+    imctl status                    # session + window info
+    imctl tap 0.5 0.5               # tap center
+    imctl longpress 0.5 0.5 1.0     # long-press center for 1s
+    imctl swipe 0.5 0.8 0.5 0.2     # swipe up
+    imctl home                      # home gesture
+    imctl app-switcher              # app switcher
+    imctl scroll down 0.5           # scroll down half a screen
+    imctl page left                 # next home page
+    imctl type "hello world"        # type text (clipboard-based)
+    imctl key return                # press a key
+    imctl ocr                       # OCR the screen
+    imctl find "Settings"           # find text on screen
+    imctl open "Photos"             # open app via Spotlight
+    imctl verify home               # run a gesture with verification
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import gestures, input, verify, vision
+from .window import WindowError
+
+
+def _cmd_status(_args) -> int:
+    print(json.dumps(gestures.status(), indent=2))
+    return 0
+
+
+def _cmd_tap(args) -> int:
+    input.tap(args.x, args.y)
+    print(f"tapped ({args.x}, {args.y})")
+    return 0
+
+
+def _cmd_longpress(args) -> int:
+    input.long_press(args.x, args.y, args.duration)
+    print(f"long-pressed ({args.x}, {args.y}) for {args.duration}s")
+    return 0
+
+
+def _cmd_swipe(args) -> int:
+    input.swipe(args.fx, args.fy, args.tx, args.ty, args.ms)
+    print(f"swiped ({args.fx},{args.fy}) -> ({args.tx},{args.ty})")
+    return 0
+
+
+def _cmd_home(_args) -> int:
+    gestures.home()
+    print("home gesture sent")
+    return 0
+
+
+def _cmd_app_switcher(_args) -> int:
+    gestures.app_switcher()
+    print("app switcher opened")
+    return 0
+
+
+def _cmd_scroll(args) -> int:
+    if args.direction == "down":
+        gestures.scroll_down(args.distance)
+    else:
+        gestures.scroll_up(args.distance)
+    print(f"scrolled {args.direction} {args.distance}")
+    return 0
+
+
+def _cmd_page(args) -> int:
+    if args.direction == "left":
+        gestures.page_left()
+    else:
+        gestures.page_right()
+    print(f"paged {args.direction}")
+    return 0
+
+
+def _cmd_type(args) -> int:
+    input.type_text(args.text)
+    print(f"typed {args.text!r}")
+    return 0
+
+
+def _cmd_key(args) -> int:
+    input.press_key(args.key)
+    print(f"pressed {args.key}")
+    return 0
+
+
+def _cmd_ocr(_args) -> int:
+    hits = gestures.read_text()
+    for h in hits:
+        print(h)
+    print(f"-- {len(hits)} hits")
+    return 0
+
+
+def _cmd_find(args) -> int:
+    hit = vision.find(args.text, exact=args.exact)
+    if hit is None:
+        print(f"not found: {args.text!r}", file=sys.stderr)
+        return 1
+    print(hit)
+    return 0
+
+
+def _cmd_open(args) -> int:
+    ok = gestures.open_app(args.app)
+    print(f"opened {args.app!r}" if ok else f"app not found: {args.app!r}")
+    return 0 if ok else 1
+
+
+def _cmd_verify(args) -> int:
+    actions = {
+        "home": gestures.home,
+        "app-switcher": gestures.app_switcher,
+        "page-left": gestures.page_left,
+        "page-right": gestures.page_right,
+    }
+    if args.action not in actions:
+        print(f"unknown action: {args.action}", file=sys.stderr)
+        return 2
+    ok = verify.verify_action(actions[args.action])
+    print("screen changed: yes" if ok else "screen changed: NO (action may have been dropped)")
+    return 0 if ok else 1
+
+
+def _cmd_launch(_args) -> int:
+    gestures.launch()
+    print("iPhone Mirroring ready")
+    return 0
+
+
+def _cmd_screenshot(args) -> int:
+    path = vision.capture_window(args.path)
+    print(path)
+    return 0
+
+
+def _cmd_resume(_args) -> int:
+    ok = gestures.resume()
+    print("resumed" if ok else "still paused (unlock the iPhone, then retry)")
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="imctl",
+        description="Control iPhone Mirroring on macOS from the CLI",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("status", help="show session status").set_defaults(func=_cmd_status)
+    sp = sub.add_parser("screenshot", help="capture the mirroring window to PNG (by window id, works when covered)")
+    sp.add_argument("path", nargs="?", default=None)
+    sp.set_defaults(func=_cmd_screenshot)
+    sub.add_parser("resume", help="click Resume when the session shows Connection Paused").set_defaults(func=_cmd_resume)
+    sub.add_parser("launch", help="ensure mirroring is running and frontmost").set_defaults(func=_cmd_launch)
+
+    sp = sub.add_parser("tap", help="tap at normalized coords")
+    sp.add_argument("x", type=float)
+    sp.add_argument("y", type=float)
+    sp.set_defaults(func=_cmd_tap)
+
+    sp = sub.add_parser("longpress", help="long-press at normalized coords")
+    sp.add_argument("x", type=float)
+    sp.add_argument("y", type=float)
+    sp.add_argument("--duration", type=float, default=0.8)
+    sp.set_defaults(func=_cmd_longpress)
+
+    sp = sub.add_parser("swipe", help="swipe between two normalized points")
+    sp.add_argument("fx", type=float)
+    sp.add_argument("fy", type=float)
+    sp.add_argument("tx", type=float)
+    sp.add_argument("ty", type=float)
+    sp.add_argument("--ms", type=int, default=300)
+    sp.set_defaults(func=_cmd_swipe)
+
+    sub.add_parser("home", help="home gesture").set_defaults(func=_cmd_home)
+    sub.add_parser("app-switcher", help="open app switcher").set_defaults(func=_cmd_app_switcher)
+
+    sp = sub.add_parser("scroll", help="scroll up/down")
+    sp.add_argument("direction", choices=["up", "down"])
+    sp.add_argument("distance", type=float, nargs="?", default=0.5)
+    sp.set_defaults(func=_cmd_scroll)
+
+    sp = sub.add_parser("page", help="page left/right on home screen")
+    sp.add_argument("direction", choices=["left", "right"])
+    sp.set_defaults(func=_cmd_page)
+
+    sp = sub.add_parser("type", help="type text (clipboard-based, IME-safe)")
+    sp.add_argument("text")
+    sp.set_defaults(func=_cmd_type)
+
+    sp = sub.add_parser("key", help="press a key (return/delete/up/down/left/right)")
+    sp.add_argument("key")
+    sp.set_defaults(func=_cmd_key)
+
+    sub.add_parser("ocr", help="OCR the screen").set_defaults(func=_cmd_ocr)
+
+    sp = sub.add_parser("find", help="find text on screen")
+    sp.add_argument("text")
+    sp.add_argument("--exact", action="store_true")
+    sp.set_defaults(func=_cmd_find)
+
+    sp = sub.add_parser("open", help="open an app via Spotlight")
+    sp.add_argument("app")
+    sp.set_defaults(func=_cmd_open)
+
+    sp = sub.add_parser("verify", help="run a gesture and verify the screen changed")
+    sp.add_argument("action", choices=["home", "app-switcher", "page-left", "page-right"])
+    sp.set_defaults(func=_cmd_verify)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except WindowError as exc:
+        print(f"window error: {exc}", file=sys.stderr)
+        return 3
+    except input.InputError as exc:
+        print(f"input error: {exc}", file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/imctl/src/imctl/gestures.py

@@ -0,0 +1,151 @@
+"""High-level gestures composed from the input engine.
+
+These map to standard iOS interactions. Coordinates are normalized
+(0-1) within the mirroring window. Gesture start points were chosen to
+match iOS conventions (e.g. home swipe starts at the very bottom edge).
+"""
+
+from __future__ import annotations
+
+from . import input as inp
+from . import vision
+from .window import ensure_running, get_bounds
+
+
+class GestureError(RuntimeError):
+    """Raised when a composed gesture cannot complete."""
+
+
+def home() -> None:
+    """Swipe up from near the bottom edge: go to the home screen.
+
+    Starts at 0.90 height: the bottom ~7% of the mirroring window is
+    macOS window chrome (rounded corners / resize area), not the video
+    surface — events there never reach the phone. 0.90 is the lowest
+    point that reliably lands on the iOS home-indicator zone.
+    """
+    inp.swipe(0.5, 0.90, 0.5, 0.10, duration_ms=300)
+
+
+def app_switcher() -> None:
+    """Swipe up and hold: open the app switcher."""
+    b = get_bounds()
+    from Quartz import (
+        CGEventCreateMouseEvent, CGEventPost, CGEventSourceCreate,
+        kCGEventLeftMouseDown, kCGEventLeftMouseUp, kCGEventLeftMouseDragged,
+        kCGEventSourceStateHIDSystemState, kCGHIDEventTap, kCGMouseButtonLeft,
+    )
+    import time
+
+    x0, y0 = b.denormalize(0.5, 0.90)
+    x1, y1 = b.denormalize(0.5, 0.45)
+    src = CGEventSourceCreate(kCGEventSourceStateHIDSystemState)
+
+    def ev(kind, x, y):
+        CGEventPost(kCGHIDEventTap,
+                    CGEventCreateMouseEvent(src, kind, (x, y), kCGMouseButtonLeft))
+
+    ev(kCGEventLeftMouseDown, x0, y0)
+    time.sleep(0.02)
+    # Eased drag to mid-screen.
+    steps = 15
+    for i in range(1, steps + 1):
+        t = i / steps
+        e = t * t * (3 - 2 * t)  # smoothstep
+        ev(kCGEventLeftMouseDragged, x0 + (x1 - x0) * e, y0 + (y1 - y0) * e)
+        time.sleep(0.016)
+    time.sleep(0.55)  # hold to trigger the switcher
+    ev(kCGEventLeftMouseUp, x1, y1)
+
+
+def scroll_down(distance: float = 0.5) -> None:
+    """Scroll content down (swipe up) by a normalized distance."""
+    start = min(0.9, 0.4 + distance / 2)
+    inp.swipe(0.5, start, 0.5, start - distance, duration_ms=300)
+
+
+def scroll_up(distance: float = 0.5) -> None:
+    """Scroll content up (swipe down) by a normalized distance."""
+    start = max(0.1, 0.6 - distance / 2)
+    inp.swipe(0.5, start, 0.5, start + distance, duration_ms=300)
+
+
+def page_left() -> None:
+    """Swipe right-to-left: go to the next home-screen page."""
+    inp.swipe(0.8, 0.5, 0.2, 0.5, duration_ms=280)
+
+
+def page_right() -> None:
+    """Swipe left-to-right: go to the previous home-screen page."""
+    inp.swipe(0.2, 0.5, 0.8, 0.5, duration_ms=280)
+
+
+def pull_down_search() -> None:
+    """Swipe down from mid-screen: open Spotlight search."""
+    inp.swipe(0.5, 0.25, 0.5, 0.75, duration_ms=280)
+
+
+def open_app(name: str) -> bool:
+    """Open an app by name via Spotlight + OCR + tap.
+
+    Returns True if the app name was found on screen after typing.
+    """
+    pull_down_search()
+    import time
+
+    time.sleep(1.0)
+    inp.type_text(name)
+    time.sleep(1.5)  # wait for Spotlight results
+
+    hit = vision.find(name)
+    if hit is None:
+        return False
+    inp.tap(hit.nx, hit.ny)
+    time.sleep(1.0)
+    return True
+
+
+def read_text() -> list:
+    """OCR the current screen; returns vision.OCRHit list."""
+    return vision.read_screen()
+
+
+def status() -> dict:
+    """Return a status dict for the mirroring session.
+
+    Keys: running; and when running: window {x,y,w,h} (AX bounds), window_id, onscreen, frontmost,
+    paused (True/False, or null when the "Connection Paused" text cannot be read).
+    """
+    from .window import get_window_info, is_frontmost, is_paused, is_running
+
+    running = is_running()
+    info = {"running": running}
+    if running:
+        try:
+            b = get_bounds()
+            info["window"] = {"x": b.x, "y": b.y, "w": b.width, "h": b.height}
+        except Exception as exc:
+            info["window_error"] = str(exc)
+        wi = get_window_info()
+        if wi:
+            info["window_id"] = wi["id"]
+            info["onscreen"] = wi["onscreen"]
+        info["frontmost"] = is_frontmost()
+        info["paused"] = is_paused()
+    return info
+
+
+def resume() -> bool:
+    """Resume a paused mirroring session (clicks Resume). Returns True when not paused afterwards."""
+    from .window import resume as _resume
+
+    return _resume()
+
+
+def launch() -> None:
+    """Ensure iPhone Mirroring is running, frontmost, and not paused."""
+    ensure_running()
+    from .window import ensure_frontmost, resume as _resume
+
+    ensure_frontmost()
+    _resume()

package/imctl/src/imctl/input.py

@@ -0,0 +1,246 @@
+"""CGEvent input engine for iPhone Mirroring.
+
+All input is delivered as synthesized CoreGraphics events posted to the
+HID event tap. The iPhone Mirroring app translates these into touch
+events on the phone.
+
+Empirically-validated parameters (see project README for the test
+methodology):
+
+- TAP_INTERVAL_S = 0.05  — minimum down/up interval that the mirroring
+  gesture recognizer registers reliably. Faster taps are sometimes
+  dropped.
+- SWIPE_STEPS = 20      — number of interpolated drag points. A single
+  dd/dm/du drag (e.g. via cliclick) is NOT recognized as a swipe by
+  iPhone Mirroring; stepped drags are.
+- SWIPE_NUDGE_PX = 3    — an initial small movement right after
+  mouse-down. Without it, the recognizer sometimes classifies the
+  gesture as an icon long-press-drag instead of a scroll swipe.
+- Ease-in-out curve     — quadratic ease matches how a human finger
+  decelerates, which keeps the gesture inside the recognizer's
+  velocity window.
+"""
+
+from __future__ import annotations
+
+import time
+
+from Quartz import (
+    CGEventCreateMouseEvent,
+    CGEventPost,
+    CGEventSetIntegerValueField,
+    CGEventSourceCreate,
+    kCGEventLeftMouseDown,
+    kCGEventLeftMouseUp,
+    kCGEventLeftMouseDragged,
+    kCGEventSourceStateHIDSystemState,
+    kCGHIDEventTap,
+    kCGMouseButtonLeft,
+    kCGEventFlagMaskCommand,
+    CGEventCreateKeyboardEvent,
+    CGEventSetFlags,
+)
+
+from .window import WindowBounds, ensure_frontmost, get_bounds
+
+TAP_INTERVAL_S = 0.05
+LONG_PRESS_S = 0.8
+SWIPE_STEPS = 20
+SWIPE_NUDGE_PX = 3
+SWIPE_DEFAULT_MS = 300
+
+
+class InputError(RuntimeError):
+    """Raised when a synthesized input event cannot be delivered."""
+
+
+def _source():
+    return CGEventSourceCreate(kCGEventSourceStateHIDSystemState)
+
+
+def _mouse_event(kind: int, x: float, y: float, source) -> None:
+    event = CGEventCreateMouseEvent(
+        source, kind, (x, y), kCGMouseButtonLeft
+    )
+    if event is None:
+        raise InputError(f"CGEventCreateMouseEvent returned None for {kind}")
+    CGEventPost(kCGHIDEventTap, event)
+
+
+def _key_event(keycode: int, down: bool, source) -> None:
+    event = CGEventCreateKeyboardEvent(source, keycode, down)
+    if event is None:
+        raise InputError(f"CGEventCreateKeyboardEvent returned None for {keycode}")
+    CGEventPost(kCGHIDEventTap, event)
+
+
+# --- Pointer primitives ---------------------------------------------------
+
+
+def tap(nx: float = 0.5, ny: float = 0.5, bounds: WindowBounds | None = None) -> None:
+    """Tap at normalized coordinates (0-1) within the mirroring window."""
+    ensure_frontmost()
+    b = bounds or get_bounds()
+    x, y = b.denormalize(nx, ny)
+    src = _source()
+    _mouse_event(kCGEventLeftMouseDown, x, y, src)
+    time.sleep(TAP_INTERVAL_S)
+    _mouse_event(kCGEventLeftMouseUp, x, y, src)
+
+
+def long_press(nx: float = 0.5, ny: float = 0.5, duration_s: float = LONG_PRESS_S,
+               bounds: WindowBounds | None = None) -> None:
+    """Press and hold at normalized coordinates."""
+    ensure_frontmost()
+    b = bounds or get_bounds()
+    x, y = b.denormalize(nx, ny)
+    src = _source()
+    _mouse_event(kCGEventLeftMouseDown, x, y, src)
+    time.sleep(duration_s)
+    _mouse_event(kCGEventLeftMouseUp, x, y, src)
+
+
+def _ease_in_out(t: float) -> float:
+    """Quadratic ease-in-out: slow start, fast middle, slow end."""
+    if t < 0.5:
+        return 2.0 * t * t
+    return 1.0 - ((-2.0 * t + 2.0) ** 2) / 2.0
+
+
+def swipe(from_x: float, from_y: float, to_x: float, to_y: float,
+          duration_ms: int = SWIPE_DEFAULT_MS,
+          bounds: WindowBounds | None = None) -> None:
+    """Swipe between two normalized points with eased interpolation.
+
+    The gesture is: mouse-down, 3px nudge, 20 eased drag steps,
+    mouse-up. This is the shape iPhone Mirroring's recognizer accepts.
+    """
+    ensure_frontmost()
+    b = bounds or get_bounds()
+    x0, y0 = b.denormalize(from_x, from_y)
+    x1, y1 = b.denormalize(to_x, to_y)
+
+    src = _source()
+    step_delay = (duration_ms / 1000.0) / SWIPE_STEPS
+
+    _mouse_event(kCGEventLeftMouseDown, x0, y0, src)
+    time.sleep(0.02)
+
+    # Initial nudge: disambiguates swipe from long-press-drag.
+    dx = 1 if x1 >= x0 else -1
+    dy = 1 if y1 >= y0 else -1
+    _mouse_event(kCGEventLeftMouseDragged, x0 + dx * SWIPE_NUDGE_PX,
+                 y0 + dy * SWIPE_NUDGE_PX, src)
+    time.sleep(0.01)
+
+    for i in range(1, SWIPE_STEPS + 1):
+        t = i / SWIPE_STEPS
+        e = _ease_in_out(t)
+        cx = x0 + (x1 - x0) * e
+        cy = y0 + (y1 - y0) * e
+        _mouse_event(kCGEventLeftMouseDragged, cx, cy, src)
+        time.sleep(step_delay)
+
+    _mouse_event(kCGEventLeftMouseUp, x1, y1, src)
+
+
+def scroll(dy_pixels: int, nx: float = 0.5, ny: float = 0.5,
+           bounds: WindowBounds | None = None) -> None:
+    """Scroll vertically at a position. Positive dy scrolls up."""
+    from Quartz import CGEventCreateScrollWheelEvent
+
+    ensure_frontmost()
+    b = bounds or get_bounds()
+    x, y = b.denormalize(nx, ny)
+    src = _source()
+    # Axis 1 = vertical; pixel units; negative = scroll down (content up).
+    event = CGEventCreateScrollWheelEvent(
+        src, kCGScrollEventUnitPixel, 1, dy_pixels
+    )
+    if event is None:
+        raise InputError("CGEventCreateScrollWheelEvent returned None")
+    CGEventPost(kCGHIDEventTap, event)
+
+
+# --- Keyboard primitives ----------------------------------------------------
+
+# macOS virtual keycodes used by this module.
+_VK_RETURN = 36
+_VK_DELETE = 51
+_VK_ARROW_KEYS = {"up": 126, "down": 125, "left": 123, "right": 124}
+_VK_V = 9
+_VK_A = 0
+
+
+def press_key(key: str) -> None:
+    """Press a single key: 'return', 'delete', 'up', 'down', 'left', 'right'."""
+    ensure_frontmost()
+    keymap = {"return": _VK_RETURN, "delete": _VK_DELETE, **_VK_ARROW_KEYS}
+    if key not in keymap:
+        raise InputError(f"unsupported key: {key!r} (supported: {sorted(keymap)})")
+    src = _source()
+    _key_event(keymap[key], True, src)
+    time.sleep(0.02)
+    _key_event(keymap[key], False, src)
+
+
+def type_text(text: str) -> None:
+    """Type text via clipboard paste (IME-safe).
+
+    Direct CGEvent keystroke synthesis breaks under CJK IMEs and is
+    slow for long strings. Instead we:
+      1. save the user's pasteboard,
+      2. write the text,
+      3. Cmd+V into the focused field,
+      4. restore the pasteboard.
+
+    Requires the calling terminal to have Accessibility permission
+    (same as every other imctl input).
+    """
+    from AppKit import NSPasteboard
+
+    ensure_frontmost()
+    pb = NSPasteboard.generalPasteboard()
+    saved = pb.dataForType_("public.utf8-plain-text")
+    saved_change = pb.changeCount()
+
+    try:
+        pb.clearContents()
+        pb.setString_forType_(text, "public.utf8-plain-text")
+        time.sleep(0.05)
+
+        src = _source()
+        v_down = CGEventCreateKeyboardEvent(src, _VK_V, True)
+        CGEventSetFlags(v_down, kCGEventFlagMaskCommand)
+        CGEventPost(kCGHIDEventTap, v_down)
+        time.sleep(0.05)
+        v_up = CGEventCreateKeyboardEvent(src, _VK_V, False)
+        CGEventSetFlags(v_up, kCGEventFlagMaskCommand)
+        CGEventPost(kCGHIDEventTap, v_up)
+        time.sleep(0.15)  # let the paste land before restoring
+    finally:
+        # Restore the user's clipboard only if nothing else changed it.
+        if pb.changeCount() == saved_change + 1:
+            pb.clearContents()
+            if saved is not None:
+                pb.setData_forType_(saved, "public.utf8-plain-text")
+
+
+def clear_text() -> None:
+    """Select-all and delete in the focused field."""
+    ensure_frontmost()
+    src = _source()
+    for keycode, flags in (
+        (_VK_A, kCGEventFlagMaskCommand),  # Cmd+A
+    ):
+        e = CGEventCreateKeyboardEvent(src, keycode, True)
+        CGEventSetFlags(e, flags)
+        CGEventPost(kCGHIDEventTap, e)
+        time.sleep(0.03)
+        e = CGEventCreateKeyboardEvent(src, keycode, False)
+        CGEventSetFlags(e, flags)
+        CGEventPost(kCGHIDEventTap, e)
+    time.sleep(0.05)
+    _key_event(_VK_DELETE, True, src)
+    time.sleep(0.02)
+    _key_event(_VK_DELETE, False, src)

package/imctl/src/imctl/verify.py

@@ -0,0 +1,77 @@
+"""Pixel-level action verification.
+
+Each gesture is followed by a screenshot hash comparison to confirm the
+screen actually changed. This closes the loop: an action that reports
+success but leaves the screen identical is a dropped event, and callers
+should retry or re-observe — the same observe-act-re-observe discipline
+that OpenAI's Computer Use enforces with its revision mechanism.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import tempfile
+from dataclasses import dataclass
+
+from .window import get_bounds
+
+
+@dataclass(frozen=True)
+class ScreenState:
+    """A fingerprint of the mirroring window content."""
+
+    md5: str
+    width: int
+    height: int
+
+
+def capture_hash() -> ScreenState:
+    """Capture the window and return a content fingerprint.
+
+    The hash is computed over a downsampled copy: full-resolution
+    hashes are sensitive to video-stream noise (compression flicker)
+    even when nothing meaningful changed.
+    """
+    b = get_bounds()
+    raw = tempfile.mktemp(prefix="imctl_verify_", suffix=".png")
+    small = tempfile.mktemp(prefix="imctl_verify_s_", suffix=".png")
+    try:
+        subprocess.run(
+            ["screencapture", "-x", f"-R{b.x},{b.y},{b.width},{b.height}", raw],
+            check=True,
+            timeout=10,
+        )
+        # Downsample to ~163x360 (half window) to suppress stream noise.
+        subprocess.run(
+            ["sips", "-z", "360", "163", raw, "--out", small],
+            check=True,
+            capture_output=True,
+            timeout=10,
+        )
+        with open(small, "rb") as f:
+            digest = hashlib.md5(f.read()).hexdigest()
+        return ScreenState(md5=digest, width=b.width, height=b.height)
+    finally:
+        subprocess.run(["rm", "-f", raw, small], capture_output=True)
+
+
+def changed(before: ScreenState, after: ScreenState) -> bool:
+    """True if the screen content differs between two states."""
+    return before.md5 != after.md5
+
+
+def verify_action(action, *args, settle_s: float = 1.5, **kwargs) -> bool:
+    """Run an action and report whether the screen changed.
+
+    Usage:
+        ok = verify_action(gestures.home)
+    Returns True if the screen content changed after the action.
+    """
+    before = capture_hash()
+    action(*args, **kwargs)
+    import time
+
+    time.sleep(settle_s)
+    after = capture_hash()
+    return changed(before, after)