// STRYKE-GUI — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-gui is one of the opt-in connector packages in the stryke ecosystem. Mouse motion / buttons / wheel, keyboard press / type / hotkey, screen size + bounds, pixel reads, screenshots, and clipboard — a PyAutoGUI-equivalent surface for stryke. Opt-in package, kept out of the stryke core binary so the daily-driver install stays slim and free of X11/Wayland system libraries. It ships as a Rust cdylib that stryke dlopens in-process on first use GUI; the native input/display code (enigo + xcap + arboard) lives in libstryke_gui.{dylib,so}.

Core stays small on purpose — most one-liner / awk-replacement work doesn't need a virtual-pointer driver or a screen-capture pipeline. enigo + xcap drag in the platform input/display stack (Wayland + xkb + dbus + PipeWire on Linux; CGEvent + ScreenCaptureKit on macOS), so they ship as an opt-in package.

~ARCHITECTURE

In-process cdylib design: the stryke side is a thin .stk wrapper that calls FFI symbols on the dlopen'd library. No subprocess, no pipe — calls return on the same thread that made them.

$WHY OPT-IN (NOT BUILTIN)

The enigo (input) and xcap (capture) crates link against the platform input/display stack. On Linux that means the X11 and Wayland client libraries plus xkb, dbus, and PipeWire — a stack of -dev packages that would otherwise have to be installed before cargo install strykelang could even build. Baking them into core forces that cost on every user, GUI or not.

The trade-off is intentional. The core stryke binary stays slim precisely because each connector ships separately. Daily-driver work (one-liners, awk replacement, data scripting) doesn't need a virtual-pointer driver or a screen-capture pipeline linked in.

&FFI ENVELOPE

JSON in / JSON out across the FFI boundary. Each GUI::* wrapper serializes its args to a JSON string and calls the matching gui__* symbol resolved out of the dlopen'd cdylib; the cdylib returns a JSON CString the wrapper parses. Action calls (gui__mouse_move, gui__mouse_click, gui__key_type, gui__key_hotkey, …) return a success JSON; query calls return a structured payload. catch_unwind on every call converts panics to JSON errors; the returned CString is freed via the cdylib-exported free-cstring symbol, wired automatically by stryke's FFI loader.

Failures come back as a {"error": "<msg>"} JSON payload and the .stk wrapper dies with the message.

# request shape (built by the .stk wrapper)
{"...": ...}

# response shape
{"result": ...}            # success — per-fn shape
{"error": "<msg>"}        # failure — wrapper die()s with the message

/SCOPE

The surface is a PyAutoGUI-equivalent — mouse motion / buttons / wheel, keyboard press / type / hotkey, screen size + bounds, pixel reads, and full or region screenshots. Coordinates use a top-left origin; the primary display only. Tweened motion runs at 60 fps via linear interpolation; duration ≤ 0 is a single-step warp.

The package exposes 69 public GUI:: functions (counted from lib/GUI.stk), backed by 60 gui__* cdylib exports in src/lib.rs — the difference is convenience wrappers (mouse_size, the right/middle/double/triple click and relative-drag/hscroll variants) that reuse a shared export. The surface divides into a device half (31 functions) and a pure half (38 functions) that runs headless with no display or permission gate.

See the README's API reference for the authoritative function list with per-field notes. The device half mirrors PyAutoGUI's shape so existing automation scripts port directly with GUI:: in place of pyautogui.; the pure color half has no PyAutoGUI counterpart.

+DEPENDENCIES

The cdylib pulls in the native input/display stack plus the JSON envelope crates. The release profile (Cargo.toml) builds with opt-level = 3, thin LTO, a single codegen unit, symbols stripped, and panic = "abort".

!PERMISSIONS

#PROJECT METADATA