Fix input reliability: ensureFocus, CGAssociate, conditional CGEvent, verbose logging

Three root causes fixed for reliable tap/swipe input:

1. Restore CGAssociateMouseAndMouseCursorPosition in tap(), swipe(), drag()
   Without disassociating before CGWarp, macOS suppresses relative HID events,
   silently dropping clicks even though cursor position is correct.

2. Make CGEvent focus click conditional (only when wasActive=false)
   Sending CGEvent when session is already established disrupts HID routing.
   Now only sends focus click when transitioning from inactive to active.

3. Poll for activation instead of fixed sleep
   app.activate() is async — poll app.isActive with RunLoop processing
   instead of Thread.sleep. Add detailed verbose logging for diagnostics.

Also includes: ensureFocus() with 5s cooldown in InputInjector, windowManager
pattern for auto-focus, new commands (drag, scroll, doctor, wait-for),
ActionResult JSON envelope, grid screenshot, OCR waitForText, and
open-source infrastructure (CI, CONTRIBUTING, CHANGELOG, SECURITY).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: berkozero

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What
+
+Brief description of changes.
+
+## Why
+
+Motivation and context.
+
+## How to Test
+
+Steps to verify — ideally against a real iPhone Mirroring session.
+
+## Checklist
+
+- [ ] `swift build` compiles without warnings
+- [ ] `swift test` passes
+- [ ] Tested against real iPhone Mirroring (if applicable)
+- [ ] `--json` output works for new/modified commands
+- [ ] Updated `skills/iphonebase/SKILL.md` if command interface changed

.github/workflows/ci.yml

@@ -16,4 +16,4 @@ jobs:
         run: swift build
 
       - name: Run tests
-        run: swift test
+        run: make test

AGENTS.md

@@ -0,0 +1,77 @@
+# iphonebase
+
+Swift CLI to control iPhone via macOS iPhone Mirroring. Built for AI agents (OpenClaw, Claude Code, MCP) and standalone terminal use.
+
+## Tech Stack
+
+- Swift 5.9+, macOS 14+ (requires Sequoia 15.0+ at runtime)
+- ArgumentParser 1.3.0
+- Frameworks: ScreenCaptureKit, Vision, CoreGraphics, AppKit
+- Karabiner-Elements required (DriverKit virtual HID for input injection)
+
+## Build & Run
+
+```
+swift build                                        # debug
+swift build -c release                             # release
+swift test                                         # run tests
+sudo cp .build/release/iphonebase /usr/local/bin/  # install
+```
+
+## Project Structure
+
+```
+Sources/
+  IPhoneBaseCore/        # Library
+    WindowManager.swift  # Find & focus iPhone Mirroring window
+    ScreenCapture.swift  # ScreenCaptureKit capture + grid overlay
+    OCREngine.swift      # Apple Vision text recognition
+    InputInjector.swift  # Karabiner DriverKit virtual HID input
+    HIDKeyMap.swift      # USB HID keycodes & character mappings
+    ActionResult.swift   # Shared JSON response envelope
+  iphonebase/            # CLI executable
+    IPhoneBase.swift     # Entry point, command registration
+    Commands/            # One file per command (13 commands)
+skills/
+  iphonebase/SKILL.md   # OpenClaw skill definition
+Tests/
+  IPhoneBaseCoreTests/   # Unit tests (HIDKeyMap)
+```
+
+## Adding a New Command
+
+1. Create `Sources/iphonebase/Commands/XxxCommand.swift`
+2. Implement `AsyncParsableCommand` (or `ParsableCommand` for sync-only)
+3. Add `XxxCommand.self` to the `subcommands` array in `IPhoneBase.swift`
+4. Include `--json` flag using the shared `ActionResult<T>` envelope
+5. Update `skills/iphonebase/SKILL.md` with the new command docs
+
+## Code Conventions
+
+- Import order: ArgumentParser, IPhoneBaseCore, Foundation
+- All commands support `--json` via shared `ActionResult<T>` envelope (`Sources/IPhoneBaseCore/ActionResult.swift`)
+- Results to stdout, debug/verbose to stderr
+- InputInjector pattern: `connect()` then `defer { disconnect() }`; set `windowBounds` for coordinate validation
+- Call `wm.bringToFront()` before any input injection
+- Errors: typed enums with `CustomStringConvertible`; throw `ExitCode.failure` for user errors
+- Commit messages: imperative mood ("Add feature" not "Added feature"), first line under 72 characters
+
+## Coordinate System (critical)
+
+- ScreenCapture captures at 2x retina resolution
+- OCR (Vision) returns normalized coords with bottom-left origin — must invert Y
+- `tap --text` handles conversion automatically; raw `tap x y` is relative to window (screen points)
+- All InputInjector operations use absolute screen coordinates (`window.bounds.origin + offset`)
+
+## Input Injection Gotchas
+
+- iPhone Mirroring blocks CGEvent clicks — only Karabiner virtual HID works
+- Tap sequence: `CGWarpMouseCursorPosition` → nudge-sync virtual pointer (3x 1px/-1px) → click via HID
+- Timing delays (`usleep`) throughout InputInjector are tuned values, not arbitrary
+- Karabiner daemon must be running (not just installed)
+
+## OpenClaw Skill
+
+- Skill at `skills/iphonebase/SKILL.md` follows AgentSkills spec (YAML frontmatter + markdown)
+- Requires `bins: ["iphonebase"]`, `os: ["darwin"]`
+- Install to `~/.openclaw/skills/` for agent discovery

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- `doctor` command — diagnostic check of all prerequisites (8 checks)
+- `wait-for` command — poll screen via OCR until text appears or timeout
+- `scroll` command — scroll up/down via mouse wheel with configurable clicks
+- `drag` command — smooth point-to-point drag with configurable steps
+- `--json` flag on all commands via shared `ActionResult<T>` envelope
+- `AGENTS.md` for cross-agent (Cursor, Codex, Copilot) compatibility
+- `SECURITY.md` vulnerability disclosure policy
+- `CHANGELOG.md`
+- PR template
+
+### Changed
+- All commands now return structured `ActionResult` JSON with `success`, `action`, `data`, `error`, `durationMs`
+- Improved input injection reliability with tuned timing and nudge-sync sequence
+- README rewritten with badges, agent quick start, comparison table
+
+## [0.1.0] - 2025-01-20
+
+### Added
+- Initial release
+- `status` command — check iPhone Mirroring availability
+- `screenshot` command — capture screen as PNG with optional grid overlay
+- `describe` command — OCR text detection with coordinates and confidence
+- `tap` command — tap by coordinates, text (OCR), or grid cell; double-tap and long-press support
+- `swipe` command — directional swipe with configurable start point and distance
+- `type` command — character-by-character text input via virtual HID
+- `key` command — named key press with modifier support (cmd, shift, opt, ctrl)
+- `home` command — navigate to iPhone home screen
+- `launch` command — open app by name via Spotlight search
+- `IPhoneBaseCore` library: WindowManager, ScreenCapture, OCREngine, InputInjector, HIDKeyMap
+- OpenClaw skill definition (`skills/iphonebase/SKILL.md`)
+- GitHub Actions CI (build + test on macOS 15)
+- Unit tests for HIDKeyMap
+
+[Unreleased]: https://github.com/berkozero/iphonebase/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/berkozero/iphonebase/releases/tag/v0.1.0

CLAUDE.md

@@ -1,54 +1,46 @@
 # iphonebase
 
-Swift CLI to control iPhone via macOS iPhone Mirroring. Built for AI agents (OpenClaw, Claude Code, MCP) and standalone terminal use.
+Swift CLI to control iPhone via macOS iPhone Mirroring. See also [AGENTS.md](AGENTS.md) for cross-agent instructions.
 
-## Tech Stack
-- Swift 5.9+, macOS 14+ (requires Sequoia 15.0+ at runtime)
-- ArgumentParser 1.3.0
-- Frameworks: ScreenCaptureKit, Vision, CoreGraphics, AppKit
-- Karabiner-Elements required (DriverKit virtual HID for input injection)
-
-## Build & Run
-swift build                                    # debug
-swift build -c release                         # release
-sudo cp .build/release/iphonebase /usr/local/bin/  # install
+## Build & Test
+```
+swift build                  # debug
+swift build -c release       # release
+swift test                   # tests
+```
 
 ## Project Structure
-- Sources/IPhoneBaseCore/ — library: WindowManager, ScreenCapture, OCREngine, InputInjector, HIDKeyMap
-- Sources/iphonebase/ — CLI entry point + Commands/
-- skills/iphonebase/ — OpenClaw skill definition (SKILL.md)
+- `Sources/IPhoneBaseCore/` — library: WindowManager, ScreenCapture, OCREngine, InputInjector, HIDKeyMap, ActionResult
+- `Sources/iphonebase/` — CLI entry point + Commands/
+- `skills/iphonebase/` — OpenClaw skill (SKILL.md)
 
 ## Adding a New Command
-1. Create Sources/iphonebase/Commands/XxxCommand.swift
-2. Implement AsyncParsableCommand (or ParsableCommand for sync-only)
-3. Add XxxCommand.self to subcommands array in IPhoneBase.swift
-4. Include --json flag for structured output
+1. Create `Sources/iphonebase/Commands/XxxCommand.swift`
+2. Implement `AsyncParsableCommand` (or `ParsableCommand` for sync-only)
+3. Add `XxxCommand.self` to subcommands array in `IPhoneBase.swift`
+4. Include `--json` flag for structured output
+5. Update `skills/iphonebase/SKILL.md`
 
 ## Code Conventions
 - Import order: ArgumentParser, IPhoneBaseCore, Foundation
-- All commands support --json (use JSONSerialization with .prettyPrinted)
+- All commands support `--json` via shared `ActionResult<T>` envelope
 - Results to stdout, debug/verbose to stderr
-- InputInjector pattern: connect() then defer { disconnect() }
-- Call wm.bringToFront() before any input injection
-- Errors: typed enums with CustomStringConvertible; throw ExitCode.failure for user errors
+- InputInjector pattern: `connect()` then `defer { disconnect() }`; set `windowBounds` for coordinate validation
+- Call `wm.bringToFront()` before any input injection
+- Errors: typed enums with `CustomStringConvertible`; throw `ExitCode.failure` for user errors
 
 ## Coordinate System (critical)
 - ScreenCapture captures at 2x retina resolution
 - OCR (Vision) returns normalized coords with bottom-left origin — must invert Y
-- tap --text handles conversion automatically; raw tap x y is relative to window (screen points)
-- All InputInjector operations use absolute screen coordinates (window.bounds.origin + offset)
+- `tap --text` handles conversion automatically; raw `tap x y` is relative to window (screen points)
+- All InputInjector operations use absolute screen coordinates (`window.bounds.origin + offset`)
 
 ## Input Injection Gotchas
 - iPhone Mirroring blocks CGEvent clicks — only Karabiner virtual HID works
-- Tap sequence: CGWarp cursor → nudge-sync virtual pointer (3x 1px/-1px) → click via HID
-- Timing delays (usleep) throughout InputInjector are tuned values, not arbitrary
+- Tap sequence: CGWarp cursor → nudge-sync (3x 1px/-1px) → click via HID
+- Timing delays (`usleep`) are tuned values, not arbitrary
 - Karabiner daemon must be running (not just installed)
 
-## OpenClaw Skill
-- Skill at skills/iphonebase/SKILL.md follows AgentSkills spec (YAML frontmatter + markdown)
-- Requires bins: ["iphonebase"], os: ["darwin"]
-- Install to ~/.openclaw/skills/ for agent discovery
-
 ## Commits
 - Imperative mood ("Add feature" not "Added feature")
 - First line under 72 characters

CONTRIBUTING.md

@@ -13,6 +13,8 @@ Open a [GitHub issue](https://github.com/berkozero/iphonebase/issues/new?templat
 
 If a command fails silently, re-run with `--verbose` (where supported) and include the stderr output.
 
+For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
 ## Suggesting Features
 
 Open a [feature request](https://github.com/berkozero/iphonebase/issues/new?template=feature_request.md). Describe the use case, not just the solution.
@@ -23,6 +25,7 @@ Open a [feature request](https://github.com/berkozero/iphonebase/issues/new?temp
 git clone https://github.com/berkozero/iphonebase.git
 cd iphonebase
 swift build
+swift test
 ```
 
 Requirements:
@@ -35,23 +38,24 @@ Requirements:
 
 1. Fork the repo and create a branch from `main`
 2. Make your changes
-3. Test against a real iPhone Mirroring session
-4. Run `swift build` to verify it compiles
+3. Run `swift build` and `swift test`
+4. Test against a real iPhone Mirroring session
 5. Open a pull request with a clear description of what and why
 
+### When Adding or Changing Commands
+
+- Update `skills/iphonebase/SKILL.md` with the new command docs
+- Add an entry to `CHANGELOG.md` under `[Unreleased]`
+- Ensure `--json` output works via the `ActionResult<T>` envelope
+
 ### Code Style
 
-- Follow existing conventions in the codebase
+- Follow existing conventions (see [AGENTS.md](AGENTS.md) for details)
 - Keep functions focused and small
-- Use `--json` output for any new commands
 - Write to stderr for debug/verbose output, stdout for results
 
 ### Commit Messages
 
 - Use imperative mood ("Add feature" not "Added feature")
 - First line under 72 characters
 - Explain *why*, not just *what*, in the body if needed
-
-## Code of Conduct
-
-This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Be kind and constructive.

Makefile

@@ -1,4 +1,7 @@
-.PHONY: build release install test clean
+.PHONY: build release install test test-device test-all clean
+
+# Swift Testing framework path (ships with Command Line Tools, not in default search path)
+TESTING_FW = /Library/Developer/CommandLineTools/Library/Developer/Frameworks
 
 build:
 	swift build
@@ -10,7 +13,16 @@ install: release
 	cp .build/release/iphonebase /usr/local/bin/
 
 test:
-	swift test
+	swift test \
+		-Xswiftc -F -Xswiftc $(TESTING_FW) \
+		-Xlinker -F -Xlinker $(TESTING_FW) \
+		-Xlinker -rpath -Xlinker $(TESTING_FW) \
+		--enable-swift-testing --disable-xctest
+
+test-device: build
+	@bash tests/smoke-test.sh
+
+test-all: test test-device
 
 clean:
 	swift package clean

Package.resolved

@@ -1,4 +1,4 @@
-// swift-tools-version: 5.9
+// swift-tools-version: 6.0
 
 import PackageDescription
 
@@ -9,13 +9,14 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.3.0"),
+        .package(url: "https://github.com/apple/swift-testing.git", from: "0.12.0"),
     ],
     targets: [
         .target(
             name: "IPhoneBaseCore",
             dependencies: [],
+            swiftSettings: [.swiftLanguageMode(.v5)],
             linkerSettings: [
-                .linkedFramework("ScreenCaptureKit"),
                 .linkedFramework("Vision"),
                 .linkedFramework("CoreGraphics"),
                 .linkedFramework("AppKit"),
@@ -26,11 +27,15 @@ let package = Package(
             dependencies: [
                 "IPhoneBaseCore",
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
-            ]
+            ],
+            swiftSettings: [.swiftLanguageMode(.v5)]
         ),
         .testTarget(
             name: "IPhoneBaseCoreTests",
-            dependencies: ["IPhoneBaseCore"]
+            dependencies: [
+                "IPhoneBaseCore",
+                .product(name: "Testing", package: "swift-testing"),
+            ]
         ),
     ]
 )