Crate smix_runner_client

Expand description

smix-runner-client — HTTP IPC client to swift-bridge/SmixRunnerCore (outer crate). v3.1 c8, first outer crate allowing reqwest + tokio + thiserror + tracing deps per user 2026-05-25 brief.

Ported from now-retired TS source: src/sim/runner-client.ts (1129 lines). Wire-level 1:1 compatibility with the Swift side — any route shape / query param / response body shape change must be done in lockstep with swift-bridge/Sources/SmixRunnerCore.

§Routes (18 endpoints, port progress c8 = MVP set)

GET /health — connectivity probe (memoized via HttpRunnerClient::ensure_reachable)
GET /tree?include= — full a11y tree dump (returns A11yNode)
GET /system-popups?include= — list of SystemPopup
POST /tap {selector, mode, include?} — selector → element tap
POST /tap-at-norm-coord {nx, ny} — Apple native event chain coord tap
POST /find {selector, include?} — boolean existence check (v1.4 quick-probe)
POST /fill {selector, text, include?} — fill text into input
POST /clear {selector, include?} — clear input
POST /press-key {key} — press named key (Return/Tab/etc.)
POST /scroll {selector, direction, include?} — scroll-until-visible
POST /swipe-once {direction} — single swipe gesture (no probe loop)
POST /foreground {bundleId} — bring app to foreground
POST /hide-keyboard — swipe-down to dismiss keyboard
POST /back — back gesture
POST /record/start — begin recording AX notifications
GET /record/poll — drain recorded events
POST /record/stop — stop recording, drain final events

Per CLAUDE.md §9 #4 — never expose raw URL / sleep / xpath surfaces. All operations go through the typed methods below.

Structs§

FindRequest: POST /find request body.
FindResponse: POST /find response body.
HttpRunnerClient: HTTP client to the swift-side SmixRunnerCore. Async (tokio-based). Constructed once per Cell; ensure_reachable memoizes a successful /health probe so subsequent calls don’t re-probe.
KeyboardStages: Per-stage timing returned by /fill / /clear / /press-key.
OcrFrame: v5.19 c1 — normalized OCR bounding box returned by HttpRunnerClient::find_text_by_ocr. Coordinates are normalized to [0, 1] in UIKit coord space (top-left origin, y-down). Apple Vision’s native bbox is bottom-left origin + y-up — the swift handler converts before returning so all consumers see UIKit coords.
RecordEventsResponse: GET /record/poll / POST /record/stop response body.
RecordedEvent: One recorder event captured by /record/start → /record/poll flow.
RequestContext: v0.2.1 — per-request context carried across the wire via the App-Bundle-Id and App-Activate HTTP headers. Client sets these via HttpRunnerClient::with_target_bundle_id / with_auto_activate, or per-call by cloning the client with a modified context. The runner side reads them into SmixRunnerServer.currentContext (task-local) and passes to resolveApp() in every app-touching handler.
RunnerIncludeOpts: include scope query param shared by /tree / /tap / /fill / /clear / /find / /scroll / /system-popups. URL-only.
RunnerKeyboardResult: POST /fill / POST /clear / POST /press-key response body.
RunnerScrollNotMatched: POST /scroll returned 200 / matched:false / swipes:N — scroll exhausted N swipes without surfacing the target. Mirrors TS RunnerScrollNotMatched.
RunnerSwipeOnceFailure: POST /swipe-once returned 200 / ok:false / vanished_during_swipe. Mirrors TS RunnerSwipeOnceFailure.
ScrollResponse: POST /scroll response body.
SystemPopup: One system-popup discovered on the screen (alert / sheet / banner).
SystemPopupActionRequest: POST /system-popup-action request body (v4.2 c2 — G9 act side).
SystemPopupActionResponse: POST /system-popup-action response body.
SystemPopupButton: One button on a SystemPopup.
SystemPopupsResponse: GET /system-popups response body.
TapAtNormCoordRequest: POST /tap-at-norm-coord request body.
TapNotFoundError: POST /tap returned 404 / not_found — element matched no node. Mirrors TS TapNotFoundError.
TapRequest: POST /tap request body.
TapResult: POST /tap response body.
TapStages: POST /tap per-stage timing in milliseconds.

Enums§

IncludeScope: include scope literal — currently only all-windows (system popups pierce the app frame).
RunnerScrollSelector: Reduced selector shape used by /scroll (text-or-id only; complex selectors are host-side-resolved before reaching the runner).
RunnerTransportError: Transport-level failure (network, non-2xx, malformed body). Mirrors TS RunnerTransportError 1:1.
TapMode: POST /tap mode discriminator.