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

{sim_mirror-0.2.0 → sim_mirror-1.2.0}/.gitignore

@@ -14,6 +14,14 @@ coverage.json
 coverage.xml
 htmlcov/
 
+# Swift
+helper/.build/
+helper/.swiftpm/
+/.build/
+/.swiftpm/
+xcuserdata/
+*.xcresult
+
 # Node
 node_modules/
 viewer/dist/

{sim_mirror-0.2.0 → sim_mirror-1.2.0}/NOTICE

@@ -6,6 +6,9 @@ This product is licensed under the Apache License, Version 2.0 (see LICENSE).
 It includes third-party material under its own licenses; see THIRD_PARTY_LICENSES.md:
 - idb_companion's gRPC protocol definition (facebook/idb), MIT License,
   Copyright (c) Meta Platforms, Inc. and affiliates.
+- In the native helper, simulator input and accessibility bridges written after facebook/idb's
+  FBSimulatorControl (MIT License, Copyright (c) Meta Platforms, Inc. and affiliates) and
+  EvanBacon/serve-sim (Apache License 2.0, Copyright 2026 Evan Bacon).
 - Icon paths from Lucide (lucide.dev), ISC License,
   Copyright (c) Lucide Contributors 2022; portions Copyright (c) Cole Bemis 2013-2022 (Feather, MIT).
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sim-mirror
-Version: 0.2.0
+Version: 1.2.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
@@ -28,6 +28,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: fastapi<1,>=0.115
 Requires-Dist: grpclib<0.5,>=0.4.9
+Requires-Dist: pillow<13,>=11.1
 Requires-Dist: protobuf<8,>=7.36
 Requires-Dist: tomli>=2; python_version < '3.11'
 Requires-Dist: tomlkit>=0.13
@@ -51,8 +52,9 @@ A live iOS Simulator in any browser tab or web page, an animated cursor that sho
 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: first public preview (v0.1).** The tools, the viewer and the protocol work today; the embedding API and
-> protocol become stable with v1.0.
+> **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.
 
 ## Why SimMirror
 
@@ -62,6 +64,8 @@ Claude Code, Codex, Cursor and any other MCP client.
   the spot first -- so you can follow along, and step in: an agent waits for your hand to be still.
 - **Spend fewer tokens.** Agents read accessibility snapshots with stable element refs and diffs between screens, act
   in batches with waits, and reach for a screenshot only when a question is visual.
+- **Read screens accessibility cannot.** A game or a canvas reads from its pixels, and an app under development can
+  share its own views, so icon-only buttons and hand-drawn controls read by name.
 
 ## Install
 
@@ -75,7 +79,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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.0 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -84,14 +88,18 @@ 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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0
+uv tool install sim-mirror==1.2.0
+# or
+brew install andrewkochulab/tap/sim-mirror
 ```
 
-**The viewer library**, for your own pages: the npm package `@andrewkochulab/sim-mirror`, attached to each
-[release](https://github.com/AndrewKochulab/sim-mirror/releases). Homebrew and PyPI come with v1.0.
+**The viewer library**, for your own pages: `npm install @andrewkochulab/sim-mirror`
+([npm](https://www.npmjs.com/package/@andrewkochulab/sim-mirror)). SimMirror itself is
+[on PyPI](https://pypi.org/project/sim-mirror/) and in a [Homebrew tap](https://github.com/AndrewKochulab/homebrew-tap).
 
-**Requirements:** an Apple Silicon Mac, Xcode 26 or later, [uv](https://docs.astral.sh/uv/), and for touching the
-screen, idb_companion (`brew install facebook/fb/idb-companion`). Details in [Installation](docs/installation.md).
+**Requirements:** an Apple Silicon Mac, Xcode 26 or later, and [uv](https://docs.astral.sh/uv/) or Homebrew. Nothing
+else: SimMirror drives a simulator with its own helper, which comes in the package. Details in
+[Installation](docs/installation.md).
 
 ## Quickstart
 
@@ -118,10 +126,22 @@ the viewer's own pointer glides there first (`agent.cursor_lead_ms`). Never the
 
 **Screen understanding.** A snapshot is a few lines -- `e2 button "General" (201,319)` -- with refs that stay with their
 elements across scrolls, a digest, and diffs. `sim_act` plays up to 20 steps in one call and waits for text, its
-absence, or the screen to settle. See [Screen understanding](docs/screen-understanding.md).
+absence, or the screen to settle -- past a spinner or a pulsing dot that never stops. See
+[Screen understanding](docs/screen-understanding.md).
 
-**Connectors.** idb_companion gives full control; without it the simctl connector still mirrors the screen, view-only,
-and says why. More connectors plug in through an entry point. See [Connectors](docs/connectors.md).
+**Reading pixels.** A screen whose accessibility says nothing -- a game, a canvas, an app still loading -- reads as the
+text macOS's Vision finds in it, with refs to tap and text to wait for, and the viewer can outline what was read
+(`perception.ocr`). See [Read from pixels](docs/screen-understanding.md#read-from-pixels).
+
+**App SDK.** An app under development can link **SimMirrorKit**, a small Swift package, and call `SimMirror.start()`:
+in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so an icon-only button, a card with a tap
+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).
+
+**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
+[Connectors](docs/connectors.md).
 
 **Embedding.** An [iframe](docs/embedding/iframe.md) with a one-shot ticket, the
 [`<sim-mirror>` element](docs/embedding/web-component.md) themed with CSS custom properties, or SimMirror
@@ -131,8 +151,8 @@ and says why. More connectors plug in through an entry point. See [Connectors](d
 saved for one project or all of them and applied before it says so. Settings that decide what runs or who may reach
 the daemon wait for a code from `sim-mirror settings confirm`. See [The settings panel](docs/settings.md).
 
-**Doctor.** Checks Xcode, its Simulator frameworks, runtimes, idb_companion, Device Hub and the desktop session, then
-proves a tap reaches a simulator. See [the doctor](docs/doctor.md).
+**Doctor.** Checks Xcode, its Simulator frameworks, runtimes, the native helper and idb_companion, Device Hub and the
+desktop session, the text reader and an app's shared hierarchy, then proves a tap reaches a simulator. See [the doctor](docs/doctor.md).
 
 **Security.** Loopback only, a Host allowlist, exact Origin checks, CORS and framing only for origins you list, hashed
 scoped tokens, and one-shot codes in URL fragments. See [Security](docs/security.md).
@@ -164,15 +184,16 @@ an image at about 750 pixels a token).
 |---|---|
 | macOS | 26 (15 with Xcode 16.4, view-only) |
 | Xcode | 26 and 27 |
-| Connectors | idb_companion 1.5 (full control), simctl (view-only) |
+| Connectors | native helper (full control), idb_companion 1.5 (full control), simctl (view-only) |
+| 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 |
 
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
-While SimMirror is `0.x`, the tools, the protocol and the embedding API can still change in a minor release, and the
-changelog says when they do; from 1.0 they are held to [what SimMirror promises not to break](docs/stability.md). Pin
-an exact version either way.
+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
+exception, and pin a minor version.
 
 ## Documentation
 
@@ -185,12 +206,11 @@ the [command line](docs/reference/cli.md) and the [protocol](docs/reference/prot
 | Milestone | What it brings |
 |---|---|
 | **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 |
-| **v1.0** | Stable protocol and embedding API, PyPI and npm packages, the MCP registry |
-| **v1.1** | Build, run and test tools become stable |
-| **v1.2** | Richer screen understanding, a native Swift helper, Xcode 27 `mcpbridge` connector, one shared daemon for many hosts |
+| **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 |
 | **Android** | Android emulator support with the same viewer, cursor and tools |
-| **Homebrew** | `brew install andrewkochulab/tap/sim-mirror`, right after v1.0 |
 | **Website & launch** | Landing page, video tutorials and guides |
 
 See [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/AndrewKochulab/sim-mirror/milestones). How

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

@@ -15,8 +15,9 @@ A live iOS Simulator in any browser tab or web page, an animated cursor that sho
 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: first public preview (v0.1).** The tools, the viewer and the protocol work today; the embedding API and
-> protocol become stable with v1.0.
+> **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.
 
 ## Why SimMirror
 
@@ -26,6 +27,8 @@ Claude Code, Codex, Cursor and any other MCP client.
   the spot first -- so you can follow along, and step in: an agent waits for your hand to be still.
 - **Spend fewer tokens.** Agents read accessibility snapshots with stable element refs and diffs between screens, act
   in batches with waits, and reach for a screenshot only when a question is visual.
+- **Read screens accessibility cannot.** A game or a canvas reads from its pixels, and an app under development can
+  share its own views, so icon-only buttons and hand-drawn controls read by name.
 
 ## Install
 
@@ -39,7 +42,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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.0 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -48,14 +51,18 @@ 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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0
+uv tool install sim-mirror==1.2.0
+# or
+brew install andrewkochulab/tap/sim-mirror
 ```
 
-**The viewer library**, for your own pages: the npm package `@andrewkochulab/sim-mirror`, attached to each
-[release](https://github.com/AndrewKochulab/sim-mirror/releases). Homebrew and PyPI come with v1.0.
+**The viewer library**, for your own pages: `npm install @andrewkochulab/sim-mirror`
+([npm](https://www.npmjs.com/package/@andrewkochulab/sim-mirror)). SimMirror itself is
+[on PyPI](https://pypi.org/project/sim-mirror/) and in a [Homebrew tap](https://github.com/AndrewKochulab/homebrew-tap).
 
-**Requirements:** an Apple Silicon Mac, Xcode 26 or later, [uv](https://docs.astral.sh/uv/), and for touching the
-screen, idb_companion (`brew install facebook/fb/idb-companion`). Details in [Installation](docs/installation.md).
+**Requirements:** an Apple Silicon Mac, Xcode 26 or later, and [uv](https://docs.astral.sh/uv/) or Homebrew. Nothing
+else: SimMirror drives a simulator with its own helper, which comes in the package. Details in
+[Installation](docs/installation.md).
 
 ## Quickstart
 
@@ -82,10 +89,22 @@ the viewer's own pointer glides there first (`agent.cursor_lead_ms`). Never the
 
 **Screen understanding.** A snapshot is a few lines -- `e2 button "General" (201,319)` -- with refs that stay with their
 elements across scrolls, a digest, and diffs. `sim_act` plays up to 20 steps in one call and waits for text, its
-absence, or the screen to settle. See [Screen understanding](docs/screen-understanding.md).
+absence, or the screen to settle -- past a spinner or a pulsing dot that never stops. See
+[Screen understanding](docs/screen-understanding.md).
 
-**Connectors.** idb_companion gives full control; without it the simctl connector still mirrors the screen, view-only,
-and says why. More connectors plug in through an entry point. See [Connectors](docs/connectors.md).
+**Reading pixels.** A screen whose accessibility says nothing -- a game, a canvas, an app still loading -- reads as the
+text macOS's Vision finds in it, with refs to tap and text to wait for, and the viewer can outline what was read
+(`perception.ocr`). See [Read from pixels](docs/screen-understanding.md#read-from-pixels).
+
+**App SDK.** An app under development can link **SimMirrorKit**, a small Swift package, and call `SimMirror.start()`:
+in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so an icon-only button, a card with a tap
+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).
+
+**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
+[Connectors](docs/connectors.md).
 
 **Embedding.** An [iframe](docs/embedding/iframe.md) with a one-shot ticket, the
 [`<sim-mirror>` element](docs/embedding/web-component.md) themed with CSS custom properties, or SimMirror
@@ -95,8 +114,8 @@ and says why. More connectors plug in through an entry point. See [Connectors](d
 saved for one project or all of them and applied before it says so. Settings that decide what runs or who may reach
 the daemon wait for a code from `sim-mirror settings confirm`. See [The settings panel](docs/settings.md).
 
-**Doctor.** Checks Xcode, its Simulator frameworks, runtimes, idb_companion, Device Hub and the desktop session, then
-proves a tap reaches a simulator. See [the doctor](docs/doctor.md).
+**Doctor.** Checks Xcode, its Simulator frameworks, runtimes, the native helper and idb_companion, Device Hub and the
+desktop session, the text reader and an app's shared hierarchy, then proves a tap reaches a simulator. See [the doctor](docs/doctor.md).
 
 **Security.** Loopback only, a Host allowlist, exact Origin checks, CORS and framing only for origins you list, hashed
 scoped tokens, and one-shot codes in URL fragments. See [Security](docs/security.md).
@@ -128,15 +147,16 @@ an image at about 750 pixels a token).
 |---|---|
 | macOS | 26 (15 with Xcode 16.4, view-only) |
 | Xcode | 26 and 27 |
-| Connectors | idb_companion 1.5 (full control), simctl (view-only) |
+| Connectors | native helper (full control), idb_companion 1.5 (full control), simctl (view-only) |
+| 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 |
 
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
-While SimMirror is `0.x`, the tools, the protocol and the embedding API can still change in a minor release, and the
-changelog says when they do; from 1.0 they are held to [what SimMirror promises not to break](docs/stability.md). Pin
-an exact version either way.
+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
+exception, and pin a minor version.
 
 ## Documentation
 
@@ -149,12 +169,11 @@ the [command line](docs/reference/cli.md) and the [protocol](docs/reference/prot
 | Milestone | What it brings |
 |---|---|
 | **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 |
-| **v1.0** | Stable protocol and embedding API, PyPI and npm packages, the MCP registry |
-| **v1.1** | Build, run and test tools become stable |
-| **v1.2** | Richer screen understanding, a native Swift helper, Xcode 27 `mcpbridge` connector, one shared daemon for many hosts |
+| **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 |
 | **Android** | Android emulator support with the same viewer, cursor and tools |
-| **Homebrew** | `brew install andrewkochulab/tap/sim-mirror`, right after v1.0 |
 | **Website & launch** | Landing page, video tutorials and guides |
 
 See [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/AndrewKochulab/sim-mirror/milestones). How

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

@@ -33,6 +33,33 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## The native helper's simulator bridges
+
+- **What:** in the native helper, how it reaches a simulator's input and accessibility through Apple's private
+  frameworks: the DTUHID message shapes, the Indigo message builder signatures and the accessibility translator
+  bridge (`helper/Sources/HelperPlatform/HIDTransports.swift`, `AccessibilityReader.swift`), written for SimMirror in
+  Swift after these projects' Objective-C and Swift.
+- **Sources:** [facebook/idb](https://github.com/facebook/idb)'s FBSimulatorControl, under the MIT License quoted
+  above (Copyright (c) Meta Platforms, Inc. and affiliates); and [EvanBacon/serve-sim](https://github.com/EvanBacon/serve-sim),
+  under the Apache License 2.0, the same license as SimMirror's own (see LICENSE).
+- **License:** MIT; Apache-2.0
+
+```
+Copyright 2026 Evan Bacon
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
 ## Lucide icons
 
 - **What:** the SVG path data of the icons drawn by the viewer (`viewer/src/icons.ts`).
@@ -57,5 +84,5 @@ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
 
-Runtime dependencies installed from PyPI and npm (FastAPI, Uvicorn, grpclib, protobuf, tomlkit and others) are not
-redistributed here; each carries its own license in its package.
+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-0.2.0 → sim_mirror-1.2.0}/docs/README.md

@@ -30,6 +30,8 @@
 
 - [Screen understanding](screen-understanding.md) -- snapshots, refs, diffs, waits, and what each costs
 - [Connectors](connectors.md) -- how SimMirror reaches a device, and what each can do
+- [The app SDK](app-sdk.md) -- an app under development shares its own UIKit and SwiftUI views, so screens
+  without accessibility labels read well
 - [Security](security.md) -- the threat model and what keeps the daemon to itself
 - [Architecture](architecture.md) -- the parts, the seams and the rules between them
 - [Compatibility](compatibility.md) -- where SimMirror is expected to work, and where it was checked

{sim_mirror-0.2.0 → sim_mirror-1.2.0}/examples/README.md

@@ -13,6 +13,8 @@ Each folder is one way to use SimMirror, small enough to copy.
 | [fastapi-embed](fastapi-embed/) | A Python host application mounting SimMirror's routers under its own paths, with its own sign-in |
 | [custom-connector](custom-connector/) | A connector of your own, installed through the `sim_mirror.connectors` entry point, with contract tests |
 | [token-budget](token-budget/) | Measuring what each tool's answer costs an agent |
+| [app-sdk](app-sdk/) | An iOS app sharing its own views through SimMirrorKit: icon buttons, a tap gesture, a hand-drawn control with a describer, `.simMirror` tags |
 
 Every example assumes a Mac with Xcode and a booted-or-bootable simulator, and `sim-mirror doctor` passing. The
-examples are tested with SimMirror's own suite (`tests/examples/`), without starting a simulator.
+examples are tested with SimMirror's own suite (`tests/examples/`), without starting a simulator; app-sdk's hosted
+tests run on a simulator with `make sdk-app-test`.

{sim_mirror-0.2.0 → sim_mirror-1.2.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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==1.2.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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror open
+uvx --from sim-mirror==1.2.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-0.2.0 → sim_mirror-1.2.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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==1.2.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-0.2.0 → sim_mirror-1.2.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 git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==1.2.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-0.2.0 → sim_mirror-1.2.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 @ git+https://github.com/AndrewKochulab/sim-mirror@v0.2.0" \
+EXAMPLE_KEY=change-me uv run --with "sim-mirror==1.2.0" \
   uvicorn --factory app:create_app --port 7484
 ```
 

sim_mirror-1.2.0/helper/Package.swift

@@ -0,0 +1,35 @@
+// swift-tools-version:6.0
+// SPDX-License-Identifier: Apache-2.0
+//
+// SimMirror's native helper: the screen, input and element tree of one booted simulator, served to SimMirror on a unix
+// socket -- without idb_companion.
+//
+// `HelperCore` is everything that can be decided without a simulator: the wire protocol, what a screenshot or a stream
+// is cut to, how input maps onto each HID transport, and how an accessibility tree becomes SimMirror's document. It is
+// unit-tested to the per-file coverage bar. `HelperPlatform` is the thin layer that reaches Apple's private simulator
+// frameworks through the Objective-C runtime; it is exercised against real simulators by SimMirror's live suite.
+
+import PackageDescription
+
+let package = Package(
+    name: "SimMirrorHelper",
+    platforms: [.macOS(.v14)],
+    products: [
+        .executable(name: "sim-mirror-helper", targets: ["sim-mirror-helper"]),
+    ],
+    targets: [
+        .target(name: "HelperCore"),
+        .target(name: "ObjCGuard"),
+        .target(
+            name: "HelperPlatform",
+            dependencies: ["HelperCore", "ObjCGuard"],
+            swiftSettings: [.swiftLanguageMode(.v5)]
+        ),
+        .executableTarget(
+            name: "sim-mirror-helper",
+            dependencies: ["HelperCore", "HelperPlatform"],
+            swiftSettings: [.swiftLanguageMode(.v5)]
+        ),
+        .testTarget(name: "HelperCoreTests", dependencies: ["HelperCore"]),
+    ]
+)

sim_mirror-1.2.0/helper/Sources/HelperCore/Accessibility.swift

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+import Foundation
+
+/// A rectangle in points, from the top left.
+public struct Rect: Equatable, Sendable {
+    public let x: Double
+    public let y: Double
+    public let width: Double
+    public let height: Double
+
+    public init(x: Double, y: Double, width: Double, height: Double) {
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+    }
+
+    var json: JSONValue {
+        .object(["x": .number(x), "y": .number(y), "width": .number(width), "height": .number(height)])
+    }
+}
+
+/// An accessibility value: text, a number, or a switch's state.
+public enum AccessibilityValue: Equatable, Sendable {
+    case text(String)
+    case number(Double)
+
+    var json: JSONValue {
+        switch self {
+        case .text(let text): return .string(text)
+        case .number(let number): return .number(number)
+        }
+    }
+}
+
+/// One element of a screen's accessibility tree, read from the device.
+///
+/// Only what SimMirror reads of an element is kept. Each attribute is a round trip to the simulator, and a snapshot
+/// reads every element, so an attribute nothing reads -- a role's description, help text, custom actions -- is not
+/// asked for at all.
+public struct AXNode: Equatable, Sendable {
+    /// Its role as the accessibility API says it, ``AXButton``.
+    public var role: String?
+    public var subrole: String?
+    public var label: String?
+    public var title: String?
+    public var identifier: String?
+    public var value: AccessibilityValue?
+    public var frame: Rect
+    /// Its traits as the bits iOS keeps them in; nil when it does not say.
+    public var traits: UInt64?
+    public var enabled: Bool
+    public var children: [AXNode]
+
+    public init(
+        role: String? = nil, subrole: String? = nil, label: String? = nil, title: String? = nil,
+        identifier: String? = nil, value: AccessibilityValue? = nil, frame: Rect = Rect(x: 0, y: 0, width: 0, height: 0),
+        traits: UInt64? = nil, enabled: Bool = true, children: [AXNode] = []
+    ) {
+        self.role = role
+        self.subrole = subrole
+        self.label = label
+        self.title = title
+        self.identifier = identifier
+        self.value = value
+        self.frame = frame
+        self.traits = traits
+        self.enabled = enabled
+        self.children = children
+    }
+}
+
+/// The names of the traits iOS gives an element, bit by bit.
+///
+/// The bits are AXRuntime's ``kAX*Trait`` constants, which run from 0 upward in this order; the names are the constants
+/// less their prefix and suffix, which is how idb_companion names them too.
+public enum AXTraits {
+    public static let names = [
+        "Button", "Link", "Image", "Selected", "PlaysSound", "KeyboardKey", "StaticText", "SummaryElement",
+        "NotEnabled", "UpdatesFrequently", "SearchField", "StartsMediaSession", "Adjustable",
+        "AllowsDirectInteraction", "CausesPageTurn", "TabBar", "Header", "WebContent", "TextEntry", "PickerElement",
+        "RadioButton", "IsEditing", "LaunchIcon", "StatusBarElement", "SecureTextField", "Inactive", "Footer",
+        "BackButton", "TabButton", "AutoCorrectCandidate", "DeleteKey", "SelectionDismissesItem", "Visited",
+        "Scrollable", "Spacer", "TableIndex", "Map", "TextOperationsAvailable", "Draggable", "GesturePracticeRegion",
+        "PopupButton", "AllowsNativeSliding", "MathEquation", "ContainedByTable", "ContainedByList", "TouchContainer",
+        "SupportsZoom", "TextArea", "BookContent", "ContainedByLandmark", "FolderIcon", "ReadOnly", "MenuItem",
+        "Toggle", "IgnoreItemChooser", "SupportsTrackingDetail", "Alert", "ContainedByFieldset",
+        "AllowsLayoutChangeInStatusBar",
+    ]
+
+    /// The names of the bits set: ``None`` for none, and ``Unknown`` for bits no name is known for.
+    public static func names(_ mask: UInt64) -> [String] {
+        guard mask != 0 else { return ["None"] }
+        var found = names.indices.filter { mask & (1 << UInt64($0)) != 0 }.map { names[$0] }
+        if mask >> UInt64(names.count) != 0 { found.append("Unknown") }
+        return found
+    }
+}
+
+/// The document SimMirror reads a screen from: the tree of the elements a person or an agent can act on or read.
+///
+/// Its shape is idb_companion's consolidated accessibility document, with the keys SimMirror reads, so SimMirror reads
+/// either one the same way. The
+/// tree keeps what is worth reporting -- an element with a label, an identifier, or a role that is acted on -- and an
+/// element that is not has its kept descendants take its place, so a button inside an unlabelled group is kept.
+public enum AXDocument {
+    /// The roles, less their ``AX`` prefix, that are kept whatever they say.
+    public static let actionableRoles: Set<String> = [
+        "Button", "Cell", "TextField", "SecureTextField", "SearchField", "Switch", "Toggle", "Link", "MenuItem",
+        "Slider", "CheckBox", "RadioButton", "SegmentedControl", "Stepper", "PopUpButton", "Picker", "PickerWheel",
+        "Tab", "Key", "DisclosureTriangle",
+    ]
+
+    public static func make(root: AXNode, screen: ScreenGeometry) -> JSONValue {
+        let elements = kept(root)
+        return .object([
+            "backend": .string("native"),
+            "elements": .array(elements),
+            "modal": .null,
+            "screen": .object([
+                "coordinate_space": .string("screen"),
+                "width": .int(screen.widthPt),
+                "height": .int(screen.heightPt),
+            ]),
+            "truncated": .bool(false),
+        ])
+    }
+
+    /// A role without its ``AX`` prefix: ``AXButton`` is ``Button``.
+    public static func type(of role: String?) -> String? {
+        guard let role else { return nil }
+        return role.hasPrefix("AX") ? String(role.dropFirst(2)) : role
+    }
+
+    static func keeps(_ node: AXNode) -> Bool {
+        if let label = node.label, !label.isEmpty { return true }
+        if let identifier = node.identifier, !identifier.isEmpty { return true }
+        return type(of: node.role).map(actionableRoles.contains) ?? false
+    }
+
+    static func kept(_ node: AXNode) -> [JSONValue] {
+        let children = node.children.flatMap(kept)
+        guard keeps(node) else { return children }
+        return [element(node, children: children)]
+    }
+
+    static func element(_ node: AXNode, children: [JSONValue]) -> JSONValue {
+        .object([
+            "type": .text(type(of: node.role)),
+            "subrole": .text(node.subrole),
+            "label": .text(node.label),
+            "title": .text(node.title),
+            "identifier": .text(node.identifier),
+            "value": node.value?.json ?? .null,
+            "frame": node.frame.json,
+            "traits": node.traits.map { .array(AXTraits.names($0).map(JSONValue.string)) } ?? .null,
+            "enabled": .bool(node.enabled),
+            "children": .array(children),
+        ])
+    }
+}