test(example): agent-device visual regression PoC for Surface

example/package.json

@@ -8,7 +8,9 @@
     "eas-build-pre-install": "cd .. && yarn",
     "start": "EXPO_NO_TYPESCRIPT_SETUP=1 expo start --dev-client",
     "android": "EXPO_NO_TYPESCRIPT_SETUP=1 expo run:android",
-    "ios": "EXPO_NO_TYPESCRIPT_SETUP=1 expo run:ios"
+    "ios": "EXPO_NO_TYPESCRIPT_SETUP=1 expo run:ios",
+    "visual": "node visual/run.mjs",
+    "test:visual": "node --test visual/run.test.mjs"
   },
   "dependencies": {
     "@expo/metro-config": "~56.0.0",

example/src/Examples/SurfaceExample.tsx

@@ -53,7 +53,7 @@ const SurfaceExample = () => {
 
   return (
     <ScreenWrapper>
-      <List.Section title="Elevated surface">
+      <List.Section title="Elevated surface" testID="surface-example-elevated">
         <ScrollView
           horizontal
           showsHorizontalScrollIndicator={false}
@@ -65,7 +65,7 @@ const SurfaceExample = () => {
         </ScrollView>
       </List.Section>
 
-      <List.Section title="Flat surface">
+      <List.Section title="Flat surface" testID="surface-example-flat">
         <ScrollView
           horizontal
           showsHorizontalScrollIndicator={false}

example/visual/.gitignore

@@ -0,0 +1 @@
+artifacts/

example/visual/env.json

@@ -0,0 +1,34 @@
+{
+  "platform": "ios",
+  "device": "iPhone 17 Pro",
+  "iosVersion": "26.5",
+  "runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
+  "scale": 3,
+  "pixelDensity": 3,
+  "agentDeviceVersion": "0.21.0",
+  "reactNativeVersion": "0.85.3",
+  "branch": "poc/agent-device-visual",
+  "date": "2026-09-10T09:30:58Z",
+  "baselines": {
+    "surface-example-elevated": "__baselines__/ios/surface-example-elevated.png",
+    "surface-example-flat": "__baselines__/ios/surface-example-flat.png"
+  },
+  "android": {
+    "avd": "Pixel_10_Pro",
+    "device": "Pixel 10 Pro",
+    "apiLevel": 37,
+    "androidRelease": "17",
+    "systemImage": "system-images/android-37.0/google_apis_playstore_ps16k/arm64-v8a/",
+    "density": 480,
+    "screenPx": "1280x2856",
+    "emulatorVersion": "36.6.11.0 (build_id 15507667)",
+    "gpuMode": "auto (hw.gpu.enabled=yes, hw.gpu.mode=auto; swiftshader NOT measured)",
+    "agentDeviceVersion": "0.21.0",
+    "reactNativeVersion": "0.85.3",
+    "date": "2026-09-10T09:45:00Z",
+    "baselines": {
+      "surface-example-elevated": "__baselines__/android/surface-example-elevated.png",
+      "surface-example-flat": "__baselines__/android/surface-example-flat.png"
+    }
+  }
+}

example/visual/evidence/a11y-excerpt.json

@@ -0,0 +1,74 @@
+{
+  "about": "Excerpts from the XCUITest / UiAutomator trees captured 2026-09-10 with `npx agent-device@0.21.0 snapshot --raw --force-full --json`. The full trees (13,500 lines) are on branch poc/agent-device-visual-runner under example/visual/evidence/a11y/. Test id at the time: surface-elevated (renamed surface-example-elevated later; the rename changes no pixel).",
+  "ios": {
+    "with_accessible": {
+      "total_nodes": 115,
+      "elevation_labelled_nodes": 2,
+      "surface_section_node": [
+        {
+          "type": "Other",
+          "role": "RCTViewComponentView",
+          "identifier": "surface-elevated",
+          "label": "Elevated surface, Elevation 0, Elevation 1, Elevation 2, Elevation 3, Elevation 4, Elevation 5, Vertical scroll bar, 3 pages",
+          "rect": {
+            "x": 0,
+            "y": 134,
+            "width": 402,
+            "height": 214
+          }
+        }
+      ]
+    },
+    "testID_only": {
+      "total_nodes": 177,
+      "elevation_labelled_nodes": 26,
+      "surface_section_node": [
+        {
+          "type": "Other",
+          "role": "RCTViewComponentView",
+          "identifier": "surface-elevated",
+          "rect": {
+            "x": 0,
+            "y": 134,
+            "width": 402,
+            "height": 214
+          }
+        }
+      ]
+    }
+  },
+  "android": {
+    "with_accessible": {
+      "total_nodes": 217,
+      "elevation_labelled_nodes": 13,
+      "surface_section_node": [
+        {
+          "type": "android.view.ViewGroup",
+          "identifier": "surface-elevated",
+          "rect": {
+            "x": 0,
+            "y": 372,
+            "width": 1280,
+            "height": 642
+          }
+        }
+      ]
+    },
+    "testID_only": {
+      "total_nodes": 217,
+      "elevation_labelled_nodes": 13,
+      "surface_section_node": [
+        {
+          "type": "android.view.ViewGroup",
+          "identifier": "surface-elevated",
+          "rect": {
+            "x": 0,
+            "y": 372,
+            "width": 1280,
+            "height": 642
+          }
+        }
+      ]
+    }
+  }
+}

example/visual/evidence/devclient-excerpt.json

@@ -0,0 +1,38 @@
+{
+  "about": "Excerpts captured 2026-09-11 with `snapshot --force-full --json`; full files on branch poc/agent-device-visual-runner under example/visual/evidence/runner/.",
+  "ios_after_open_relaunch": {
+    "immediately": {
+      "total_nodes": 3,
+      "labels": ["React Native Paper Example", null, "Downloading 100%\u2026"]
+    },
+    "six_seconds_later": {
+      "total_nodes": 77,
+      "dev_menu_close_node": [
+        {
+          "type": "Button",
+          "role": "SwiftUI.AccessibilityNode",
+          "identifier": "xmark",
+          "label": "Close",
+          "rect": {
+            "x": 344.06965174129357,
+            "y": 401.5837479270315,
+            "width": 34.56716417910445,
+            "height": 34.56716417910445
+          }
+        }
+      ]
+    }
+  },
+  "android_devclient_floating_tools_button": [
+    {
+      "type": "android.widget.ImageView",
+      "label": "Tools",
+      "rect": {
+        "x": 1115,
+        "y": 243,
+        "width": 78,
+        "height": 78
+      }
+    }
+  ]
+}

example/visual/evidence/results.csv

@@ -0,0 +1,75 @@
+platform,group,capture,threshold,totalPixels,differentPixels,mismatchPercent,regions,match,sourceOnRunnerBranch
+ios,first-run,a-vs-b (density 1),0.1,86028,0,0,0,True,evidence/ios/26-diff.json
+ios,first-run,flat a-vs-b (density 1),0.1,86028,0,0,0,True,evidence/ios/30-diff.json
+ios,first-run,warm-1,0.1,774252,0,0,0,True,evidence/ios/37-diff.json
+ios,first-run,warm-2,0.1,774252,0,0,0,True,evidence/ios/40-diff.json
+ios,first-run,warm-3,0.1,774252,0,0,0,True,evidence/ios/43-diff.json
+ios,first-run,relaunch-1,0.1,774252,0,0,0,True,evidence/ios/53-diff.json
+ios,first-run,gross,0.1,774252,4277,0.55,1,False,evidence/ios/59-diff.json
+ios,first-run,gross,0.02,774252,116292,15.02,3,False,evidence/ios/60-diff.json
+ios,first-run,revert-1,0.1,774252,0,0,0,True,evidence/ios/63-diff.json
+ios,first-run,realistic,0.02,774252,10179,1.31,3,False,evidence/ios/66-diff-t0.02.json
+ios,first-run,realistic,0.1,774252,0,0,0,True,evidence/ios/66-diff-t0.1.json
+ios,first-run,revert-2,0.1,774252,0,0,0,True,evidence/ios/69-diff.json
+ios,first-run,relaunch-1,0.02,774252,0,0,0,True,evidence/ios/6x-diff-relaunch-1-t002.json
+ios,first-run,warm-1,0.02,774252,0,0,0,True,evidence/ios/6x-diff-warm-1-t002.json
+ios,first-run,warm-2,0.02,774252,0,0,0,True,evidence/ios/6x-diff-warm-2-t002.json
+ios,first-run,warm-3,0.02,774252,0,0,0,True,evidence/ios/6x-diff-warm-3-t002.json
+android,first-run,relaunch-1,0.01,821760,0,0,0,True,evidence/android/103-diff-relaunch-1-t0.01.json
+android,first-run,relaunch-1,0.02,821760,0,0,0,True,evidence/android/103-diff-relaunch-1-t0.02.json
+android,first-run,relaunch-1,0.05,821760,0,0,0,True,evidence/android/103-diff-relaunch-1-t0.05.json
+android,first-run,relaunch-1,0.1,821760,0,0,0,True,evidence/android/103-diff-relaunch-1-t0.1.json
+android,first-run,gross,0.01,821760,265916,32.36,2,False,evidence/android/108-diff-gross-t0.01.json
+android,first-run,gross,0.02,821760,208505,25.37,4,False,evidence/android/108-diff-gross-t0.02.json
+android,first-run,gross,0.05,821760,118661,14.44,4,False,evidence/android/108-diff-gross-t0.05.json
+android,first-run,gross,0.1,821760,65051,7.92,2,False,evidence/android/108-diff-gross-t0.1.json
+android,first-run,revert1,0.01,821760,0,0,0,True,evidence/android/111-diff-revert1-t0.01.json
+android,first-run,revert1,0.02,821760,0,0,0,True,evidence/android/111-diff-revert1-t0.02.json
+android,first-run,revert1,0.05,821760,0,0,0,True,evidence/android/111-diff-revert1-t0.05.json
+android,first-run,revert1,0.1,821760,0,0,0,True,evidence/android/111-diff-revert1-t0.1.json
+android,first-run,realistic,0.01,821760,14686,1.79,1,False,evidence/android/114-diff-realistic-t0.01.json
+android,first-run,realistic,0.02,821760,9336,1.14,1,False,evidence/android/114-diff-realistic-t0.02.json
+android,first-run,realistic,0.05,821760,1830,0.22,1,False,evidence/android/114-diff-realistic-t0.05.json
+android,first-run,realistic,0.1,821760,0,0,0,True,evidence/android/114-diff-realistic-t0.1.json
+android,first-run,revert2,0.01,821760,0,0,0,True,evidence/android/117-diff-revert2-t0.01.json
+android,first-run,revert2,0.02,821760,0,0,0,True,evidence/android/117-diff-revert2-t0.02.json
+android,first-run,revert2,0.05,821760,0,0,0,True,evidence/android/117-diff-revert2-t0.05.json
+android,first-run,revert2,0.1,821760,0,0,0,True,evidence/android/117-diff-revert2-t0.1.json
+android,first-run,warm-1,0.01,821760,0,0,0,True,evidence/android/94-diff-warm-1-t0.01.json
+android,first-run,warm-1,0.02,821760,0,0,0,True,evidence/android/94-diff-warm-1-t0.02.json
+android,first-run,warm-1,0.05,821760,0,0,0,True,evidence/android/94-diff-warm-1-t0.05.json
+android,first-run,warm-1,0.1,821760,0,0,0,True,evidence/android/94-diff-warm-1-t0.1.json
+android,first-run,warm-2,0.01,821760,0,0,0,True,evidence/android/94-diff-warm-2-t0.01.json
+android,first-run,warm-2,0.02,821760,0,0,0,True,evidence/android/94-diff-warm-2-t0.02.json
+android,first-run,warm-2,0.05,821760,0,0,0,True,evidence/android/94-diff-warm-2-t0.05.json
+android,first-run,warm-2,0.1,821760,0,0,0,True,evidence/android/94-diff-warm-2-t0.1.json
+android,first-run,warm-3,0.01,821760,0,0,0,True,evidence/android/94-diff-warm-3-t0.01.json
+android,first-run,warm-3,0.02,821760,0,0,0,True,evidence/android/94-diff-warm-3-t0.02.json
+android,first-run,warm-3,0.05,821760,0,0,0,True,evidence/android/94-diff-warm-3-t0.05.json
+android,first-run,warm-3,0.1,821760,0,0,0,True,evidence/android/94-diff-warm-3-t0.1.json
+ios,re-measured,gross,0.02,774252,116292,15.02,3,False,evidence/sensitivity/ios/gross-diff-t0.02.json
+ios,re-measured,gross,0.1,774252,4277,0.55,1,False,evidence/sensitivity/ios/gross-diff-t0.1.json
+ios,re-measured,realistic-1,0.02,774252,10179,1.31,3,False,evidence/sensitivity/ios/realistic-1-diff-t0.02.json
+ios,re-measured,realistic-1,0.1,774252,0,0,0,True,evidence/sensitivity/ios/realistic-1-diff-t0.1.json
+ios,re-measured,realistic-2,0.02,774252,10179,1.31,3,False,evidence/sensitivity/ios/realistic-2-diff-t0.02.json
+ios,re-measured,realistic-2,0.1,774252,0,0,0,True,evidence/sensitivity/ios/realistic-2-diff-t0.1.json
+ios,re-measured,realistic-3,0.02,774252,10179,1.31,3,False,evidence/sensitivity/ios/realistic-3-diff-t0.02.json
+ios,re-measured,realistic-3,0.1,774252,0,0,0,True,evidence/sensitivity/ios/realistic-3-diff-t0.1.json
+ios,re-measured,reverted,0.02,774252,0,0,0,True,evidence/sensitivity/ios/reverted-diff-t0.02.json
+ios,re-measured,reverted,0.1,774252,0,0,0,True,evidence/sensitivity/ios/reverted-diff-t0.1.json
+android,re-measured,gross,0.02,821760,208505,25.37,4,False,evidence/sensitivity/android/gross-diff-t0.02.json
+android,re-measured,gross,0.1,821760,65051,7.92,2,False,evidence/sensitivity/android/gross-diff-t0.1.json
+android,re-measured,gross-probe,0.02,821760,0,0,0,True,evidence/sensitivity/android/gross-probe-diff-t0.02.json
+android,re-measured,gross-probe,0.1,821760,0,0,0,True,evidence/sensitivity/android/gross-probe-diff-t0.1.json
+android,re-measured,realistic-1,0.02,821760,9336,1.14,1,False,evidence/sensitivity/android/realistic-1-diff-t0.02.json
+android,re-measured,realistic-1,0.1,821760,0,0,0,True,evidence/sensitivity/android/realistic-1-diff-t0.1.json
+android,re-measured,realistic-2,0.02,821760,9336,1.14,1,False,evidence/sensitivity/android/realistic-2-diff-t0.02.json
+android,re-measured,realistic-2,0.1,821760,0,0,0,True,evidence/sensitivity/android/realistic-2-diff-t0.1.json
+android,re-measured,realistic-3,0.02,821760,9336,1.14,1,False,evidence/sensitivity/android/realistic-3-diff-t0.02.json
+android,re-measured,realistic-3,0.1,821760,0,0,0,True,evidence/sensitivity/android/realistic-3-diff-t0.1.json
+android,re-measured,reverted,0.02,821760,0,0,0,True,evidence/sensitivity/android/reverted-diff-t0.02.json
+android,re-measured,reverted,0.1,821760,0,0,0,True,evidence/sensitivity/android/reverted-diff-t0.1.json
+android,re-measured,sanity-before-break,0.02,821760,0,0,0,True,evidence/sensitivity/android/sanity-before-break-diff-t0.02.json
+android,re-measured,sanity-before-break,0.1,821760,0,0,0,True,evidence/sensitivity/android/sanity-before-break-diff-t0.1.json
+android,dev-client-chrome,tools-button-on,0.02,821760,2822,0.34,1,False,runner-branch:evidence/runs/android/round3-pass/summary.json
+ios,dev-client-chrome,tools-button-on,0.02,774252,3916,0.51,1,False,"verify/ios/a11-diff.json (2026-09-16 re-verification, not committed)"

example/visual/evidence/web-excerpt.json

@@ -0,0 +1,33 @@
+{
+  "about": "agent-device 0.21.0, --platform web (managed agent-browser 0.27.1, Node 24.18), against `expo export --platform web` of the example app served on 127.0.0.1:4322, 2026-09-14.",
+  "open": {
+    "success": true,
+    "device": "Agent Browser Chrome",
+    "startupMs": 1576
+  },
+  "screenshot_crop_on": {
+    "command": "screenshot web-crop.png --crop-on 'id=\"surface-example-elevated\"' --platform web --session web --json",
+    "success": false,
+    "error": {
+      "code": "UNSUPPORTED_OPERATION",
+      "message": "screenshot --crop-on is not accepted on web targets",
+      "hint": "This command is not available for the selected platform/device.",
+      "diagnosticId": "mu0zgqxl-62c0defe",
+      "logPath": "/Users/juliankobrynski/.agent-device/sessions/web/requests/4f9d41985f52c500.ndjson",
+      "diagnosticsRecord": {
+        "session": "web",
+        "requestId": "4f9d41985f52c500"
+      },
+      "details": {
+        "reason": "CROP_TARGET_NOT_ACCEPTED",
+        "rejectionReason": "PENDING_PIXEL_IDENTITY_EVIDENCE"
+      }
+    }
+  },
+  "screenshot_plain": {
+    "command": "screenshot web-full.png --platform web --session web --json",
+    "success": true,
+    "width": 1280,
+    "height": 577
+  }
+}