feat: add macOS desktop snapshot surfaces

.github/workflows/macos.yml

@@ -0,0 +1,55 @@
+name: macOS
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  integration-macos:
+    name: Integration Tests
+    runs-on: macos-26
+    timeout-minutes: 80
+    continue-on-error: true
+    env:
+      AGENT_DEVICE_DAEMON_TIMEOUT_MS: '300000'
+      AGENT_DEVICE_IOS_APP_LAUNCH_TIMEOUT_MS: '60000'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup toolchain
+        uses: ./.github/actions/setup-node-pnpm
+
+      - name: Resolve agent-device home
+        id: macos-agent-home
+        run: echo "dir=$HOME/.agent-device" >> "$GITHUB_OUTPUT"
+
+      - name: Build macOS XCTest runner
+        run: pnpm build:xcuitest:macos
+
+      - name: Build macOS helper
+        run: pnpm build:macos-helper
+
+      - name: Run macOS integration test
+        run: node --test test/integration/macos.test.ts
+
+      - name: Upload macOS artifacts
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: macos-artifacts
+          if-no-files-found: ignore
+          path: |
+            ${{ steps.macos-agent-home.outputs.dir }}/daemon.log
+            ${{ steps.macos-agent-home.outputs.dir }}/sessions/**
+            test/artifacts/**
+            test/screenshots/**

README.md

@@ -68,7 +68,7 @@ For agents:
 npm install -g agent-device
 ```
 
-On macOS, `agent-device` now includes a local `agent-device-macos-helper` source package that is built on demand for desktop permission checks, alert handling, and other host-Mac support paths. Release distribution should use a signed/notarized helper build; source checkouts fall back to a local Swift build.
+On macOS, `agent-device` includes a local `agent-device-macos-helper` source package that is built on demand for desktop permission checks, alert handling, and helper-backed desktop snapshot surfaces. Release distribution should use a signed/notarized helper build; source checkouts fall back to a local Swift build.
 
 ## Contributing