feat(android): investigate custom snapshot helper for stale UIAutomator hierarchies

[thymikee]

Problem

Android snapshots currently rely on stock adb shell/exec-out uiautomator dump. This can return stale or incomplete hierarchies, especially after navigation, during transitions, or when apps have looping animations / continuously changing accessibility events.

We already have daemon-side freshness recovery for recent Android navigation, but that only mitigates obvious stale trees after actions. It cannot fully control Android UIAutomator's internal idle waiting or accessibility cache behavior.

Background

Related Android/UIAutomator behavior:

• UiAutomation.waitForIdle(...) waits for the accessibility event stream to become idle before proceeding.
• Stock uiautomator dump has historically waited for idle before reading getRootInActiveWindow().
• AndroidX UiAutomator exposes Configurator.setWaitForIdleTimeout(...) for controlling idle waits.
• AndroidX/Appium have both had to deal with stale accessibility caches; Appium exposes settings such as waitForIdleTimeout and a mobile: resetAccessibilityCache escape hatch.

Proposal

Investigate replacing or augmenting stock uiautomator dump with a small Android helper APK/instrumentation runner that can provide a fresher best-effort hierarchy.

Minimal first version:

• Build a small Android-side helper using AndroidX UiAutomator or equivalent APIs.
• Configure idle behavior with a small/zero idle timeout instead of relying on stock uiautomator dump defaults.
• Dump the active hierarchy in an XML shape compatible with the existing parser, if practical.
• Add host-side routing so snapshotAndroid tries the helper first and falls back to stock uiautomator dump.
• Include bounded timeouts, diagnostics, and clear fallback reasons.

Potential follow-up:

• Add explicit accessibility cache reset/toggle behavior if the helper still observes stale trees.
• Add helper version/install management.
• Consider richer JSON output later if XML compatibility becomes limiting.

Acceptance Criteria

• Android snapshot capture can bypass stock uiautomator dump for helper-capable devices.
• The helper path supports configurable/bounded idle waiting.
• Failure falls back to existing stock dump behavior without breaking current workflows.
• Diagnostics identify which backend was used and why fallback occurred.
• Unit tests cover host-side routing, timeout, and fallback behavior.
• Emulator smoke/integration coverage is added if CI/device availability allows it.

Notes

This is expected to be a medium-to-large feature, not a small patch. A minimal shippable helper is likely several focused files plus tests; a robust implementation may also require packaging, install/version management, and docs updates.