@expo/serve-sim 0.1.35-canary.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   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.

package/README.md

@@ -0,0 +1,279 @@
+# serve-sim
+
+The `npx serve` of Apple Simulators. 
+
+Host your simulator for use with Agent tools like Codex, Cursor, or Claude Desktop — locally, over your LAN, or host on a remote mac and tunnel anywhere. 
+
+```sh
+npx @expo/serve-sim
+# → Preview at http://localhost:3200
+```
+
+https://github.com/user-attachments/assets/fbf890f4-c8c7-4684-82be-d677b8a188f8
+
+`serve-sim` captures the simulator's IOSurface through an in-process Swift addon, exposes it over HTTP or WebRTC, and serves a React preview UI with simulator input. It works with any booted iOS Simulator — no Xcode plugin and no instrumentation in your app.
+
+## Features 
+
+- Up to 60 FPS over HTTP, or low-latency 30 FPS over WebRTC.
+- Swipe from the bottom to go home.
+- gestures like pinch to zoom by holding the option key.
+- Simulator logs are forwarded to the browser for browser-use MCP tools to read from.
+- Recent simulator actions are available in the browser tools panel and `serve-sim event-log`.
+- Drag and drop videos and images to add them to the simulator device. 
+- Keyboard commands and hot keys are forwarded to the simulator, including CMD+SHIFT+H to go home.
+- Apple Watch, iPad, and iOS support.
+
+## Why?
+
+Hosted simulators can be hard to test, `serve-sim` enables you to test the hosted infra locally first for faster iteration. When you're ready to host a simulator remotely, simply tunnel the served URL and users can interact with the simulator as if it were running locally on their device.
+
+I develop the Expo framework, but this tool is completely agnostic to React Native and can be used for any iOS interaction you need.
+
+## Install
+
+Requires an Apple silicon (`arm64`) Mac with Xcode command line tools (`xcrun simctl`) and a [maintained Node.js LTS release](https://nodejs.org/en/about/previous-releases) (currently Node 20+). Older or end-of-life Node versions are not supported. `bun` is **not** required to run the CLI. Camera injection uses a host-side helper built for macOS 14+.
+
+The bundled native addon, simulator tools, and host helpers are arm64-only.
+
+## CLI
+
+```
+serve-sim [device...]                 Start preview server (default: localhost:3200)
+serve-sim --no-preview [device...]    Stream in foreground without a preview server
+serve-sim gesture '<json>' [-d udid]  Send a touch gesture
+serve-sim button [name] [-d udid]     Send a button press (default: home)
+serve-sim type <text> [-d udid]       Type text via the simulator keyboard
+                                      (US keyboard only; also --stdin / --file <path>)
+serve-sim rotate <orientation> [-d udid]
+                                      portrait | portrait_upside_down |
+                                      landscape_left | landscape_right
+serve-sim ca-debug <option> <on|off> [-d udid]
+                                      Toggle a CoreAnimation debug flag
+                                      (blended|copies|misaligned|offscreen|slow-animations)
+serve-sim memory-warning [-d udid]    Simulate a memory warning
+serve-sim event-log [-d udid]         Show recent simulator events
+
+serve-sim camera <bundle-id> [-d udid] [source-options]
+                                      Inject a synthetic camera feed and (re)launch the app
+serve-sim camera switch <placeholder|webcam|file> [arg] [-d udid]
+                                      Hot-swap the running helper's source (no relaunch)
+serve-sim camera mirror <auto|on|off> [-d udid]
+                                      Hot-swap preview-layer mirror mode
+serve-sim camera status [-d udid]     Print helper state as JSON ({alive, source, ...})
+serve-sim camera --list-webcams       List host camera devices
+serve-sim camera --stop-webcam [-d udid]
+                                      Stop the camera helper for a device
+
+Options:
+  -p, --port <port>   Starting port (preview default: 3200; helper default: 3100)
+      --detach        Spawn server and exit (daemon mode)
+  -q, --quiet         JSON-only output
+      --no-preview    Skip the web UI; stream in foreground only
+      --codec <codec> HTTP stream codec: 'auto', 'h264', or 'mjpeg'
+      --transport <http|webrtc>
+                      Stream transport (default: http)
+      --webrtc-codec <vp8|vp9|h264>
+                      WebRTC video codec (default: h264)
+      --stun-url <url[,url...]>
+                      STUN URL(s) for WebRTC ICE
+      --turn-url <url[,url...]>
+                      TURN URL(s) for WebRTC ICE
+      --turn-username <username>
+                      TURN username
+      --turn-credential <credential>
+                      TURN credential
+      --list [device] List running streams
+      --kill [device] Kill running stream(s)
+
+Camera options (used with `serve-sim camera <bundle-id>`):
+  -f, --file <path>          Image or video file (kind auto-detected from
+                             extension/magic bytes; videos loop at native FPS)
+      --webcam [name]        Live host webcam (defaults to the built-in
+                             front camera when [name] is omitted)
+      --mirror [on|off|auto] Override preview-layer mirroring (default: auto =
+                             front mirrored, back not). Data-output buffers
+                             are never auto-mirrored, matching AVF defaults.
+      --no-mirror            Shortcut for --mirror off
+      --build                Rebuild the dylib + helper from source
+```
+
+WebRTC uses HTTP for SDP signaling and RTP for video. Simulator input and screen
+metadata continue over the existing helper WebSocket. ICE prefers a direct UDP
+path when one is reachable, even if the page was loaded through a tunnel URL;
+TURN is used as a fallback when direct/STUN candidates fail.
+Multiple WebRTC viewers can use the same simulator simultaneously. They share
+one SimulatorKit capture source, while each viewer has an independent peer
+connection, encoder, congestion controller, and helper WebSocket. HTTP streams
+continue to support multiple viewers as well.
+
+See [WebRTC architecture](docs/webrtc-architecture.md) for the current design,
+control-channel decision, known constraints, and planned direction.
+
+### Examples
+
+```sh
+serve-sim                              # auto-detect booted sim, open preview
+serve-sim "iPhone 16 Pro"              # target a specific device
+serve-sim --detach                     # start a background helper, return JSON
+serve-sim --list                       # show running streams
+serve-sim --kill                       # stop all helpers
+
+# Type text into the focused field
+serve-sim type "Hello, world!"
+echo "from stdin" | serve-sim type --stdin
+serve-sim type --file ./snippet.txt
+
+# Camera injection
+serve-sim camera com.acme.MyApp                            # animated placeholder
+serve-sim camera com.acme.MyApp --webcam                   # default webcam
+serve-sim camera com.acme.MyApp --webcam "MacBook Pro Camera"
+serve-sim camera com.acme.MyApp --file ~/Pictures/face.png # static image
+serve-sim camera com.acme.MyApp --file ~/Movies/loop.mp4   # looping video
+
+# Hot-swap source on a running helper (no app relaunch)
+serve-sim camera switch placeholder
+serve-sim camera switch webcam
+serve-sim camera switch ~/Movies/loop.mp4                  # auto-detects file kind
+
+# Other helpers
+serve-sim camera mirror on
+serve-sim camera status                                    # JSON: alive, source, mirror
+serve-sim camera --list-webcams
+serve-sim camera --stop-webcam
+```
+
+Multiple booted simulators are supported by passing several device names. With no device argument, serve-sim selects an existing stream, a booted simulator, or a default simulator to boot.
+
+### Camera
+
+`serve-sim camera <bundle-id>` replaces the simulator's camera feed for a single app. A small host-side helper writes BGRA frames into a POSIX shared-memory region; an injected dylib (`DYLD_INSERT_LIBRARIES`) swizzles AVFoundation inside the simulator process so the app reads from that region instead of the simulator's stub camera.
+
+The helper is one-per-device and outlives any single app launch, so multiple apps on the same simulator can share the feed — just run `serve-sim camera <other-bundle-id>` again to relaunch the next app with the dylib attached. Source changes (`camera switch`) and mirror changes (`camera mirror`) flow through the helper's control socket and don't relaunch the app.
+
+Sources:
+
+- **placeholder** — animated programmatic frames (default).
+- **file** — image (PNG/JPEG/HEIC/…) or video (mp4/mov/m4v/webm/…). The CLI sniffs the kind from the extension and falls back to magic bytes for files without an extension.
+- **webcam** — live `AVCaptureDevice` (built-in, Continuity, external).
+
+## Connectors
+
+`serve-sim` can be used with dev servers, browser, and AI editors for more seamless integration.
+
+### Agent Skill
+
+An [Agent Skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) ships in [`skills/serve-sim`](skills/serve-sim) — it teaches AI coding agents (Claude Code, Cursor, Codex CLI, Gemini CLI, and any host implementing the open Agent Skills standard) how to drive a simulator through the CLI: taps, gestures, hardware buttons, rotation, camera injection, and handing the stream off to the host's preview pane.
+
+```sh
+bunx add-skill expo/serve-sim
+```
+
+See [`skills/serve-sim/README.md`](skills/serve-sim/README.md) for the full capability list.
+
+### Claude Code Desktop
+
+Create a `.claude/launch.json` and define a server:
+
+```json
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "Apple",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["serve-sim"],
+      "port": 3200
+    }
+  ]
+}
+```
+
+### Expo
+
+Expo apps don't need to touch `metro.config.js` — the [`expo-device-hub`](https://github.com/expo/expo-device-hub) plugin uses `serve-sim` and sets up the device streaming for you.
+
+```sh
+npx expo install expo-device-hub
+```
+
+Then run `npx expo start` and open the simulator preview at:
+
+```
+http://localhost:8081/_expo/plugins/expo-device-hub
+```
+
+No other configuration needed.
+
+## Embed in your dev server
+
+`@expo/serve-sim/middleware` is a **fetch-style** middleware. `simMiddleware(options)` returns a Web-standard request handler with a `.handleWebSocket` hook, so it mounts in any server that speaks `Request`/`Response` (Bun, Deno, Hono, a Node adapter, …). Run `serve-sim --detach` once to start the streaming helper, then wire the two entry points:
+
+```ts
+import { simMiddleware } from "@expo/serve-sim/middleware";
+
+const middleware = simMiddleware({ basePath: "/.sim" });
+
+// `server` is a stand-in for your runtime (Bun.serve, node:http + ws, Deno, …).
+
+// HTTP — run every request through the middleware. It returns a Response for
+// serve-sim's own routes (preview at /.sim, state at /.sim/api, SSE logs at
+// /.sim/logs), or `undefined` — meaning "not mine", so fall through.
+server.onRequest(async (request) => {
+  return (await middleware(request)) ?? new Response("Not found", { status: 404 });
+});
+
+// WebSocket — the preview client runs execs, simulator settings, and the SSE
+// side-channels over one socket at `<basePath>/exec-ws`, with no HTTP fallback.
+// On upgrade, hand the request + accepted socket to handleWebSocket; it returns
+// true once it owns the socket. `socket` is a `ws`-style WebSocket (Node's `ws`
+// works as-is; other runtimes need a small adapter).
+server.onUpgrade((request, socket) => {
+  if (!middleware.handleWebSocket?.(request, socket)) socket.close();
+});
+```
+
+The middleware reads the helper's state from `$TMPDIR/serve-sim/` and points the browser at the helper's stream, interaction WebSocket, and WebKit DevTools endpoints. By default those URLs target the helper's own port directly (CORS is wide-open on the helper), so a plain `app.use(...)` mount works without touching your server's WebSocket handling.
+
+### Single-port / remote proxying
+
+To expose the preview to remote viewers behind a single port (the way standalone `serve-sim` does), pass `proxyHelpers: true`. The browser then reaches the stream, control socket, and DevTools through same-origin `/.sim/helper/<device>` and `/.sim/devtools` URLs, so the per-device helper port and inspect-webkit bridge can stay local to the host. This routes WebSockets through the middleware, so you must forward your server's `upgrade` events to `handleUpgrade`:
+
+```ts
+const middleware = simMiddleware({ basePath: "/.sim", proxyHelpers: true });
+
+// Route HTTP requests through `middleware(request)` as above, and also forward
+// raw upgrade events for helper and DevTools proxy sockets.
+const server = listen();
+server.on("upgrade", (req, socket, head) => middleware.handleUpgrade(req, socket, head));
+```
+
+If you enable `proxyHelpers` but don't wire `upgrade`, the page still loads video over HTTP but loses simulator input and DevTools (their sockets never reach the proxy). When terminating TLS at a reverse proxy, forward `X-Forwarded-Proto` so the helper URLs use `https`/`wss` and avoid mixed-content blocks.
+
+## How it works
+
+```
+┌──────────────┐   IOSurface   ┌──────────────────────┐  HTTP / WebRTC  ┌─────────┐
+│ iOS Simulator│ ────────────► │ serve-sim process    │ ──────────────► │ Browser │
+└──────────────┘               │ Swift N-API capture  │                 └─────────┘
+                               │ + Node middleware    │
+                               └──────────────────────┘
+                                          ▲
+                                     state files in
+                                   $TMPDIR/serve-sim/
+```
+
+The npm package ships the native capture addon and LiveKit WebRTC framework alongside the Node CLI. `bun` is needed to build the package, but not to run the published CLI.
+
+## Development
+
+```sh
+bun install
+bun run packages/serve-sim/build.ts                    # full production build
+packages/serve-sim/Sources/SimNative/build.sh           # native addon only
+bun run --filter serve-sim dev                          # watch mode
+```
+
+## License
+
+Apache-2.0

package/Sources/SimAXSettings/build.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+OUT_DIR="${1:-$HERE/../../dist/simax}"
+mkdir -p "$OUT_DIR"
+
+SDK="$(xcrun --sdk iphonesimulator --show-sdk-path)"
+BIN="$OUT_DIR/serve-sim-ax-settings"
+
+# Build an arm64 simulator executable; it runs inside the sim via `simctl spawn`.
+xcrun --sdk iphonesimulator clang \
+    -arch arm64 \
+    -mios-simulator-version-min=15.0 \
+    -isysroot "$SDK" \
+    -framework CoreFoundation \
+    -o "$BIN" \
+    "$HERE/sim-ax-settings.m"
+
+echo "Built: $BIN"
+file "$BIN"