@percy/core 1.32.0-beta.0 → 1.32.0-beta.1

package/dist/percy.js

@@ -20,6 +20,7 @@ import { gatherSnapshots, createSnapshotsQueue, validateSnapshotOptions } from '
 import { discoverSnapshotResources, createDiscoveryQueue, RESOURCE_CACHE_KEY, CACHE_STATS_KEY, DISK_SPILL_KEY } from './discovery.js';
 import Monitoring from '@percy/monitoring';
 import { WaitForJob } from './wait-for-job.js';
+import { closeGrpcClientCache } from './maestro-hierarchy.js';
 const MAX_SUGGESTION_CALLS = 10;
 
 // If no activity is done for 5 mins, we will stop monitoring
@@ -121,6 +122,16 @@ export class Percy {
     this.monitoringCheckLastExecutedAt = null;
     this.sdkInfoDisplayed = false;
 
+    // Per-Percy gRPC client cache for the Android view-hierarchy resolver
+    // (D9 in 2026-05-07-002 plan). Owns transport state — channels hold open
+    // sockets, must be closed in stop(). Module-scoped state would leak
+    // between concurrent Percy instances and cause cross-instance shutdown
+    // races. The drift envelope (maestroHierarchyDrift in maestro-hierarchy.js)
+    // stays module-scoped because drift is observability state — surfaced
+    // process-wide on /percy/healthcheck. Two scopes, two reasons.
+    this.grpcClientCache = new Map();
+    this.grpcClientCache.shutdownInProgress = false;
+
     // Domain validation state for auto domain allow-listing
     this.domainValidation = {
       autoConfiguredHosts: new Set(),
@@ -429,6 +440,13 @@ export class Percy {
       await _classPrivateFieldGet(_discovery, this).end();
       await _classPrivateFieldGet(_snapshots, this).end();
 
+      // Close gRPC channels for the Android view-hierarchy resolver. Set the
+      // shutdown flag first so any in-flight runAndroidGrpcDump() that hits
+      // CANCELLED returns {kind:'unavailable', reason:'shutdown'} instead of
+      // triggering the fallback chain on a tearing-down process (R-7).
+      this.grpcClientCache.shutdownInProgress = true;
+      closeGrpcClientCache(this.grpcClientCache);
+
       // mark instance as stopped
       this.readyState = 3;
     } catch (err) {

package/dist/proto/README.md

@@ -0,0 +1,47 @@
+# Vendored protobuf — `maestro_android.proto`
+
+Direct copy of the protobuf schema served by `dev.mobile.maestro` on Android
+devices, used by `@percy/core`'s element-region resolver to call
+`maestro_android.MaestroDriver/viewHierarchy` directly over gRPC instead of
+spawning the full `maestro` CLI (~9s JVM cold start per call → <100ms direct
+gRPC call).
+
+## Source
+
+- **Upstream file:** `maestro-proto/src/main/proto/maestro_android.proto`
+- **Upstream repo:** [`mobile-dev-inc/Maestro`](https://github.com/mobile-dev-inc/Maestro)
+- **Commit SHA at copy time:** `bc8bde1b5cb7f2d4076047c0a9db094ece47512f` (2025-05-26)
+- **Closest CLI release:** `cli-2.5.1`
+- **Copy date:** 2026-04-29
+
+## What we use
+
+Only `MaestroDriver/viewHierarchy(ViewHierarchyRequest) returns (ViewHierarchyResponse)`
+and the `string hierarchy = 1` field on the response. The rest of the proto
+is included unchanged so future updates can be a clean upstream re-copy
+without surgical edits.
+
+## Drift policy
+
+- The proto **must** be re-vendored from upstream whenever the Maestro CLI
+  version deployed on BrowserStack hosts is bumped past the version recorded
+  above. PRs that update this file must paste the upstream SHA and CLI tag.
+- The runtime parser (`@grpc/proto-loader`) silently drops unknown fields.
+  If `viewHierarchy`'s response field is renumbered, retyped, or replaced,
+  decode errors surface as `dump-error (grpc-decode)` and a
+  `maestroHierarchyDrift` flag appears on the `/percy/healthcheck` response.
+  See `docs/solutions/integration-issues/percy-labels-cli-schema-rejection-2026-04-23.md`
+  for context on why we monitor schema drift loudly.
+
+## How to refresh
+
+```sh
+curl -fsSL "https://raw.githubusercontent.com/mobile-dev-inc/Maestro/main/maestro-proto/src/main/proto/maestro_android.proto" \
+  -o packages/core/src/proto/maestro_android.proto
+# Update the SHA + CLI tag above; PR must show the diff and the new pin.
+```
+
+The file is loaded at module init via `@grpc/proto-loader`'s `loadSync` from
+`packages/core/src/maestro-hierarchy.js`. Babel CLI's `copyFiles: true`
+(scripts/build.js:26) preserves the relative layout so it lands at
+`dist/proto/maestro_android.proto` after `yarn build`.

package/dist/proto/maestro_android.proto

@@ -0,0 +1,116 @@
+syntax = "proto3";
+
+package maestro_android;
+
+service MaestroDriver {
+
+  rpc deviceInfo(DeviceInfoRequest) returns (DeviceInfo) {}
+
+  rpc viewHierarchy(ViewHierarchyRequest) returns (ViewHierarchyResponse) {}
+
+  rpc screenshot(ScreenshotRequest) returns (ScreenshotResponse) {}
+
+  rpc tap(TapRequest) returns (TapResponse) {}
+
+  rpc inputText(InputTextRequest) returns (InputTextResponse) {}
+
+  rpc eraseAllText(EraseAllTextRequest) returns (EraseAllTextResponse) {}
+
+  rpc setLocation(SetLocationRequest) returns (SetLocationResponse) {}
+
+  rpc isWindowUpdating(CheckWindowUpdatingRequest) returns (CheckWindowUpdatingResponse) {}
+
+  rpc launchApp(LaunchAppRequest) returns (LaunchAppResponse) {}
+
+  rpc addMedia(stream AddMediaRequest) returns (AddMediaResponse) {}
+
+  rpc enableMockLocationProviders(EmptyRequest) returns (EmptyResponse) {}
+
+  rpc disableLocationUpdates(EmptyRequest) returns (EmptyResponse) {}
+}
+
+message EmptyRequest {}
+message EmptyResponse {}
+
+message LaunchAppRequest {
+
+  string packageName = 1;
+  repeated ArgumentValue arguments = 2;
+}
+
+message ArgumentValue {
+  string key = 1;
+  string value = 2;
+  string type = 3;
+}
+
+message LaunchAppResponse {}
+
+// Device info
+message DeviceInfoRequest {}
+
+message DeviceInfo {
+  uint32 widthPixels = 1;
+  uint32 heightPixels = 2;
+}
+
+message ScreenshotRequest {}
+
+message ScreenshotResponse {
+  bytes bytes = 1;
+}
+
+// View hierarchy
+message ViewHierarchyRequest {}
+
+message ViewHierarchyResponse {
+  string hierarchy = 1;
+}
+
+// Interactions
+
+message TapRequest {
+  uint32 x = 1;
+  uint32 y = 2;
+}
+
+message TapResponse {}
+
+message InputTextRequest {
+  string text = 1;
+}
+message InputTextResponse {}
+
+
+message EraseAllTextRequest {
+    uint32 charactersToErase = 1;
+}
+
+message EraseAllTextResponse {}
+
+message SetLocationRequest {
+    double latitude = 1;
+    double longitude = 2;
+}
+
+message SetLocationResponse {}
+
+message CheckWindowUpdatingRequest {
+  string appId = 1;
+}
+
+message CheckWindowUpdatingResponse {
+  bool isWindowUpdating = 1;
+}
+
+message AddMediaRequest {
+  Payload payload = 1;
+  string media_name = 2;
+  string media_ext = 3;
+}
+
+message AddMediaResponse { }
+
+message Payload {
+  bytes data = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.32.0-beta.0",
+  "version": "1.32.0-beta.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,16 +44,20 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.32.0-beta.0",
-    "@percy/config": "1.32.0-beta.0",
-    "@percy/dom": "1.32.0-beta.0",
-    "@percy/logger": "1.32.0-beta.0",
-    "@percy/monitoring": "1.32.0-beta.0",
-    "@percy/webdriver-utils": "1.32.0-beta.0",
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.8.0",
+    "@percy/client": "1.32.0-beta.1",
+    "@percy/config": "1.32.0-beta.1",
+    "@percy/dom": "1.32.0-beta.1",
+    "@percy/logger": "1.32.0-beta.1",
+    "@percy/monitoring": "1.32.0-beta.1",
+    "@percy/webdriver-utils": "1.32.0-beta.1",
+    "busboy": "^1.6.0",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
     "fast-glob": "^3.2.11",
+    "fast-xml-parser": "^4.4.1",
     "micromatch": "^4.0.8",
     "mime-types": "^2.1.34",
     "pako": "^2.1.0",
@@ -63,7 +67,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.32.0-beta.0"
+    "@percy/cli-doctor": "1.32.0-beta.1"
   },
-  "gitHead": "36c0d4a8f23b5e3ab6bdf5db5e181c1febd4b767"
+  "gitHead": "899783cc84e5fd1b68c701c251cd8cabcbe35fd1"
 }