> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Simulator

> A macOS-only drawer in Work that builds, launches, mirrors, inspects, and controls a booted iOS Simulator — and turns a tapped SwiftUI view into source-anchored chat context.

The **iOS Simulator** drawer drives the system iOS Simulator from inside ADE's Work tab. It discovers your launchable iOS targets, builds and launches the app, mirrors the running Simulator window into the drawer, and turns drawer gestures into either simulator input or context for the active chat. When you tap a SwiftUI view in inspect mode, the agent gets the element's **source file and line** — not a guess from stale code.

> [!NOTE]
>
> This feature is **macOS-only**. `xcrun`, `xcodebuild`, and Simulator.app must be available on the runtime host. `idb` and `idb_companion` are optional but unlock direct tap, drag, text, and accessibility-backed inspection.

## What the drawer does

> [card] Build & launch
>
> Discover Xcode projects, DerivedData app bundles, and installed simulator apps, then build, install, and launch the one you pick.

> [card] Mirror the live view
>
> Stream the real Simulator.app window into the drawer, parked behind ADE so it stays out of your way.

> [card] Inspect & select
>
> Tap an element to capture it as chat context — with its component id, source file, and line when the app is annotated.

> [card] Control
>
> Tap, drag, swipe, and type into the running app when `idb` and `idb_companion` are installed.

## Source-anchored inspection

The magic of the drawer is **ADE Inspector**, a debug-only Swift kit that lives inside the iOS app under inspection. When you annotate a view with `.adeInspectable("settingsButton")`, the kit publishes a per-frame JSON snapshot of every annotated view's frame, component id, and source location into the app's data container.

When you tap in inspect mode, ADE correlates that snapshot with a fresh screenshot and attaches the matched element to your chat as a context chip carrying the component id, the source file and line, and a screenshot of the hit. The agent reasons about *that* view at *that* line, not the surrounding container.

**1. Annotate the views you care about**

Wrap buttons, list rows, and headline labels with `.adeInspectable("componentId")` and mount `.adeInspectorHost()` once near the root. The kit is `#if DEBUG`-only — release builds compile it to a no-op.

**2. Launch the app in the drawer**

ADE builds and launches your selected target, then mirrors the Simulator window into Work.

**3. Tap in inspect mode**

A tap resolves the SwiftUI view under your finger and produces a context item.

**4. Send it to the agent**

The element lands in the chat composer as a chip with the source file and line baked in.

> [!TIP]
>
> Annotate selectively. The snapshot already drops zero-area and off-screen frames, but tagging every structural container inflates the JSON and creates ambiguous hit-tests. Tag the views you'll actually want to talk about.

## When the app isn't annotated

ADE Inspector is opt-in, and inspection degrades gracefully:

* **Accessibility fallback** — with `idb` installed, a tap falls through to the OS accessibility tree, so the agent still gets labels and roles (just no source file or line).
* **Coordinate fallback** — without `idb`, ADE still attaches the screenshot and the hit coordinates, so the agent can reason about the region.

## Preview Lab

Beyond a running app, the drawer can render SwiftUI **previews**. It discovers nearby `#Preview` and `PreviewProvider` definitions, ranks the best match for your selected source file or last-tapped element, opens Xcode when needed, and renders the preview into ADE's Preview drawer — a one-shot bridge from "the view I just selected" to "show me what it looks like."

## One owner per session

Each launched simulator session has one owning chat or lane. If a second chat tries to launch against an active session, it's told the simulator is owned by another session until the current owner releases it or you force a shutdown.

## A simulator on another Mac

A chat can use the simulator on another of your Macs without moving there. `ade apple launch --machine "Mac Studio"` with no lane builds the chat's work copy on that Mac (see [remote machines](https://ade-app.dev/docs/tools/remote-machines.md#use-another-machine-from-the-chat-you-are-in)) and runs it on a simulator that Mac already has and no lane holds. ADE creates a new simulator only when none is free, and never deletes one it borrowed. The drawer then offers **Simulator · Mac Studio** beside **This lane**, so you can switch between them.

## Drive it from the CLI

Everything the drawer does is also available from the `ade apple` command group (`ade ios-sim` is an older name for it), so an agent can build, launch, inspect, and control the simulator headlessly. Use `--socket` so the CLI and the desktop drawer share the same live session, selection, and proof state.

> [accordion] ade apple commands
>
> ```bash theme={null}
> ade --socket apple status --text          # tool readiness checklist
> ade --socket apple devices --text         # list simulators
> ade --socket apple apps --text             # list launch targets
> ade --socket apple launch --target <id> --text
> ade --socket apple live-start --text       # start the mirrored window stream
> ade --socket apple snapshot --text         # capture screen + elements
> ade --socket apple select --x 120 --y 420 --text   # tap → chat context
> ade --socket apple tap --x 120 --y 420 --text      # tap as input (needs idb)
> ade --socket apple preview-current --text  # render the selected element's preview
> ade --socket apple shutdown --text
> ```
>
> A `no-context` result from a preview command means ADE has no selected source-backed element yet — `select` one first rather than guessing the screen.

## Troubleshooting

> [accordion] The live view is blank
>
> Verify Simulator.app is running and not minimized. The drawer reports the specific macOS window issue when capture is blocked.

> [accordion] Taps or text don't work, but the view does
>
> Install `idb` and `idb_companion` — they back direct input and accessibility inspection. Without them you still get the mirrored live view.

> [accordion] A launch is blocked by another owner
>
> Run `ade --socket apple shutdown --force --text`, or use the drawer's takeover action.

> [card] [Browser](https://ade-app.dev/docs/tools/browser.md)
>
> The same inspect-and-hand-off flow, for web pages.

> [card] [Agent chat](https://ade-app.dev/docs/chat/overview.md)
>
> Act on the element you tapped, in context.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.