sim-mirror 1.2.0__tar.gz → 2.0.0__tar.gz

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sim-mirror
-Version: 1.2.0
+Version: 2.0.0
 Summary: Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.
 Project-URL: Homepage, https://github.com/AndrewKochulab/sim-mirror
 Project-URL: Documentation, https://github.com/AndrewKochulab/sim-mirror/tree/main/docs
@@ -45,16 +45,21 @@ Description-Content-Type: text/markdown
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/AndrewKochulab/sim-mirror?include_prereleases&sort=semver)](https://github.com/AndrewKochulab/sim-mirror/releases)
 
-![A Claude Code session tapping through Settings on an iPhone 17 Pro simulator in the viewer, its cursor named
-and drawn before each tap](docs/media/hero.gif)
+<img src="docs/media/hero.gif" width="100%"
+  alt="A Claude Code session driving a calendar app on an iPhone 17 simulator in the viewer: it opens an event, scrolls
+through its notes, then fills in and saves a new one, the agent's cursor gliding to each spot before it taps">
+
+*A real session, sped up four times. [The whole recording](https://github.com/AndrewKochulab/sim-mirror/releases/download/v1.2.0/sim-mirror-plugin-demo.mp4)
+runs 1m 39s.*
 
 A live iOS Simulator in any browser tab or web page, an animated cursor that shows exactly what your AI agent is about
 to tap, and token-efficient UI snapshots so agents read the screen as compact text instead of screenshots. Works with
 Claude Code, Codex, Cursor and any other MCP client.
 
-> **Status: 1.2.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
-> 1.x release to [what SimMirror promises not to break](docs/stability.md). 1.2 drives simulators with SimMirror's own
-> helper, reads a screen from its pixels when accessibility says nothing, and lets an app share its own views.
+> **Status: 2.0.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
+> release to [what SimMirror promises not to break](docs/stability.md). 2.0 brings real iPhones and iPads beside the
+> simulators -- live over the cable, driven through WebDriverAgent -- and records any screen as an MP4 or a GIF. It
+> removes nothing 1.x promised.
 
 ## Why SimMirror
 
@@ -79,7 +84,7 @@ Claude Code, Codex, Cursor and any other MCP client.
 **Any MCP client**, as a stdio server:
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -88,7 +93,7 @@ Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.
 **The command**, for `sim-mirror open`, `doctor` and the rest:
 
 ```sh
-uv tool install sim-mirror==1.2.0
+uv tool install sim-mirror==2.0.0
 # or
 brew install andrewkochulab/tap/sim-mirror
 ```
@@ -138,6 +143,14 @@ in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so
 gesture or a hand-drawn control reads by name, and `.simMirror("Settings")` names a SwiftUI view. Optional, and nothing
 of it is in a Release build. See [The app SDK](docs/app-sdk.md).
 
+**Real devices.** A cabled iPhone or iPad shows up beside the simulators: its live screen over the cable, its apps,
+logs, look and location through Xcode's `devicectl`, and touching, typing and its element tree through a WebDriverAgent
+you build with your own team. What SimMirror changes on it is put back when it is let go. See
+[Real devices](docs/real-devices.md).
+
+**Recording.** The viewer's Record button, `sim_record` or `sim-mirror record` keep a device's screen as an MP4, a GIF
+or both, with each touch drawn where it landed and a 9:41 status bar. See [Recording](docs/recording.md).
+
 **Connectors.** SimMirror's own native helper gives full control with nothing to install; idb_companion still can,
 and the simctl connector mirrors the screen view-only when neither is there, and says why. `auto` uses the fastest that
 works and falls back when one fails. More connectors plug in through an entry point. See
@@ -185,6 +198,7 @@ an image at about 750 pixels a token).
 | macOS | 26 (15 with Xcode 16.4, view-only) |
 | Xcode | 26 and 27 |
 | Connectors | native helper (full control), idb_companion 1.5 (full control), simctl (view-only) |
+| Real devices | an iPhone or iPad that Xcode's `devicectl` reaches, by cable (view-only without WebDriverAgent) |
 | App SDK | Debug builds on the iOS Simulator, iOS 16 or later |
 | Clients | Claude Code, Codex, Cursor, any stdio MCP client |
 | Browsers | Chrome, Safari, Firefox, Edge |
@@ -192,7 +206,7 @@ an image at about 750 pixels a token).
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
 From 1.0 the tools, the protocol, the embedding API, the viewer package, settings and the command line are held to
-[what SimMirror promises not to break](docs/stability.md): a 1.x release adds, and never breaks. Connectors are the
+[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing. Connectors are the
 exception, and pin a minor version.
 
 ## Documentation
@@ -208,8 +222,8 @@ the [command line](docs/reference/cli.md) and the [protocol](docs/reference/prot
 | **v0.1** (preview) | Live viewer, agent cursor, person and agent control, MCP tools, `sim-mirror doctor`, idb and simctl connectors, build and test as a preview |
 | **v0.2** | Build, run and test tools, a settings panel, Xcode 27's UI hierarchy through `mcpbridge`, one shared daemon for many hosts |
 | **v1.0** | Stable protocol and embedding API, held by a check; PyPI, npm and the MCP Registry; a cursor that stays while the agent works |
-| **v1.2** (now) | SimMirror's own native helper instead of idb_companion, screens read from their pixels and settling past endless animations, an optional in-app debug SDK, and a Homebrew tap |
-| **v2.0** | Real iPhones: view, install and launch without signing; full control through WebDriverAgent |
+| **v1.2** | SimMirror's own native helper instead of idb_companion, screens read from their pixels and settling past endless animations, an optional in-app debug SDK, and a Homebrew tap |
+| **v2.0** (now) | Real iPhones and iPads: the live screen over the cable, apps, logs, look and location without signing; full control through WebDriverAgent; recording a screen as an MP4 or GIF |
 | **Android** | Android emulator support with the same viewer, cursor and tools |
 | **Website & launch** | Landing page, video tutorials and guides |
 

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/README.md

@@ -8,16 +8,21 @@
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/AndrewKochulab/sim-mirror?include_prereleases&sort=semver)](https://github.com/AndrewKochulab/sim-mirror/releases)
 
-![A Claude Code session tapping through Settings on an iPhone 17 Pro simulator in the viewer, its cursor named
-and drawn before each tap](docs/media/hero.gif)
+<img src="docs/media/hero.gif" width="100%"
+  alt="A Claude Code session driving a calendar app on an iPhone 17 simulator in the viewer: it opens an event, scrolls
+through its notes, then fills in and saves a new one, the agent's cursor gliding to each spot before it taps">
+
+*A real session, sped up four times. [The whole recording](https://github.com/AndrewKochulab/sim-mirror/releases/download/v1.2.0/sim-mirror-plugin-demo.mp4)
+runs 1m 39s.*
 
 A live iOS Simulator in any browser tab or web page, an animated cursor that shows exactly what your AI agent is about
 to tap, and token-efficient UI snapshots so agents read the screen as compact text instead of screenshots. Works with
 Claude Code, Codex, Cursor and any other MCP client.
 
-> **Status: 1.2.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
-> 1.x release to [what SimMirror promises not to break](docs/stability.md). 1.2 drives simulators with SimMirror's own
-> helper, reads a screen from its pixels when accessibility says nothing, and lets an app share its own views.
+> **Status: 2.0.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
+> release to [what SimMirror promises not to break](docs/stability.md). 2.0 brings real iPhones and iPads beside the
+> simulators -- live over the cable, driven through WebDriverAgent -- and records any screen as an MP4 or a GIF. It
+> removes nothing 1.x promised.
 
 ## Why SimMirror
 
@@ -42,7 +47,7 @@ Claude Code, Codex, Cursor and any other MCP client.
 **Any MCP client**, as a stdio server:
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -51,7 +56,7 @@ Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.
 **The command**, for `sim-mirror open`, `doctor` and the rest:
 
 ```sh
-uv tool install sim-mirror==1.2.0
+uv tool install sim-mirror==2.0.0
 # or
 brew install andrewkochulab/tap/sim-mirror
 ```
@@ -101,6 +106,14 @@ in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so
 gesture or a hand-drawn control reads by name, and `.simMirror("Settings")` names a SwiftUI view. Optional, and nothing
 of it is in a Release build. See [The app SDK](docs/app-sdk.md).
 
+**Real devices.** A cabled iPhone or iPad shows up beside the simulators: its live screen over the cable, its apps,
+logs, look and location through Xcode's `devicectl`, and touching, typing and its element tree through a WebDriverAgent
+you build with your own team. What SimMirror changes on it is put back when it is let go. See
+[Real devices](docs/real-devices.md).
+
+**Recording.** The viewer's Record button, `sim_record` or `sim-mirror record` keep a device's screen as an MP4, a GIF
+or both, with each touch drawn where it landed and a 9:41 status bar. See [Recording](docs/recording.md).
+
 **Connectors.** SimMirror's own native helper gives full control with nothing to install; idb_companion still can,
 and the simctl connector mirrors the screen view-only when neither is there, and says why. `auto` uses the fastest that
 works and falls back when one fails. More connectors plug in through an entry point. See
@@ -148,6 +161,7 @@ an image at about 750 pixels a token).
 | macOS | 26 (15 with Xcode 16.4, view-only) |
 | Xcode | 26 and 27 |
 | Connectors | native helper (full control), idb_companion 1.5 (full control), simctl (view-only) |
+| Real devices | an iPhone or iPad that Xcode's `devicectl` reaches, by cable (view-only without WebDriverAgent) |
 | App SDK | Debug builds on the iOS Simulator, iOS 16 or later |
 | Clients | Claude Code, Codex, Cursor, any stdio MCP client |
 | Browsers | Chrome, Safari, Firefox, Edge |
@@ -155,7 +169,7 @@ an image at about 750 pixels a token).
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
 From 1.0 the tools, the protocol, the embedding API, the viewer package, settings and the command line are held to
-[what SimMirror promises not to break](docs/stability.md): a 1.x release adds, and never breaks. Connectors are the
+[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing. Connectors are the
 exception, and pin a minor version.
 
 ## Documentation
@@ -171,8 +185,8 @@ the [command line](docs/reference/cli.md) and the [protocol](docs/reference/prot
 | **v0.1** (preview) | Live viewer, agent cursor, person and agent control, MCP tools, `sim-mirror doctor`, idb and simctl connectors, build and test as a preview |
 | **v0.2** | Build, run and test tools, a settings panel, Xcode 27's UI hierarchy through `mcpbridge`, one shared daemon for many hosts |
 | **v1.0** | Stable protocol and embedding API, held by a check; PyPI, npm and the MCP Registry; a cursor that stays while the agent works |
-| **v1.2** (now) | SimMirror's own native helper instead of idb_companion, screens read from their pixels and settling past endless animations, an optional in-app debug SDK, and a Homebrew tap |
-| **v2.0** | Real iPhones: view, install and launch without signing; full control through WebDriverAgent |
+| **v1.2** | SimMirror's own native helper instead of idb_companion, screens read from their pixels and settling past endless animations, an optional in-app debug SDK, and a Homebrew tap |
+| **v2.0** (now) | Real iPhones and iPads: the live screen over the cable, apps, logs, look and location without signing; full control through WebDriverAgent; recording a screen as an MP4 or GIF |
 | **Android** | Android emulator support with the same viewer, cursor and tools |
 | **Website & launch** | Landing page, video tutorials and guides |
 

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/THIRD_PARTY_LICENSES.md

@@ -84,5 +84,48 @@ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
 
+## WebDriverAgent
+
+- **What:** the XCTest runner SimMirror uses to touch, type on and read a real device
+  ([Real devices](docs/real-devices.md#tier-2-webdriveragent)). It is **not** shipped: `sim-mirror wda setup` fetches
+  release 16.12.10 (commit `00c38220c3e84906c965b996ffc4c12d09fef62f`), checks its SHA-256, makes two changes -- its
+  screen stream is bound to the device's loopback, as its API is, and a point of a touch is used where it is given
+  rather than looked up against the app -- and builds it on your Mac with your team.
+- **Source:** [appium/WebDriverAgent](https://github.com/appium/WebDriverAgent), first written by Facebook.
+- **License:** BSD-3-Clause
+
+```
+BSD License
+
+For WebDriverAgent software
+
+Copyright (c) 2015-present, Facebook, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
 Runtime dependencies installed from PyPI and npm (FastAPI, Uvicorn, grpclib, protobuf, tomlkit, Pillow and others) are
 not redistributed here; each carries its own license in its package.

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/docs/README.md

@@ -13,6 +13,12 @@
 - [Cursor](clients/cursor.md)
 - [Any other MCP client](clients/other-mcp.md)
 
+## Use it with a real device, and record
+
+- [Real devices](real-devices.md) -- a cabled iPhone or iPad: its live screen, apps and logs, and WebDriverAgent for
+  touch, typing and the element tree
+- [Recording](recording.md) -- a screen as an MP4 or a GIF, with each touch drawn, and a demo in a pull request
+
 ## Change its settings
 
 - [The settings panel](settings.md) -- every setting from the viewer, and a code at the terminal for the ones a page

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/docs/media/README.md

@@ -4,17 +4,18 @@ Pictures the README and the docs show. Every clone carries every picture ever co
 keeps them small: a GIF at most 3 MB, a still image at most 400 KB, the folder at most 25 MB. Videos are attached to a
 GitHub Release instead.
 
-Captured from real runs, never mocked up. All of these were taken on 2026-09-16 from one machine -- macOS 26.6.2,
-Xcode 26.6, an iPhone 17 Pro simulator on iOS 26.5 -- with SimMirror 0.1.0:
+Captured from real runs, never mocked up. Most were taken on 2026-09-16 from one machine -- macOS 26.6.2, Xcode 26.6,
+an iPhone 17 Pro simulator on iOS 26.5 -- with SimMirror 0.1.0; a row says so when its picture came from a later run:
 
 | File | Shows | How it was made |
 |---|---|---|
-| `hero.gif` | A Claude Code session tapping through Settings, its cursor drawn before each tap | Frames of the viewer while a real Claude Code session drove the device over MCP -- which is why the cursor's chip reads `claude-code` and the device says it is in use |
-| `cursor.gif` | The agent cursor gliding to a row and the screen following | The same run, the moment around one tap |
+| `hero.gif` | A Claude Code session reading and writing calendar events, its cursor drawn before each tap | A screen recording made later, on 2026-09-17 with SimMirror 1.2.0, Xcode 27.0 and an iPhone 17 simulator on iOS 27.0, of a real Claude Code session driving a calendar app over MCP -- which is why the cursor's chip reads `claude-code` and the device says it is in use. Sped up four times and cut to 700 px wide to stay under the GIF limit; [the whole recording](https://github.com/AndrewKochulab/sim-mirror/releases/download/v1.2.0/sim-mirror-plugin-demo.mp4) is attached to the 1.2.0 release |
+| `cursor.gif` | The agent cursor gliding to a row and the screen following | The 2026-09-16 Settings run, the moment around one tap |
 | `viewer.png` | The viewer in a browser tab | A screenshot of the tab, live |
 | `snapshot-vs-screenshot.png` | A snapshot beside a screenshot of the same screen | The real answers of `sim_screenshot` and `sim_snapshot`, taken a moment apart, set side by side with their measured token estimates |
 | `iframe.png` | The viewer framed in another page | The `examples/iframe` page on its own origin, with a one-shot embed ticket |
 | `view-only.png` | The view-only mirror without idb_companion | The same viewer with `connectors.idb.companion_path` pointed at nothing, so the simctl connector serves it |
 | `doctor.png` | `sim-mirror doctor` on a Mac | The real output of `sim-mirror doctor --no-tap`, typeset for the docs rather than photographed from a terminal |
-| `social-preview.png` | GitHub's social preview, 1280×640 | The project's name and claims beside a frame of `hero.gif` |
+| `social-preview.png` | GitHub's social preview, 1280×640 | The project's name and claims beside a frame of the Settings run `hero.gif` showed until 1.2.0 |
+| `recording-demo.gif` | A recording an agent made: Settings › Appearance switched to dark and back, its taps drawn | `sim_record` itself, on 2026-09-29 with Xcode 27.0 and an iPhone 18 Pro simulator on iOS 27.0: an agent started a GIF recording with the demo status bar, tapped through Settings with `sim_act`, and stopped it; the file is as `sim_record stop` kept it, 600 px wide |
 | `settings-panel.png` | The settings panel's Server tab | A screenshot of the panel in Chrome, taken later on 2026-09-16 with Xcode 27.0 and an iOS 27.0 simulator, from a daemon started with `SIM_MIRROR_SERVER_PORT=7491` -- which is why the port shows as locked |

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/examples/claude-code-cli/README.md

@@ -16,7 +16,7 @@ Its tools are named `mcp__plugin_sim-mirror_sim-mirror__sim_snapshot` and so on.
 ## Without the plugin
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
 ```
 
 Add `--scope project` before the name to write it to the project's `.mcp.json` for everyone working on it. Its tools
@@ -30,7 +30,7 @@ simulator (its scope) and this folder as the only place builds and installs may
 ## Watch it
 
 ```sh
-uvx --from sim-mirror==1.2.0 sim-mirror open
+uvx --from sim-mirror==2.0.0 sim-mirror open
 ```
 
 opens this folder's viewer in your browser. Every gesture the agent makes is drawn there as a cursor just before it

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/examples/codex/README.md

@@ -6,7 +6,7 @@ Add [config.toml](config.toml)'s table to `~/.codex/config.toml`, then start Cod
   and installs may reach. The commented `args` pin a project by name and path instead.
 - `tool_timeout_sec` is raised because `sim_build_run` and `sim_test` can take minutes (they are there only when build
   tools are switched on).
-- Watch and take over in a browser: `uvx --from sim-mirror==1.2.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==2.0.0 sim-mirror open`
   in the same folder.
 
 The tools are the same for every client; see [claude-code-cli](../claude-code-cli/) for a first prompt to try.

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/examples/cursor/README.md

@@ -6,7 +6,7 @@ one), and enable the server in Cursor's MCP settings.
 - `sim-mirror mcp` gives the agent the simulator of the folder it starts in, and that folder as the only place builds
   and installs may reach. If the tools act on the wrong project, append `"--scope", "my-app", "--root",
   "/absolute/path/to/my-app"` to `args`.
-- Watch and take over in a browser: `uvx --from sim-mirror==1.2.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==2.0.0 sim-mirror open`
   in the same folder.
 
 The tools are the same for every client; see [claude-code-cli](../claude-code-cli/) for a first prompt to try.

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/examples/fastapi-embed/README.md

@@ -5,7 +5,7 @@ A Python application with SimMirror inside it: [app.py](app.py). No daemon runs;
 
 ```sh
 cd examples/fastapi-embed
-EXAMPLE_KEY=change-me uv run --with "sim-mirror==1.2.0" \
+EXAMPLE_KEY=change-me uv run --with "sim-mirror==2.0.0" \
   uvicorn --factory app:create_app --port 7484
 ```
 

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/helper/Package.swift

@@ -28,7 +28,15 @@ let package = Package(
         .executableTarget(
             name: "sim-mirror-helper",
             dependencies: ["HelperCore", "HelperPlatform"],
-            swiftSettings: [.swiftLanguageMode(.v5)]
+            swiftSettings: [.swiftLanguageMode(.v5)],
+            // The Info.plist macOS reads to ask for the Camera, which reading a cabled device's screen needs, embedded
+            // in the program itself.
+            linkerSettings: [
+                .unsafeFlags([
+                    "-Xlinker", "-sectcreate", "-Xlinker", "__TEXT", "-Xlinker", "__info_plist",
+                    "-Xlinker", "\(Context.packageDirectory)/Support/Info.plist",
+                ]),
+            ]
         ),
         .testTarget(name: "HelperCoreTests", dependencies: ["HelperCore"]),
     ]

{sim_mirror-1.2.0 → sim_mirror-2.0.0}/helper/Sources/HelperCore/Arguments.swift

@@ -10,12 +10,21 @@ public enum Command: Equatable, Sendable {
     /// Reach a device the way serving would -- its screen, a picture, input and the element tree -- say what worked as
     /// JSON, and exit 0 only if all of it did.
     case selfCheck(DeviceOptions)
+    /// Render a recording as the job at a path asks -- an MP4, a GIF, its touches drawn in -- say what it wrote as JSON,
+    /// and exit.
+    case render(job: String)
+    /// Serve a cabled real device's screen, read through AVFoundation, on a unix socket until SimMirror lets go of it.
+    case capture(CaptureOptions)
 
     public static let usage = """
         usage: sim-mirror-helper version
                sim-mirror-helper serve --udid UDID --socket PATH [--parent-pid PID] [--hid auto|dtuhid|indigo]
                                        [--idle-key-frames on|off] [--log-level debug|info|warning|error]
                sim-mirror-helper self-check --udid UDID [--hid auto|dtuhid|indigo]
+               sim-mirror-helper render --job PATH
+               sim-mirror-helper capture --udid UDID --name NAME --socket PATH --width-px N --height-px N --scale N
+                                         [--capture-id ID] [--reference PATH] [--parent-pid PID] [--wait SECONDS] [--linger SECONDS]
+                                         [--idle-key-frames on|off] [--log-level debug|info|warning|error]
         """
 
     public static func parse(_ arguments: [String]) throws -> Command {
@@ -39,6 +48,16 @@ public enum Command: Equatable, Sendable {
             let device = try DeviceOptions.take(&options)
             try refuseLeftovers(options)
             return .selfCheck(device)
+        case "render":
+            guard let job = options.removeValue(forKey: "job"), job.hasPrefix("/") else {
+                throw HelperFailure("render needs --job and the absolute path of its job\n\(usage)", status: 400)
+            }
+            try refuseLeftovers(options)
+            return .render(job: job)
+        case "capture":
+            let capture = try CaptureOptions.take(&options)
+            try refuseLeftovers(options)
+            return .capture(capture)
         default:
             throw HelperFailure("not a command: \(verb)\n\(usage)", status: 400)
         }
@@ -122,18 +141,23 @@ public struct ServeOptions: Equatable, Sendable {
 
 /// What `sim-mirror-helper version` prints.
 public struct VersionReport: Equatable, Sendable, Encodable {
+    /// What this helper can do besides serving a simulator, so SimMirror asks only a helper that can.
+    public static let features = ["render", "capture"]
+
     public let version: String
     public let wire: Int
     public let coreSimulator: String?
+    public let features: [String]
 
     public init(coreSimulator: String?) {
         version = HelperVersion.current
         wire = Wire.version
         self.coreSimulator = coreSimulator
+        features = VersionReport.features
     }
 
     enum CodingKeys: String, CodingKey {
-        case version, wire, coreSimulator = "core_simulator"
+        case version, wire, coreSimulator = "core_simulator", features
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -141,6 +165,7 @@ public struct VersionReport: Equatable, Sendable, Encodable {
         try container.encode(version, forKey: .version)
         try container.encode(wire, forKey: .wire)
         try container.encode(coreSimulator, forKey: .coreSimulator)
+        try container.encode(features, forKey: .features)
     }
 }
 

sim_mirror-2.0.0/helper/Sources/HelperCore/Capture.swift

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+import Foundation
+
+/// What `sim-mirror-helper capture` is asked to serve: a cabled real device's screen, read the way QuickTime reads it.
+public struct CaptureOptions: Equatable, Sendable {
+    /// The device's hardware UDID, as SimMirror knows it.
+    public let udid: String
+    /// The device's name, which is what its screen is called among the Mac's capture devices.
+    public let name: String
+    public let socket: String
+    /// The screen as devicectl measures it: its pixels and scale. The capture's own pixels may differ by one.
+    public let screen: ScreenGeometry
+    /// The capture device SimMirror found this device to be before, tried first.
+    public let captureId: String?
+    /// A picture of the screen taken another way, to tell apart devices that share a name.
+    public let reference: String?
+    public let parentPid: Int32?
+    public let idleKeyFrames: Bool
+    /// How long a picture of the screen is waited for: the first capture after the cable is plugged in switches it
+    /// into another mode, measured at 6.4 seconds on an iPhone 14 Pro (2026-09-29).
+    public let waitS: Double
+    /// How long the capture keeps running after the last picture was asked for, so the next one is quick.
+    public let lingerS: Double
+    public let logLevel: Log.Level
+
+    public init(
+        udid: String, name: String, socket: String, screen: ScreenGeometry, captureId: String? = nil, reference: String? = nil,
+        parentPid: Int32? = nil, idleKeyFrames: Bool = true, waitS: Double = CaptureOptions.defaultWaitS,
+        lingerS: Double = CaptureOptions.defaultLingerS, logLevel: Log.Level = .info
+    ) {
+        self.udid = udid
+        self.name = name
+        self.socket = socket
+        self.screen = screen
+        self.captureId = captureId
+        self.reference = reference
+        self.parentPid = parentPid
+        self.idleKeyFrames = idleKeyFrames
+        self.waitS = waitS
+        self.lingerS = lingerS
+        self.logLevel = logLevel
+    }
+
+    public static let defaultWaitS = 15.0
+    public static let waitRange = 1.0...120.0
+    public static let defaultLingerS = 30.0
+    public static let lingerRange = 0.0...600.0
+
+    static func take(_ options: inout [String: String]) throws -> CaptureOptions {
+        func required(_ key: String) throws -> String {
+            guard let value = options.removeValue(forKey: key), !value.isEmpty else {
+                throw HelperFailure("capture needs --\(key)\n\(Command.usage)", status: 400)
+            }
+            return value
+        }
+        func number(_ key: String) throws -> Double {
+            let text = try required(key)
+            guard let value = Double(text), value.isFinite else { throw HelperFailure("--\(key) is a number, not \(text)", status: 400) }
+            return value
+        }
+        func seconds(_ key: String, _ range: ClosedRange<Double>, otherwise: Double) throws -> Double {
+            guard let text = options.removeValue(forKey: key) else { return otherwise }
+            guard let value = Double(text), range.contains(value) else {
+                throw HelperFailure("--\(key) is \(Int(range.lowerBound)) to \(Int(range.upperBound)) seconds, not \(text)", status: 400)
+            }
+            return value
+        }
+        let udid = try required("udid")
+        let name = try required("name")
+        let socket = try required("socket")
+        let screen = try ScreenGeometry.of(pixelWidth: number("width-px"), pixelHeight: number("height-px"), scale: number("scale"))
+        let reference = options.removeValue(forKey: "reference")
+        if let reference, !reference.hasPrefix("/") {
+            throw HelperFailure("--reference is the absolute path of a picture, not \(reference)", status: 400)
+        }
+        return CaptureOptions(
+            udid: udid, name: name, socket: socket, screen: screen, captureId: options.removeValue(forKey: "capture-id"),
+            reference: reference, parentPid: try options.removeValue(forKey: "parent-pid").map(Command.pid),
+            idleKeyFrames: try options.removeValue(forKey: "idle-key-frames").map(Command.onOff) ?? true,
+            waitS: try seconds("wait", waitRange, otherwise: defaultWaitS),
+            lingerS: try seconds("linger", lingerRange, otherwise: defaultLingerS),
+            logLevel: try options.removeValue(forKey: "log-level").map(Command.logLevel) ?? .info
+        )
+    }
+}
+
+
+/// One of the Mac's capture devices that shows a cabled device's screen.
+public struct CaptureCandidate: Equatable, Sendable {
+    public let id: String
+    public let name: String
+
+    public init(id: String, name: String) {
+        self.id = id
+        self.name = name
+    }
+}
+
+/// Which capture device is the one asked for.
+///
+/// A capture device is named for the device it shows, but its id is its own -- not the device's UDID -- so it is found
+/// by the id it had before, else by its name, else, when several devices share the name, by which of them shows the
+/// picture of the screen taken another way (`Likeness`).
+public enum CaptureChoice: Equatable, Sendable {
+    case use(String)
+    /// Several are called that: the one whose screen looks like the reference.
+    case compare([String])
+    case none
+
+    public static func pick(_ candidates: [CaptureCandidate], name: String, captureId: String?) -> CaptureChoice {
+        if let captureId, candidates.contains(where: { $0.id == captureId }) { return .use(captureId) }
+        let named = candidates.filter { $0.name == name }.map(\.id)
+        switch named.count {
+        case 0: return .none
+        case 1: return .use(named[0])
+        default: return .compare(named)
+        }
+    }
+}
+
+/// How alike two pictures of a screen are, each shrunk to the same few grey pixels: the mean difference, 0 to 255.
+///
+/// A screen captured by cable and one taken by devicectl a moment apart differ in the clock and little else, so the
+/// device whose picture is nearest the reference is the one the reference was taken of.
+public enum Likeness {
+    /// The size pictures are shrunk to before they are compared.
+    public static let width = 12
+    public static let height = 26
+
+    public static func distance(_ one: [UInt8], _ other: [UInt8]) -> Double? {
+        guard one.count == other.count, !one.isEmpty else { return nil }
+        let total = zip(one, other).reduce(0) { $0 + abs(Int($1.0) - Int($1.1)) }
+        return Double(total) / Double(one.count)
+    }
+
+    /// The index of the picture nearest the reference, or nil when none can be compared with it.
+    public static func nearest(_ reference: [UInt8], among pictures: [[UInt8]?]) -> Int? {
+        let scored = pictures.enumerated().compactMap { index, picture in
+            picture.flatMap { distance(reference, $0) }.map { (index, $0) }
+        }
+        return scored.min { $0.1 < $1.1 }?.0
+    }
+}
+
+/// Whether a captured picture is turned from the portrait SimMirror serves: a device held on its side sends its
+/// screen wider than tall, and it is turned back a quarter so points map onto it as they do in portrait.
+public enum CaptureTurn: Equatable, Sendable {
+    case none
+    case quarter
+
+    public static func of(width: Int, height: Int) -> CaptureTurn {
+        width > height ? .quarter : .none
+    }
+}
+
+/// When the capture runs: while anything holds it -- a stream -- and for a while after the last picture was asked for,
+/// so a device's status bar reads 9:41 and its cable carries a picture only while someone is looking.
+public struct CaptureDemand: Equatable, Sendable {
+    public let lingerS: Double
+    public private(set) var holders = 0
+    public private(set) var lastWanted: Double?
+
+    public init(lingerS: Double) {
+        self.lingerS = lingerS
+    }
+
+    /// Something needs the capture from now until it lets go.
+    public mutating func hold(at time: Double) {
+        holders += 1
+        lastWanted = time
+    }
+
+    public mutating func release(at time: Double) {
+        holders = max(0, holders - 1)
+        lastWanted = time
+    }
+
+    /// Whether the capture should be running at `time`.
+    public func running(at time: Double) -> Bool {
+        guard let lastWanted else { return false }
+        return holders > 0 || time - lastWanted < lingerS
+    }
+
+    /// When nothing will need the capture any more if nothing asks again, or nil while something holds it.
+    public func idleAt() -> Double? {
+        guard holders == 0, let lastWanted else { return nil }
+        return lastWanted + lingerS
+    }
+}
+
+/// Whether this process is the one that asks macOS for the Camera, or has to start one that is.
+///
+/// macOS asks permission of a process's responsible process: under a terminal or an agent, that is the terminal or the
+/// agent, which has not asked for the Camera and never will, so the capture quietly gets no pictures. Started again
+/// with its responsibility disclaimed, the helper is its own responsible process and asks for itself.
+public enum Disclaim {
+    public static let variable = "SIM_MIRROR_HELPER_DISCLAIMED"
+
+    public static func needed(_ environment: [String: String]) -> Bool {
+        environment[variable] != "1"
+    }
+}