Add RN inspector and simulator test API

Author: DjDeveloperr

.github/workflows/ci.yml

@@ -42,3 +42,6 @@ jobs:
         run: npm run test:integration:cli
         env:
           SIMDECK_INTEGRATION_VERBOSE: "1"
+
+      - name: JS API simulator integration tests
+        run: npm run test:integration:js-api

.github/workflows/release.yml

@@ -92,6 +92,9 @@ jobs:
             "${ARTIFACTS_DIR}/simdeck-${VERSION}-macos.zip"
 
           npm pack --pack-destination "${ARTIFACTS_DIR}"
+          test -x "${BUNDLE_DIR}/simdeck"
+          test -x "${BUNDLE_DIR}/simdeck-bin"
+          tar -tzf "${ARTIFACTS_DIR}/simdeck-${VERSION}.tgz" | grep -qx "package/build/simdeck-bin"
           (
             cd packages/nativescript-inspector
             npm pack --pack-destination "${ARTIFACTS_DIR}"
@@ -112,7 +115,7 @@ jobs:
             exit 1
           fi
 
-          npm publish
+          npm publish "${RUNNER_TEMP}/release-assets/simdeck-${VERSION}.tgz"
 
       - name: Publish NativeScript inspector to npm
         env:

.gitignore

@@ -8,13 +8,17 @@ client/dist/
 packages/inspector-agent/.build/
 packages/inspector-agent/.swiftpm/
 packages/nativescript-inspector/dist/
+packages/react-native-inspector/dist/
 docs/.vitepress/dist/
 docs/.vitepress/cache/
+.playwright-mcp/
+simdeck-snapshot.md
 
 # Package manager installs and caches
 node_modules/
 client/node_modules/
 packages/nativescript-inspector/node_modules/
+packages/react-native-inspector/node_modules/
 
 # Local editor state
 .vscode/

.prettierignore

@@ -5,7 +5,10 @@ build
 client/dist
 packages/inspector-agent/.build
 packages/nativescript-inspector/dist
+packages/react-native-inspector/dist
 node_modules
 server/target
 docs/.vitepress/dist
 docs/.vitepress/cache
+.playwright-mcp
+simdeck-snapshot.md

AGENTS.md

@@ -44,13 +44,18 @@ The native side should own anything that depends on macOS frameworks, `xcrun sim
   NativeScript in-app inspector runtime that connects to the Rust server over
   WebSocket, publishes NativeScript/UIKit hierarchies, and performs debug UIKit
   property edits from JavaScript.
+- `packages/react-native-inspector/src/index.ts`
+  React Native in-app inspector runtime that connects to the Rust server over
+  WebSocket, publishes React Fiber component hierarchies with Metro source
+  locations, and performs best-effort debug JS/native prop edits.
 
 ## Working Rules
 
 - Keep simulator-native logic in Objective-C under `cli/`.
 - Keep Rust server logic under `server/`.
 - Keep browser-only presentation logic in `client/`.
 - Keep NativeScript app runtime inspection logic in `packages/nativescript-inspector/`.
+- Keep React Native app runtime inspection logic in `packages/react-native-inspector/`.
 - Prefer adding a native API endpoint before adding client-only assumptions.
 - Do not add a Node or Swift dependency to solve work that already fits in Foundation/AppKit.
 - When touching private API usage, keep the adaptation small and explicit and document any simulator/runtime assumptions here.
@@ -82,22 +87,22 @@ Build the native CLI:
 
 This now builds the Rust server in `server/` and copies the resulting binary to `build/simdeck`.
 
-Run the local server:
+Run the local daemon:
 
 ```sh
-./build/simdeck serve --port 4310
+./build/simdeck daemon start --port 4310
 ```
 
 Use software H.264 when macOS screen recording starves the hardware encoder:
 
 ```sh
-./build/simdeck serve --port 4310 --video-codec h264-software
+./build/simdeck daemon start --port 4310 --video-codec h264-software
 ```
 
 For LAN access:
 
 ```sh
-./build/simdeck serve --port 4310 --bind 0.0.0.0 --advertise-host 192.168.1.50
+./build/simdeck daemon start --port 4310 --bind 0.0.0.0 --advertise-host 192.168.1.50
 ```
 
 Useful direct commands:
@@ -114,7 +119,7 @@ Useful direct commands:
 ./build/simdeck pasteboard set <udid> "hello"
 ./build/simdeck pasteboard get <udid>
 ./build/simdeck screenshot <udid> --output screen.png
-./build/simdeck describe-ui <udid>
+./build/simdeck describe <udid>
 ./build/simdeck tap <udid> 120 240
 ./build/simdeck tap <udid> --label "Continue" --wait-timeout-ms 5000
 ./build/simdeck swipe <udid> 200 700 200 200

README.md

@@ -1,16 +1,21 @@
 # SimDeck
 
-`simdeck` is a local simulator control panel & agent-first CLI for driving the simulator
+SimDeck is a developer tool built for streamlining mobile app development for coding agents.
+Drive iOS Simulator apps from the CLI, browser, and automated tests on macOS.
 
 ```sh
 npm i -g simdeck@latest
 ```
 
-- `simctl`-backed simulator discovery and lifecycle commands
-- private CoreSimulator boot fallback
+## Features
+
+- WebTransport based streaming server in Rust, hardware encoded HVEC/H264 video stream
+- Simulator control & inspection using private accessibility APIs
 - CoreSimulator chrome asset rendering for device bezels
-- NativeScript runtime inspector in `packages/nativescript-inspector/` for JS-driven UIKit querying and property edits
-- WebTransport video delivery over a self-signed local or LAN endpoint
+- NativeScript and React Native runtime inspector plugins, plus a native UIKit inspector framework for other apps
+- Project daemon reuse: normal CLI commands automatically start and reuse one warm native host per project.
+- `simdeck/test` for fast JS/TS app tests that can query accessibility state and drive simulator controls.
+- Agent [`SKILL.md`](./skills/simdeck/SKILL.md) reference
 
 ## Build
 
@@ -19,21 +24,20 @@ npm i -g simdeck@latest
 ./scripts/build-cli.sh
 ```
 
-## Install
-
 Requirements:
 
 - macOS
 - Xcode or Command Line Tools
-- Rust toolchain (`cargo`)
 - Node.js 18+
+- Rust toolchain (`cargo`) when building from source
 
-The npm package builds the native Rust/Objective-C CLI during `postinstall`; it
-is not a prebuilt cross-platform binary.
+The npm package includes the native SimDeck binary and does not compile during
+install. Rust is only required when building from a source checkout.
 
 Install the current local checkout globally from source:
 
 ```sh
+npm run build
 npm install -g .
 ```
 
@@ -46,46 +50,45 @@ Full documentation lives at [djdeveloperr.github.io/SimDeck](https://djdeveloper
 ## Run
 
 ```sh
-simdeck serve --port 4310
+simdeck ui --open
 ```
 
-Then open [http://127.0.0.1:4310](http://127.0.0.1:4310).
-To focus a specific simulator, open
-[http://127.0.0.1:4310?device=UDID](http://127.0.0.1:4310?device=UDID).
+This starts or reuses the project daemon, enables the browser UI, and opens the authenticated local URL.
+To focus a specific simulator, add `?device=UDID` to the opened URL.
 
-The Rust server exposes HTTP on the requested port and WebTransport on `port + 1`.
+The daemon exposes HTTP on the requested port and WebTransport on `port + 1`.
 The browser bootstrap comes from `GET /api/health`, which returns the WebTransport URL template,
 certificate hash, and packet version needed by the client.
-The served browser UI receives the generated API access token automatically; direct HTTP callers can use the startup token with `X-SimDeck-Token` or `Authorization: Bearer`.
+The served browser UI receives the generated API access token automatically.
 
-For fastest agent control, keep `simdeck serve` or `simdeck service on` running and route hot CLI controls through the warm local service:
+CLI commands automatically use the same warm daemon:
 
 ```sh
-export SIMDECK_SERVER_URL=http://127.0.0.1:4310
+simdeck list
 simdeck tap <udid> 0.5 0.5 --normalized
-simdeck describe-ui <udid> --format agent --max-depth 2
+simdeck describe <udid> --format agent --max-depth 2
 ```
 
-You can also pass `--server-url http://127.0.0.1:4310` on individual commands. Supported fast-path controls include launch/open-url, normalized touch/tap/swipe/gesture input, key/key-sequence/key-combo, hardware buttons, dismiss-keyboard, home/app-switcher, rotate, and appearance toggles.
+## Daemon
 
-## Service
-
-Enable the per-user background service with `launchd`:
+Manage the project daemon explicitly when needed:
 
 ```sh
-simdeck service on --port 4310
+simdeck daemon start
+simdeck daemon status
+simdeck daemon stop
 ```
 
-Restart it:
+Use software H.264 when macOS screen recording starves the hardware encoder:
 
 ```sh
-simdeck service restart
+simdeck daemon start --video-codec h264-software
 ```
 
-Disable it:
+For LAN browser access:
 
 ```sh
-simdeck service off
+simdeck ui --bind 0.0.0.0 --advertise-host 192.168.1.50 --open
 ```
 
 Restart the CoreSimulator service layer when `simctl` reports a stale service
@@ -117,9 +120,9 @@ simdeck toggle-appearance <udid>
 simdeck pasteboard set <udid> "hello"
 simdeck pasteboard get <udid>
 simdeck screenshot <udid> --output screen.png
-simdeck describe-ui <udid>
-simdeck describe-ui <udid> --format agent --max-depth 4
-simdeck describe-ui <udid> --point 120,240
+simdeck describe <udid>
+simdeck describe <udid> --format agent --max-depth 4
+simdeck describe <udid> --point 120,240
 simdeck tap <udid> 120 240
 simdeck tap <udid> --label "Continue" --wait-timeout-ms 5000
 simdeck swipe <udid> 200 700 200 200
@@ -144,13 +147,30 @@ simdeck chrome-profile <udid>
 simdeck logs <udid> --seconds 30 --limit 200
 ```
 
-`describe-ui` can use the running local SimDeck service to prefer NativeScript or
+`describe` uses the project daemon to prefer React Native, NativeScript, or
 UIKit in-app inspectors, then falls back to the built-in private CoreSimulator
 accessibility bridge. Use `--format agent` or `--format compact-json` for
 lower-token hierarchy dumps. Coordinate commands accept screen coordinates from
 the accessibility tree by default; pass `--normalized` to send `0.0..1.0`
-coordinates directly. With `--server-url` or `SIMDECK_SERVER_URL`, normalized
-input commands use the warm service path to avoid repeated native setup.
+coordinates directly.
+
+## JS/TS Tests
+
+```ts
+import { connect } from "simdeck/test";
+
+const sim = await connect();
+try {
+  await sim.tap("<udid>", 0.5, 0.5);
+  await sim.waitFor("<udid>", { label: "Continue" });
+  await sim.screenshot("<udid>");
+} finally {
+  sim.close();
+}
+```
+
+`connect()` starts the project daemon when needed, reuses it when it is already
+healthy, and only stops daemons it started itself.
 
 ## NativeScript Inspector
 
@@ -171,6 +191,26 @@ server prefers connected NativeScript inspectors for hierarchy requests and
 falls back to the Swift TCP inspector or the built-in native accessibility
 bridge when no matching app inspector is available.
 
+## React Native Inspector
+
+React Native apps can expose their component tree and Metro dev-mode source
+locations with the React Native inspector package:
+
+```ts
+import { AppRegistry } from "react-native";
+import { startSimDeckReactNativeInspector } from "@simdeck/react-native-inspector";
+import App from "./App";
+
+if (__DEV__) {
+  startSimDeckReactNativeInspector({ port: 4310 });
+}
+
+AppRegistry.registerComponent("Example", () => App);
+```
+
+Call it before `AppRegistry.registerComponent(...)` so the package can capture
+React Fiber commits.
+
 ## VS Code
 
 Package the local VS Code extension from this checkout:

bin/simdeck.mjs

@@ -11,9 +11,14 @@ const packageRoot = path.resolve(
 );
 const binaryPath = path.join(packageRoot, "build", "simdeck-bin");
 
+if (process.platform !== "darwin") {
+  console.error("simdeck only supports macOS.");
+  process.exit(1);
+}
+
 if (!existsSync(binaryPath)) {
   console.error(
-    "simdeck is not built yet. Reinstall or rebuild the package so the native CLI is available.",
+    "simdeck native binary is missing. Reinstall the npm package or run `npm run build:cli` from a source checkout.",
   );
   process.exit(1);
 }