Improve inspector source switching and simulator controls

Author: DjDeveloperr

.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types:
+      - published
+
+jobs:
+  release:
+    runs-on: macos-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: |
+            package-lock.json
+            client/package-lock.json
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Resolve release metadata
+        id: meta
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            TAG_NAME="${{ github.event.release.tag_name }}"
+          else
+            TAG_NAME="${GITHUB_REF_NAME}"
+          fi
+
+          VERSION="${TAG_NAME#v}"
+          PACKAGE_VERSION="$(node -p "require('./package.json').version")"
+
+          if [ "${VERSION}" != "${PACKAGE_VERSION}" ]; then
+            echo "Tag ${TAG_NAME} does not match package version ${PACKAGE_VERSION}" >&2
+            exit 1
+          fi
+
+          echo "tag=${TAG_NAME}" >> "${GITHUB_OUTPUT}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install client dependencies
+        run: npm ci --prefix client
+
+      - name: Lint, build, and test
+        run: npm run ci
+
+      - name: Prepare release assets
+        env:
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          ARTIFACTS_DIR="${RUNNER_TEMP}/release-assets"
+          BUNDLE_DIR="${RUNNER_TEMP}/xcode-canvas-web-${VERSION}-macos"
+
+          rm -rf "${ARTIFACTS_DIR}" "${BUNDLE_DIR}"
+          mkdir -p "${ARTIFACTS_DIR}" "${BUNDLE_DIR}"
+
+          cp build/xcode-canvas-web "${BUNDLE_DIR}/"
+          cp build/xcode-canvas-web-bin "${BUNDLE_DIR}/"
+          cp README.md LICENSE "${BUNDLE_DIR}/"
+
+          tar -czf "${ARTIFACTS_DIR}/xcode-canvas-web-${VERSION}-macos.tar.gz" \
+            -C "${RUNNER_TEMP}" \
+            "xcode-canvas-web-${VERSION}-macos"
+
+          ditto -c -k --keepParent \
+            "${BUNDLE_DIR}" \
+            "${ARTIFACTS_DIR}/xcode-canvas-web-${VERSION}-macos.zip"
+
+          npm pack --pack-destination "${ARTIFACTS_DIR}"
+
+      - name: Publish package to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          if npm view "xcode-canvas-web@${VERSION}" version >/dev/null 2>&1; then
+            echo "xcode-canvas-web@${VERSION} is already published on npm."
+            exit 0
+          fi
+
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "NPM_TOKEN repository secret is required to publish xcode-canvas-web@${VERSION}." >&2
+            exit 1
+          fi
+
+          npm publish
+
+      - name: Upload GitHub release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ steps.meta.outputs.tag }}
+        run: |
+          ARTIFACTS_DIR="${RUNNER_TEMP}/release-assets"
+
+          if gh release view "${TAG_NAME}" >/dev/null 2>&1; then
+            gh release upload "${TAG_NAME}" "${ARTIFACTS_DIR}"/* --clobber
+          else
+            gh release create "${TAG_NAME}" "${ARTIFACTS_DIR}"/* \
+              --generate-notes \
+              --title "${TAG_NAME}"
+          fi

AGENTS.md

@@ -26,7 +26,7 @@ The native side should own anything that depends on macOS frameworks, `xcrun sim
 - `cli/DFPrivateSimulatorDisplayBridge.*`
   Owns headless private display frames plus HID-based touch and keyboard injection.
 - `cli/XCWPrivateSimulatorSession.*`
-  Owns one private display bridge per booted simulator plus hardware H.264 encode.
+  Owns one private display bridge per booted simulator plus selectable HEVC/H.264 encode.
 - `cli/native/XCWNativeBridge.*`
   Narrow C ABI for simulator control, chrome rendering, and native frame callbacks into Rust.
 - `cli/native/XCWNativeSession.*`
@@ -39,12 +39,17 @@ The native side should own anything that depends on macOS frameworks, `xcrun sim
   Renders Apple’s CoreSimulator device-type PDF chrome assets into PNGs for the browser.
 - `client/src/app/App.tsx`
   Browser entrypoint for the React control surface.
+- `nativescript-inspector/src/index.ts`
+  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.
 
 ## 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 `nativescript-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,6 +87,12 @@ Run the local server:
 ./build/xcode-canvas-web serve --port 4310
 ```
 
+Use software H.264 when macOS screen recording starves the hardware encoder:
+
+```sh
+./build/xcode-canvas-web serve --port 4310 --video-codec h264-software
+```
+
 For LAN access:
 
 ```sh

README.md

@@ -8,6 +8,7 @@
 - private CoreSimulator boot fallback
 - vendored private display bridge for continuous frames plus touch and keyboard injection
 - CoreSimulator chrome asset rendering for device bezels
+- NativeScript runtime inspector in `nativescript-inspector/` for JS-driven UIKit querying and property edits
 - local HTTP API plus static client hosting in Rust
 - WebTransport video delivery over a self-signed local or LAN endpoint
 - React client in `client/`
@@ -43,6 +44,12 @@ xcode-canvas-web serve --port 4310
 
 Then open [http://127.0.0.1:4310](http://127.0.0.1:4310).
 
+The default stream encoder is hardware HEVC. If macOS screen recording makes the stream sluggish, run the server with software H.264 so the live stream does not compete with the screen recorder's hardware encoder:
+
+```sh
+xcode-canvas-web serve --port 4310 --video-codec h264-software
+```
+
 The Rust server 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.
@@ -71,6 +78,54 @@ xcode-canvas-web open-url <udid> https://example.com
 xcode-canvas-web launch <udid> com.apple.Preferences
 ```
 
+## NativeScript Inspector
+
+NativeScript apps can connect directly to the running server from JS and expose
+their NativeScript logical hierarchy plus raw UIKit backing views without
+linking the Swift inspector framework:
+
+```ts
+import { startXcodeCanvasInspector } from "@nativescript/xcode-canvas-inspector";
+
+if (__DEV__) {
+  startXcodeCanvasInspector({ port: 4310 });
+}
+```
+
+The runtime connects to `GET /api/inspector/connect` as a WebSocket. The Rust
+server prefers connected NativeScript inspectors for hierarchy requests and
+falls back to the Swift TCP inspector or AXe when no matching app inspector is
+available.
+
+Dynamic UIKit mutation is exposed through
+`POST /api/simulators/:udid/inspector/request` with methods such as
+`View.getProperties` and `View.setProperty`. This endpoint is intentionally a
+debug/tooling API for now; the browser UI can add a focused property editor on
+top of it once the safe editable-property surface settles.
+
+## Releases
+
+Push a `vX.Y.Z` tag, or publish a GitHub release for that tag, to run the release workflow on `macos-latest`.
+The tag has to match `package.json`. The workflow builds the CLI, uploads the macOS archives and npm tarball
+to the GitHub release, and publishes the package to npm when `NPM_TOKEN` is configured in repository secrets.
+
+## VS Code
+
+Package the local VS Code extension:
+
+```sh
+npm run package:vscode-extension
+```
+
+Install it into local VS Code:
+
+```sh
+npm run install:vscode-extension
+```
+
+Then run `Xcode Canvas Web: Open Simulator View` from the Command Palette. The extension will open the simulator
+inside a VS Code panel and auto-start the local server when it is not already reachable.
+
 ## License
 
 Copyright 2026 Dj

bin/xcode-canvas-web.mjs

@@ -59,6 +59,7 @@ NS_SWIFT_NAME(PrivateSimulatorDisplayBridge)
 - (BOOL)pressHomeButton:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(pressHomeButton());
 
 - (BOOL)rotateRight:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(rotateRight());
+- (BOOL)rotateLeft:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(rotateLeft());
 
 - (void)disconnect;
 

cli/DFPrivateSimulatorDisplayBridge.h

@@ -114,7 +114,6 @@
 static const NSUInteger DFKeyboardModifierOption = 1 << 2;
 static const NSUInteger DFKeyboardModifierCommand = 1 << 3;
 static const NSUInteger DFKeyboardModifierCapsLock = 1 << 4;
-static const NSUInteger DFKeyboardModifierFunction = 1 << 5;
 
 typedef struct {
     __unsafe_unretained id unit;
@@ -2657,7 +2656,7 @@ - (BOOL)pressHomeButton:(NSError * _Nullable __autoreleasing *)error {
     return success;
 }
 
-- (BOOL)rotateRight:(NSError * _Nullable __autoreleasing *)error {
+- (BOOL)rotateByDegrees:(double)deltaDegrees error:(NSError * _Nullable __autoreleasing *)error {
     __block BOOL success = NO;
     __block NSError *dispatchError = nil;
 
@@ -2700,7 +2699,7 @@ - (BOOL)rotateRight:(NSError * _Nullable __autoreleasing *)error {
                 }
             }
 
-            measurement.value = DFNormalizedDegrees(measurement.value + 90.0);
+            measurement.value = DFNormalizedDegrees(measurement.value + deltaDegrees);
             self->_deviceRotationDegrees = measurement.value;
 
             if (readFromSimulatorKit) {
@@ -2768,6 +2767,14 @@ - (BOOL)rotateRight:(NSError * _Nullable __autoreleasing *)error {
     return success;
 }
 
+- (BOOL)rotateRight:(NSError * _Nullable __autoreleasing *)error {
+    return [self rotateByDegrees:90.0 error:error];
+}
+
+- (BOOL)rotateLeft:(NSError * _Nullable __autoreleasing *)error {
+    return [self rotateByDegrees:-90.0 error:error];
+}
+
 - (void)disconnect {
     dispatch_block_t work = ^{
         if (self->_screenAdapter != nil && self->_screenAdapterCallbackUUID != nil) {
@@ -2932,12 +2939,13 @@ - (BOOL)sendKeyCode:(uint16_t)keyCode
             NSUInteger mask;
             uint16_t keyCode;
         } modifierMap[] = {
+            // IndigoHIDMessageForKeyboardArbitrary expects USB HID keyboard
+            // usages. These are left-side modifier usages from the Keyboard page.
             { DFKeyboardModifierCapsLock, 57 },
-            { DFKeyboardModifierControl, 59 },
-            { DFKeyboardModifierOption, 58 },
-            { DFKeyboardModifierShift, 56 },
-            { DFKeyboardModifierCommand, 55 },
-            { DFKeyboardModifierFunction, 63 },
+            { DFKeyboardModifierControl, 224 },
+            { DFKeyboardModifierShift, 225 },
+            { DFKeyboardModifierOption, 226 },
+            { DFKeyboardModifierCommand, 227 },
         };
 
         NSMutableArray<NSNumber *> *modifierKeyCodes = [NSMutableArray array];

cli/DFPrivateSimulatorDisplayBridge.m

@@ -19,6 +19,7 @@ typedef void (^XCWH264EncoderOutputHandler)(NSData *sampleData,
 
 - (void)encodePixelBuffer:(CVPixelBufferRef)pixelBuffer;
 - (void)requestKeyFrame;
+- (NSDictionary *)statsRepresentation;
 - (void)invalidate;
 
 @end