fix(android): preserve editable-field metadata in snapshots (#2290)

* fix(android): preserve editable-field observation metadata

* fix(android): carry field facts through the attrs digest and selection offsets past editability

- `get attrs --level digest` kept only the pre-#2288 semantic fields, so
  `editable`/`password`/`hintShowing`/`selectionStart`/`selectionEnd`
  vanished on the token-cheap route. The digest now keeps them, with a
  regression covering explicit false/zero/empty and omission when unavailable.
- The helper emitted selection offsets only inside `isEditable()`, but
  read-only selectable text exposes a selection too. Each nonnegative offset
  is now emitted independently; -1 stays absent. Parser-to-snapshot regression
  for a non-editable selectable node.
- Docs: the field-metadata notes get their own section instead of leading the
  efficiency tips.
- Dropped the test-isolation commit: main already mocks
  notifyIosRunnerAppRelaunched, and the lifecycle test passes without it.

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: AdzeB

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

@@ -34,14 +34,21 @@ static void appendNode(
     if (windowMetadata != null) {
       appendWindowMetadata(xml, windowMetadata);
     }
-    appendNonEmptyAttribute(xml, "text", node.getText());
+    CharSequence text = node.getText();
+    if (text != null) {
+      appendAttribute(xml, "text", text);
+    }
     // getText() returns the HINT for an empty field on modern Android, so `text` alone cannot
     // distinguish a cleared field from one whose value equals its hint; only this flag can
     // (#2063 empty-fill verification).
-    appendTrueAttribute(
-        xml,
-        "hint-showing",
-        Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && node.isShowingHintText());
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      appendAttribute(xml, "hint-showing", Boolean.toString(node.isShowingHintText()));
+    }
+    appendAttribute(xml, "editable", Boolean.toString(node.isEditable()));
+    // Accessibility selection offsets, not a measurement of the value's length. Read-only
+    // selectable text exposes a selection too, so they do not depend on `editable`; -1 = unavailable.
+    appendNonNegativeAttribute(xml, "selection-start", node.getTextSelectionStart());
+    appendNonNegativeAttribute(xml, "selection-end", node.getTextSelectionEnd());
     appendNonEmptyAttribute(xml, "resource-id", node.getViewIdResourceName());
     appendAttribute(xml, "class", node.getClassName());
     appendNonEmptyAttribute(xml, "package", node.getPackageName());
@@ -66,7 +73,7 @@ static void appendNode(
           Boolean.toString(
               hasAccessibilityAction(node, AccessibilityAction.ACTION_SCROLL_BACKWARD)));
     }
-    appendTrueAttribute(xml, "password", node.isPassword());
+    appendAttribute(xml, "password", Boolean.toString(node.isPassword()));
     appendAttribute(
         xml,
         "bounds",
@@ -122,6 +129,12 @@ private static void appendNonEmptyAttribute(
     appendAttribute(xml, name, value);
   }
 
+  private static void appendNonNegativeAttribute(StringBuilder xml, String name, int value) {
+    if (value >= 0) {
+      appendAttribute(xml, name, Integer.toString(value));
+    }
+  }
+
   private static void appendTrueAttribute(StringBuilder xml, String name, boolean value) {
     if (value) {
       appendAttribute(xml, name, "true");

packages/kernel/src/snapshot.ts

@@ -107,6 +107,13 @@ export type RawSnapshotNode = {
   enabled?: boolean;
   selected?: boolean;
   focused?: boolean;
+  /** Native accessibility facts; absent means unavailable, not false. */
+  editable?: boolean;
+  password?: boolean;
+  hintShowing?: boolean;
+  /** Accessibility selection offsets, never a character count or proof of value equality. */
+  selectionStart?: number;
+  selectionEnd?: number;
   visibleToUser?: boolean;
   hittable?: boolean;
   depth?: number;

packages/platform-android/src/__tests__/ui-hierarchy-field-metadata.test.ts

@@ -0,0 +1,47 @@
+import { expect, test } from 'vitest';
+import { buildUiHierarchySnapshot, parseUiHierarchyTree } from '../ui-hierarchy.ts';
+
+test.each([false, true])(
+  'editable field metadata survives snapshot presentation (raw=%s)',
+  (raw) => {
+    const tree = parseUiHierarchyTree(`<hierarchy><node class="android.widget.EditText"
+    resource-id="field" text="" bounds="[0,0][200,100]" visible-to-user="true"
+    editable="true" password="true" hint-showing="false" selection-start="0" selection-end="0"
+    focusable="true" focused="true" /></hierarchy>`);
+    const { nodes } = buildUiHierarchySnapshot(tree, undefined, { raw });
+    expect(nodes.find((node) => node.identifier === 'field')).toMatchObject({
+      value: '',
+      editable: true,
+      password: true,
+      hintShowing: false,
+      selectionStart: 0,
+      selectionEnd: 0,
+    });
+  },
+);
+
+test('selection offsets survive on a read-only selectable node (independent of editable)', () => {
+  const tree = parseUiHierarchyTree(`<hierarchy><node class="android.widget.TextView"
+    resource-id="field" text="Read-only text" bounds="[0,0][200,100]" visible-to-user="true"
+    editable="false" selection-start="2" selection-end="5" /></hierarchy>`);
+  const { nodes } = buildUiHierarchySnapshot(tree, undefined, { raw: true });
+  expect(nodes.find((node) => node.identifier === 'field')).toMatchObject({
+    editable: false,
+    selectionStart: 2,
+    selectionEnd: 5,
+  });
+});
+
+test('missing native field metadata remains unknown instead of becoming false or zero', () => {
+  const tree = parseUiHierarchyTree(`<hierarchy><node class="android.widget.EditText"
+    resource-id="field" bounds="[0,0][200,100]" focusable="true" /></hierarchy>`);
+  const { nodes } = buildUiHierarchySnapshot(tree, undefined, { raw: true });
+  const field = nodes.find((node) => node.identifier === 'field');
+  expect(field).toBeDefined();
+  expect(field?.value).toBeUndefined();
+  expect(field?.editable).toBeUndefined();
+  expect(field?.password).toBeUndefined();
+  expect(field?.hintShowing).toBeUndefined();
+  expect(field?.selectionStart).toBeUndefined();
+  expect(field?.selectionEnd).toBeUndefined();
+});

packages/platform-android/src/ui-hierarchy-builder.ts

@@ -352,6 +352,11 @@ function createAndroidRawSnapshotNode(
     rect: node.rect,
     enabled: node.enabled,
     focused: node.focused,
+    editable: node.editable,
+    password: node.password,
+    hintShowing: node.hintShowing,
+    selectionStart: node.selectionStart,
+    selectionEnd: node.selectionEnd,
     visibleToUser: node.visibleToUser,
     hittable: isAgentTarget(node) || undefined,
     depth: compactedAndroidNodeDepth(state.nodes, parentIndex),

packages/platform-android/src/ui-hierarchy-node.ts

@@ -14,6 +14,11 @@ export type AndroidUiHierarchy = {
   enabled?: boolean;
   visibleToUser?: boolean;
   focused?: boolean;
+  editable?: boolean;
+  password?: boolean;
+  hintShowing?: boolean;
+  selectionStart?: number;
+  selectionEnd?: number;
   // Two independent facts, never collapsed, and never undefined: the helper omits false attributes
   // while stock UiAutomator writes them out, so reading an absent attribute as a value gave two
   // encodings of one control opposite answers.

packages/platform-android/src/ui-hierarchy.ts

@@ -35,6 +35,9 @@ export type AndroidUiNodeMetadata = {
   focusable?: boolean;
   focused?: boolean;
   password?: boolean;
+  editable?: boolean;
+  selectionStart?: number;
+  selectionEnd?: number;
   /**
    * Helper-only: the `text` attribute is the field's HINT, not its value (an empty input's
    * `getText()` returns the hint on modern Android). Absent in raw uiautomator dumps.
@@ -147,6 +150,9 @@ function readNodeAttributes(node: string): Omit<AndroidUiNodeMetadata, 'rect'> {
     focusable: boolAttr('focusable'),
     focused: boolAttr('focused'),
     password: boolAttr('password'),
+    ...optionalBoolAttr('editable', 'editable'),
+    ...optionalNumberAttr('selectionStart', 'selection-start'),
+    ...optionalNumberAttr('selectionEnd', 'selection-end'),
     ...optionalBoolAttr('hintShowing', 'hint-showing'),
     ...optionalBoolAttr('visibleToUser', 'visible-to-user'),
     ...optionalNumberAttr('drawingOrder', 'drawing-order'),
@@ -300,6 +306,11 @@ function normalizeAndroidUiHierarchyNode(
       rect: attrs.rect,
       enabled: attrs.enabled,
       focused: attrs.focused,
+      editable: attrs.editable,
+      password: attrs.password,
+      hintShowing: attrs.hintShowing,
+      selectionStart: attrs.selectionStart,
+      selectionEnd: attrs.selectionEnd,
       visibleToUser: attrs.visibleToUser,
       clickable: attrs.clickable === true,
       focusable: attrs.focusable === true,

src/daemon/__tests__/response-views.test.ts

@@ -300,6 +300,27 @@ test('get attrs digest compacts the node under a ref target', () => {
   expect(digest).toEqual({ ref: 'e7', node: COMPACT_NODE });
 });
 
+test('attrs digest keeps explicit false/zero/empty field facts; unavailable ones stay absent (#2288)', () => {
+  const fieldFacts = {
+    value: '',
+    editable: false,
+    password: false,
+    hintShowing: false,
+    selectionStart: 0,
+    selectionEnd: 0,
+  };
+  const digest = getView!({ ref: 'e7', node: { ...MATCHED_NODE, ...fieldFacts } }, 'digest');
+  expect(digest.node).toEqual({ ...COMPACT_NODE, ...fieldFacts });
+  // MATCHED_NODE carries none of the field facts: the digest must not invent them.
+  const unavailable = getView!({ ref: 'e7', node: MATCHED_NODE }, 'digest').node as Record<
+    string,
+    unknown
+  >;
+  for (const field of Object.keys(fieldFacts)) {
+    if (field !== 'value') expect(field in unavailable).toBe(false);
+  }
+});
+
 test('find/get default and full return today’s shape unchanged (same reference)', () => {
   const data: DaemonResponseData = { ref: '@e7', text: 'Sign in', node: MATCHED_NODE };
   expect(findView!(data, 'default')).toBe(data);

src/daemon/response-views.ts

@@ -90,10 +90,12 @@ function pickScreenshotDigestMetadata(data: DaemonResponseData): DaemonResponseD
   return metadata;
 }
 
-// The semantic attributes of a single matched node an agent reasons about. The
-// verbose framing a digest drops — geometry (`rect`), tree indices
-// (`index`/`parentIndex`/`depth`), and process/app plumbing
-// (`pid`/`bundleId`/`appName`/`windowTitle`/`surface`/…) — is intentionally absent.
+// The semantic attributes of a single matched node an agent reasons about,
+// including the field facts whose explicit false/zero/empty is the signal (#2288:
+// absent means unavailable). The verbose framing a digest drops — geometry
+// (`rect`), tree indices (`index`/`parentIndex`/`depth`), and process/app
+// plumbing (`pid`/`bundleId`/`appName`/`windowTitle`/`surface`/…) — is
+// intentionally absent.
 const SELECTOR_DIGEST_NODE_FIELDS = [
   'role',
   'type',
@@ -104,6 +106,11 @@ const SELECTOR_DIGEST_NODE_FIELDS = [
   'enabled',
   'selected',
   'focused',
+  'editable',
+  'password',
+  'hintShowing',
+  'selectionStart',
+  'selectionEnd',
   'hittable',
 ] as const;
 

website/docs/docs/snapshots.md

@@ -111,3 +111,17 @@ the strategy owns which tiers it may use.
   an empty tree.
 - Private-accessibility recovery and `--actions` reads are simulator-specific. Physical iOS devices
   have no equivalent independent semantic backend; they bound the XCTest work with a probe instead.
+
+## Android field metadata
+
+Android snapshot nodes and `get attrs` (including the digest response) carry the native
+`editable`, `password`, `hintShowing`, `selectionStart`, and `selectionEnd` facts whenever the
+accessibility tree reports them. Explicit `false` and `0` are kept; an absent field means the fact
+was unavailable, not false. `hintShowing` needs Android API 26 or later.
+
+- `value: ""` is an explicitly empty accessibility text; a missing `value` means no text was
+  reported. The text of an empty field is its hint on modern Android, so check `hintShowing`
+  before reading `value` as the entered contents.
+- `selectionStart`/`selectionEnd` are accessibility selection offsets. They are independent of
+  `editable` (read-only selectable text exposes them too), they are not a character count, and
+  they do not prove that a masked or secure value equals expected text.