docs: clarify Android snapshot helper idle waits

Author: thymikee

android-snapshot-helper/README.md

@@ -43,6 +43,9 @@ The `-t` install flag is required because the helper is a test-only instrumentat
 Devices or providers that block test-package installs must allow this package before helper capture
 can run.
 
+`waitForIdleTimeoutMs` defaults to `500`, which is a maximum wait, not a fixed sleep. Direct helper
+invocations can pass `0` when immediate capture during ongoing animation is preferred.
+
 ## Output Contract
 
 The APK emits instrumentation status records using

android-snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java

@@ -30,8 +30,8 @@ public final class SnapshotInstrumentation extends Instrumentation {
   private static final String OUTPUT_FORMAT = "uiautomator-xml";
   private static final String HELPER_API_VERSION = "1";
   private static final int CHUNK_SIZE = 2 * 1024;
-  // Match the host defaults: long enough to avoid mid-transition RN snapshots, but still bounded
-  // below the stock uiautomator idle wait so busy apps do not stall every capture.
+  // Match the host default: bounded wait for microinteraction reliability without the stock
+  // uiautomator idle tax. Direct callers can pass 0 when immediate capture is preferred.
   private static final long DEFAULT_WAIT_FOR_IDLE_TIMEOUT_MS = 500;
   private static final long DEFAULT_WAIT_FOR_IDLE_QUIET_MS = 100;
   private static final long DEFAULT_TIMEOUT_MS = 8_000;

src/platforms/android/snapshot-helper-types.ts

@@ -18,6 +18,8 @@ export const ANDROID_SNAPSHOT_HELPER_RUNNER =
   'com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation';
 export const ANDROID_SNAPSHOT_HELPER_PROTOCOL = 'android-snapshot-helper-v1';
 export const ANDROID_SNAPSHOT_HELPER_OUTPUT_FORMAT = 'uiautomator-xml';
+// Keep common snapshots biased toward post-microinteraction reliability. The
+// value is a max wait; callers that need immediate capture can explicitly pass 0.
 export const ANDROID_SNAPSHOT_HELPER_WAIT_FOR_IDLE_TIMEOUT_MS = 500;
 export const ANDROID_SNAPSHOT_HELPER_WAIT_FOR_IDLE_QUIET_MS = 100;
 export const ANDROID_SNAPSHOT_HELPER_COMMAND_OVERHEAD_MS = 5_000;