simdrive 0.2.0a1__tar.gz

simdrive-0.2.0a1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: simdrive
+Version: 0.2.0a1
+Summary: Hand your iOS simulator to your agent. Claude-native MCP driver for iOS simulator testing — vision, taps, recordings.
+Author-email: SyncTek LLC <info@synctek.io>
+License-Expression: MIT
+Project-URL: Homepage, https://synctek.io/simdrive
+Project-URL: Repository, https://github.com/SyncTek-LLC/simdrive
+Project-URL: Issues, https://github.com/SyncTek-LLC/simdrive/issues
+Keywords: ios,simulator,mcp,claude,testing,qa,agent,anthropic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyobjc-framework-Quartz>=10.0
+Requires-Dist: pyobjc-framework-Vision>=10.0
+Provides-Extra: ssim
+Requires-Dist: scikit-image>=0.22; extra == "ssim"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# simdrive
+
+> **Hand your iOS simulator to your agent.**
+
+Claude-native MCP server for driving iOS simulators. Vision-first. No XCTest, no accessibility-tree query, no daemons. Your agent looks at a screenshot, picks a pixel, and `simdrive` taps it.
+
+## Why
+
+You stay in your editor. Your agent drives the sim in the background. Taps don't steal focus, your keyboard doesn't get hijacked.
+
+Automating an iOS simulator from inside an LLM session has historically required:
+- A Swift XCTest runner that breaks every Xcode release
+- An accessibility tree your agent has to mentally reconstruct from JSON dumps
+- Bespoke selectors (`label:"Sign in"`) that drift with every UI change
+- Watchdogs killing your runner mid-test
+
+simdrive replaces all of that with: **screenshot in, click out**. Your agent already understands screenshots — the LLM is the selector engine.
+
+## Install
+
+```bash
+pip install simdrive
+```
+
+Requirements:
+- macOS with Xcode + iOS Simulator (for native HID input)
+- A booted simulator. simdrive will use a running one or boot one for you.
+
+simdrive runs in the background by default — taps and keystrokes go straight to the simulator without raising its window or stealing your keyboard focus. Verify via `session_status` (`mode: "background"`).
+
+## Wire into Claude
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "simdrive": { "command": "simdrive" }
+  }
+}
+```
+
+Restart Claude Code. The 12 simdrive tools are now available.
+
+## Quickstart
+
+```
+You: open Settings on iPhone 17 Pro and turn on Airplane Mode.
+
+Claude (using simdrive):
+  → session_start({device: "iPhone 17 Pro", app_bundle_id: "com.apple.Preferences"})
+  → observe()                              # screenshot + annotated copy with numbered marks
+  → tap({text: "Airplane Mode"})           # by visible text
+  → observe()                              # sees the toggle
+  → tap({mark: 12})                        # by mark number from the annotation
+  → observe()                              # confirms it's green
+```
+
+You can also `tap({x, y})` if you have specific pixel coords (great for replay). Pick whichever is lowest-friction per call:
+
+| Form | Use it for |
+|------|------------|
+| `{text: "..."}` | Buttons, labels, anything with visible text |
+| `{mark: N}` | When the agent has just looked at the annotated screenshot |
+| `{x, y}` | Replays, deterministic UI tests, icons without text |
+
+That's the whole loop. No selectors. No waits. No XCTest.
+
+## Tool surface (12 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `session_start` | Boot/find a sim, optionally launch an app |
+| `session_end` | End session (sim stays booted) |
+| `session_status` | Inspect active session(s) |
+| `observe` | Capture screenshot (returns file path), optional log tail |
+| `tap` | Click at screenshot pixel coordinate |
+| `swipe` | Drag from (x1,y1)→(x2,y2) |
+| `type_text` | Send keyboard input |
+| `press_key` | Hardware buttons (home, lock, siri, shake, return, etc.) |
+| `record_start` | Begin recording every action |
+| `record_stop` | Finalize recording.yaml |
+| `replay` | Re-execute a recording with SSIM drift detection |
+| `logs` | Tail simulator logs (NSPredicate filterable) |
+
+Coordinates are always in **screenshot pixel space** — same pixels the agent sees in the most recent `observe`.
+
+## Recording + replay
+
+```
+record_start({name: "checkout-flow"})
+  ... agent does the flow naturally, calling tap/swipe/type_text ...
+record_stop()  # writes ~/.simdrive/recordings/checkout-flow/recording.yaml
+```
+
+Later:
+
+```
+replay({name: "checkout-flow", on_drift: "halt"})
+```
+
+Each step is gated on visual similarity: if the live screen has drifted from the recorded pre-screenshot, the replay halts (`halt`), warns and continues (`warn`), or proceeds blind (`force`). The recording is a self-contained YAML+PNG bundle you can commit to your repo.
+
+## Testing
+
+```bash
+pip install simdrive[dev]
+pytest                          # 22 unit tests, no sim required
+pytest -m live                  # 26 live tests against TestKitApp
+```
+
+Live tests boot a fresh TestKitApp session per test and exercise every tool: tap by text/mark/coords, type into focused fields, swipe-to-scroll, alert-while-focused dismissal (the iOS 26 case that defeated v15), record + replay with drift detection.
+
+## What this isn't
+
+- **Not** a real-device tool. v0.1 is simulator-only. Real device support via `idb`/`devicectl` is on the roadmap.
+- **Not** a CI replacement (yet). Designed for interactive Claude sessions; CI integration is a follow-up.
+- **Not** a fork of XCTest. We deliberately avoid Apple's testing stack to stay durable across Xcode releases.
+
+## License
+
+MIT. Built by [SyncTek](https://synctek.io).

simdrive-0.2.0a1/README.md

@@ -0,0 +1,122 @@
+# simdrive
+
+> **Hand your iOS simulator to your agent.**
+
+Claude-native MCP server for driving iOS simulators. Vision-first. No XCTest, no accessibility-tree query, no daemons. Your agent looks at a screenshot, picks a pixel, and `simdrive` taps it.
+
+## Why
+
+You stay in your editor. Your agent drives the sim in the background. Taps don't steal focus, your keyboard doesn't get hijacked.
+
+Automating an iOS simulator from inside an LLM session has historically required:
+- A Swift XCTest runner that breaks every Xcode release
+- An accessibility tree your agent has to mentally reconstruct from JSON dumps
+- Bespoke selectors (`label:"Sign in"`) that drift with every UI change
+- Watchdogs killing your runner mid-test
+
+simdrive replaces all of that with: **screenshot in, click out**. Your agent already understands screenshots — the LLM is the selector engine.
+
+## Install
+
+```bash
+pip install simdrive
+```
+
+Requirements:
+- macOS with Xcode + iOS Simulator (for native HID input)
+- A booted simulator. simdrive will use a running one or boot one for you.
+
+simdrive runs in the background by default — taps and keystrokes go straight to the simulator without raising its window or stealing your keyboard focus. Verify via `session_status` (`mode: "background"`).
+
+## Wire into Claude
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "simdrive": { "command": "simdrive" }
+  }
+}
+```
+
+Restart Claude Code. The 12 simdrive tools are now available.
+
+## Quickstart
+
+```
+You: open Settings on iPhone 17 Pro and turn on Airplane Mode.
+
+Claude (using simdrive):
+  → session_start({device: "iPhone 17 Pro", app_bundle_id: "com.apple.Preferences"})
+  → observe()                              # screenshot + annotated copy with numbered marks
+  → tap({text: "Airplane Mode"})           # by visible text
+  → observe()                              # sees the toggle
+  → tap({mark: 12})                        # by mark number from the annotation
+  → observe()                              # confirms it's green
+```
+
+You can also `tap({x, y})` if you have specific pixel coords (great for replay). Pick whichever is lowest-friction per call:
+
+| Form | Use it for |
+|------|------------|
+| `{text: "..."}` | Buttons, labels, anything with visible text |
+| `{mark: N}` | When the agent has just looked at the annotated screenshot |
+| `{x, y}` | Replays, deterministic UI tests, icons without text |
+
+That's the whole loop. No selectors. No waits. No XCTest.
+
+## Tool surface (12 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `session_start` | Boot/find a sim, optionally launch an app |
+| `session_end` | End session (sim stays booted) |
+| `session_status` | Inspect active session(s) |
+| `observe` | Capture screenshot (returns file path), optional log tail |
+| `tap` | Click at screenshot pixel coordinate |
+| `swipe` | Drag from (x1,y1)→(x2,y2) |
+| `type_text` | Send keyboard input |
+| `press_key` | Hardware buttons (home, lock, siri, shake, return, etc.) |
+| `record_start` | Begin recording every action |
+| `record_stop` | Finalize recording.yaml |
+| `replay` | Re-execute a recording with SSIM drift detection |
+| `logs` | Tail simulator logs (NSPredicate filterable) |
+
+Coordinates are always in **screenshot pixel space** — same pixels the agent sees in the most recent `observe`.
+
+## Recording + replay
+
+```
+record_start({name: "checkout-flow"})
+  ... agent does the flow naturally, calling tap/swipe/type_text ...
+record_stop()  # writes ~/.simdrive/recordings/checkout-flow/recording.yaml
+```
+
+Later:
+
+```
+replay({name: "checkout-flow", on_drift: "halt"})
+```
+
+Each step is gated on visual similarity: if the live screen has drifted from the recorded pre-screenshot, the replay halts (`halt`), warns and continues (`warn`), or proceeds blind (`force`). The recording is a self-contained YAML+PNG bundle you can commit to your repo.
+
+## Testing
+
+```bash
+pip install simdrive[dev]
+pytest                          # 22 unit tests, no sim required
+pytest -m live                  # 26 live tests against TestKitApp
+```
+
+Live tests boot a fresh TestKitApp session per test and exercise every tool: tap by text/mark/coords, type into focused fields, swipe-to-scroll, alert-while-focused dismissal (the iOS 26 case that defeated v15), record + replay with drift detection.
+
+## What this isn't
+
+- **Not** a real-device tool. v0.1 is simulator-only. Real device support via `idb`/`devicectl` is on the roadmap.
+- **Not** a CI replacement (yet). Designed for interactive Claude sessions; CI integration is a follow-up.
+- **Not** a fork of XCTest. We deliberately avoid Apple's testing stack to stay durable across Xcode releases.
+
+## License
+
+MIT. Built by [SyncTek](https://synctek.io).

simdrive-0.2.0a1/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simdrive"
+version = "0.2.0a1"
+description = "Hand your iOS simulator to your agent. Claude-native MCP driver for iOS simulator testing — vision, taps, recordings."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "SyncTek LLC", email = "info@synctek.io"},
+]
+keywords = ["ios", "simulator", "mcp", "claude", "testing", "qa", "agent", "anthropic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: MacOS",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "Pillow>=10.0",
+    "pyyaml>=6.0",
+    "mcp>=1.0",
+    "pyobjc-framework-Quartz>=10.0",
+    "pyobjc-framework-Vision>=10.0",
+]
+
+[project.urls]
+Homepage = "https://synctek.io/simdrive"
+Repository = "https://github.com/SyncTek-LLC/simdrive"
+Issues = "https://github.com/SyncTek-LLC/simdrive/issues"
+
+[project.optional-dependencies]
+ssim = ["scikit-image>=0.22"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+simdrive = "simdrive.server:serve"
+simdrive-mcp = "simdrive.server:serve"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+simdrive = ["_bin/simdrive-input"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "live: tests that require a booted iOS Simulator and Xcode",
+]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"

simdrive-0.2.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simdrive-0.2.0a1/setup.py

@@ -0,0 +1,64 @@
+"""Build hook: compile the native HID injection helper before packaging.
+
+This runs `make` in `native/` whenever setup builds the wheel. The output
+binary lands at `src/simdrive/_bin/simdrive-input` and is picked up by
+[tool.setuptools.package-data] in pyproject.toml.
+
+setup.py is intentionally minimal — pyproject.toml is the source of truth
+for project metadata.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+
+
+HERE = Path(__file__).parent
+NATIVE_DIR = HERE / "native"
+BINARY_PATH = HERE / "src" / "simdrive" / "_bin" / "simdrive-input"
+
+
+class BuildPyWithNative(build_py):
+    """build_py subclass that compiles the native HID helper as a pre-step."""
+
+    def run(self) -> None:
+        if platform.system() == "Darwin" and NATIVE_DIR.exists():
+            self._build_native()
+        else:
+            print(
+                f"simdrive: skipping native build (system={platform.system()}, "
+                f"native_dir_exists={NATIVE_DIR.exists()})",
+                file=sys.stderr,
+            )
+        super().run()
+
+    def _build_native(self) -> None:
+        if BINARY_PATH.exists() and os.environ.get("SIMDRIVE_SKIP_NATIVE_BUILD"):
+            print(f"simdrive: SIMDRIVE_SKIP_NATIVE_BUILD set; using existing {BINARY_PATH}")
+            return
+        print("simdrive: building native helper via make...")
+        try:
+            subprocess.run(
+                ["make", "clean", "all"],
+                cwd=str(NATIVE_DIR),
+                check=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise RuntimeError(
+                f"Native build failed (rc={exc.returncode}). "
+                "simdrive requires Xcode + macOS to compile its HID helper."
+            ) from exc
+        if not BINARY_PATH.exists():
+            raise RuntimeError(
+                f"Native build reported success but binary not found at {BINARY_PATH}"
+            )
+        print(f"simdrive: built {BINARY_PATH}")
+
+
+setup(cmdclass={"build_py": BuildPyWithNative})

simdrive-0.2.0a1/src/simdrive/__init__.py

@@ -0,0 +1,3 @@
+"""simdrive — hand your iOS simulator to your agent."""
+
+__version__ = "0.2.0a1"

simdrive-0.2.0a1/src/simdrive/act.py

@@ -0,0 +1,245 @@
+"""Synthetic input dispatch.
+
+Internal module. Coordinates passed in are screenshot pixels from the most
+recent observe; translated to logical iOS device points using the cached
+scale, then dispatched via the HID-injection backend.
+
+Three backends, in preference order:
+  1. hid    — bundled native helper (real UITouch events; focuses TextFields)
+  2. cliclick — synthetic mouse via the macOS window (fallback)
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Iterable, Optional
+
+from . import hid_inject, sim
+from .sim import cliclick_path
+from .window import WindowBounds, activate, get_bounds
+
+
+class ActError(RuntimeError):
+    """Raised when an act dispatch fails."""
+
+
+# Cache of UDID → (logical_w, logical_h, scale) from hid_inject.device_size_points()
+_DEVICE_GEOM_CACHE: dict[str, tuple[float, float, float]] = {}
+
+
+def _backend() -> str:
+    """Return which backend will be used. Override via SIMDRIVE_INPUT_BACKEND."""
+    requested = os.environ.get("SIMDRIVE_INPUT_BACKEND", "").lower()
+    if requested == "cliclick":
+        return "cliclick"
+    if hid_inject.available():
+        return "hid"
+    return "cliclick"
+
+
+def _device_geom(udid: str) -> tuple[float, float, float]:
+    cached = _DEVICE_GEOM_CACHE.get(udid)
+    if cached is not None:
+        return cached
+    geom = hid_inject.device_size_points(udid)
+    _DEVICE_GEOM_CACHE[udid] = geom
+    return geom
+
+
+def _pixels_to_points(udid: str, pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int) -> tuple[float, float]:
+    """Map a screenshot pixel coord to logical iOS device points for the HID path."""
+    if screenshot_w <= 0 or screenshot_h <= 0:
+        raise ActError(f"Invalid screenshot size: {screenshot_w}x{screenshot_h}")
+    logical_w, logical_h, _scale = _device_geom(udid)
+    px = (pixel_x / screenshot_w) * logical_w
+    py = (pixel_y / screenshot_h) * logical_h
+    return px, py
+
+
+def _pixels_to_screen(
+    bounds: WindowBounds, pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int
+) -> tuple[int, int]:
+    if screenshot_w <= 0 or screenshot_h <= 0:
+        raise ActError(f"Invalid screenshot size: {screenshot_w}x{screenshot_h}")
+    sx = bounds.x + (pixel_x / screenshot_w) * bounds.width
+    sy = bounds.y + (pixel_y / screenshot_h) * bounds.height
+    return int(round(sx)), int(round(sy))
+
+
+def _run_cliclick(args: Iterable[str], timeout: float = 5.0) -> None:
+    cli = cliclick_path()
+    cmd = [cli, *args]
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+    if res.returncode != 0:
+        raise ActError(f"cliclick failed (rc={res.returncode}): {res.stderr.strip() or res.stdout.strip()}")
+
+
+# ----------------------------- Public API ------------------------------ #
+
+
+def tap(pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int, udid: Optional[str] = None) -> tuple[int, int]:
+    """Click at screenshot-pixel coordinates. Returns the macOS screen coords used (or 0,0 for HID path)."""
+    if _backend() == "hid" and udid:
+        x_pt, y_pt = _pixels_to_points(udid, pixel_x, pixel_y, screenshot_w, screenshot_h)
+        hid_inject.tap(udid, x_pt, y_pt)
+        return (0, 0)
+
+    bounds = get_bounds()
+    sx, sy = _pixels_to_screen(bounds, pixel_x, pixel_y, screenshot_w, screenshot_h)
+    activate()
+    time.sleep(0.15)
+    _run_cliclick([f"c:{sx},{sy}"])
+    return sx, sy
+
+
+def swipe(
+    x1: int, y1: int, x2: int, y2: int, screenshot_w: int, screenshot_h: int, duration_ms: int = 300,
+    udid: Optional[str] = None,
+) -> None:
+    if _backend() == "hid" and udid:
+        x1p, y1p = _pixels_to_points(udid, x1, y1, screenshot_w, screenshot_h)
+        x2p, y2p = _pixels_to_points(udid, x2, y2, screenshot_w, screenshot_h)
+        steps = max(4, duration_ms // 25)
+        hid_inject.swipe(udid, x1p, y1p, x2p, y2p, steps=steps, step_delay_ms=25)
+        return
+
+    bounds = get_bounds()
+    sx1, sy1 = _pixels_to_screen(bounds, x1, y1, screenshot_w, screenshot_h)
+    sx2, sy2 = _pixels_to_screen(bounds, x2, y2, screenshot_w, screenshot_h)
+    activate()
+    time.sleep(0.15)
+    duration_ms = max(50, min(duration_ms, 5000))
+    steps = max(2, duration_ms // 30)
+    moves: list[str] = []
+    for i in range(1, steps + 1):
+        t = i / steps
+        mx = int(round(sx1 + (sx2 - sx1) * t))
+        my = int(round(sy1 + (sy2 - sy1) * t))
+        moves.append(f"m:{mx},{my}")
+    args = ["-w", "30", f"dd:{sx1},{sy1}", *moves, f"du:{sx2},{sy2}"]
+    _run_cliclick(args, timeout=10.0)
+
+
+def type_text(text: str, udid: Optional[str] = None) -> None:
+    """Send keystrokes. Caller is responsible for tapping a focused field first.
+
+    For non-ASCII characters (accented, emoji, non-Latin), falls back to the
+    pasteboard path: simctl pbcopy + Cmd-V — preserves the focused-field state
+    and works around the HID keyboard's US-ASCII-only key map.
+    """
+    if not text:
+        return
+
+    is_ascii = all(ord(c) < 128 for c in text)
+
+    if _backend() == "hid" and udid:
+        if is_ascii:
+            hid_inject.type_text(udid, text)
+            return
+        # Non-ASCII path: pbcopy + paste-shortcut
+        sim.set_pasteboard(udid, text)
+        time.sleep(0.05)
+        # Cmd-V via HID — issue Cmd modifier hold + V keypress
+        # HID usage 0xE3 = Left Cmd; 0x19 = V
+        _hid_paste(udid)
+        return
+
+    activate()
+    time.sleep(0.15)
+    _run_cliclick(["t:" + text])
+
+
+def _hid_paste(udid: str) -> None:
+    """Cmd-V via the HID helper — works in background mode."""
+    hid_inject.chord(udid, "cmd", "v")
+
+
+_CLICLICK_KEY_MAP = {
+    "return": "kp:return",
+    "enter": "kp:return",
+    "tab": "kp:tab",
+    "escape": "kp:esc",
+    "esc": "kp:esc",
+    "space": "kp:space",
+    "delete": "kp:delete",
+    "backspace": "kp:delete",
+    "arrow-up": "kp:arrow-up",
+    "arrow-down": "kp:arrow-down",
+    "arrow-left": "kp:arrow-left",
+    "arrow-right": "kp:arrow-right",
+}
+
+# HID usage codes for special keys (US layout, HID Keyboard/Keypad page)
+_HID_KEY_MAP = {
+    "return": 40,
+    "enter": 40,
+    "tab": 43,
+    "escape": 41,
+    "esc": 41,
+    "space": 44,
+    "delete": 42,
+    "backspace": 42,
+    "arrow-up": 82,
+    "arrow-down": 81,
+    "arrow-left": 80,
+    "arrow-right": 79,
+}
+
+_DEVICE_BUTTONS = {"home", "lock", "siri"}  # buttons routed to hid_inject.press_button
+
+# Sim-only buttons that go through Simulator's "Device" menu (cliclick fallback path).
+_DEVICE_MENU_KEYS = {
+    "home": "Home",
+    "lock": "Lock",
+    "shake": "Shake",
+    "siri": "Siri",
+    "app-switcher": "App Switcher",
+    "screenshot": "Trigger Screenshot",
+    "rotate-left": "Rotate Left",
+    "rotate-right": "Rotate Right",
+    "action-button": "Action Button",
+}
+
+
+def press_key(key: str, udid: Optional[str] = None) -> None:
+    key_lower = key.lower().strip()
+
+    if _backend() == "hid" and udid:
+        if key_lower in _DEVICE_BUTTONS:
+            hid_inject.press_button(udid, key_lower)
+            return
+        hid_code = _HID_KEY_MAP.get(key_lower)
+        if hid_code is not None:
+            hid_inject.press_key(udid, hid_code)
+            return
+        # fall through to cliclick path for unknown keys
+
+    if key_lower in _DEVICE_MENU_KEYS:
+        _menu_click("Device", _DEVICE_MENU_KEYS[key_lower])
+        return
+
+    cli_arg = _CLICLICK_KEY_MAP.get(key_lower)
+    if cli_arg is None:
+        raise ActError(
+            f"unsupported key: {key!r}. Supported: {sorted(_CLICLICK_KEY_MAP)} "
+            f"+ {sorted(_DEVICE_MENU_KEYS)}"
+        )
+    activate()
+    time.sleep(0.15)
+    _run_cliclick([cli_arg])
+
+
+def _menu_click(menu_title: str, item_title: str) -> None:
+    script = f'''
+    tell application "System Events"
+      tell process "Simulator"
+        click menu item "{item_title}" of menu "{menu_title}" of menu bar 1
+      end tell
+    end tell
+    '''
+    res = subprocess.run(
+        ["osascript", "-e", script], capture_output=True, text=True, timeout=5.0, check=False
+    )
+    if res.returncode != 0:
+        raise ActError(f"menu click {menu_title} > {item_title} failed: {res.stderr.strip()}")