peachsim 0.1.637 → 0.1.638

package/README.md

@@ -235,11 +235,14 @@ Pass a target to `peach open <port-or-url>` when a script or agent needs an expl
 selection.
 
 The first `peach open` launches an isolated Chrome for Testing sim. The CLI
-resolves Playwright from the current directory or beside its executable, asks that exact package for
-its required browser executable, and runs that package's installer once when
-the executable is absent. It never substitutes another revision found in the
-shared Playwright cache. Later opens reuse that sim and reload it at the
-requested target. Use `peach do reload` when the target has not changed.
+resolves Playwright from the current directory or beside its executable and
+launches the newest installed Chromium revision in its browser cache, honoring
+`PLAYWRIGHT_BROWSERS_PATH`. Set `PEACH_CHROMIUM_EXECUTABLE` to an existing
+executable to select a binary explicitly. Headless and headed launches use that
+same binary. When no installed browser is available, the CLI runs the resolved
+Playwright core's absolute installer entry. Later opens reuse that sim and
+reload it at the requested target. Use `peach do reload` when the target has not
+changed.
 Reserve `--new` for a genuinely concurrent sim; repeated new browser trees
 consume memory and CPU on shared machines.
 

package/cli/bridge-flow-runner.ts

@@ -6,7 +6,11 @@ import { REQUIRED_IDENTICAL_FLOW_FRAMES, framesIdentical } from '../detox/proof-
 import { flowTimeoutScale } from '../src/flow-timeout-scale'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
 import { sleep } from '../src/sleep'
-import { inspectWaitReady, waitReadyReason } from './commands/inspect/core'
+import {
+  inspectWaitReady,
+  isPeachAccessibilityTree,
+  waitReadyReason,
+} from './commands/inspect/core'
 import { waitForSootsimIdle } from './commands/inspect/settling'
 import { callShellCommandWhenReady, getShellState } from './commands/inspect/shared'
 import { PERMISSION_KINDS } from './commands/permissions'
@@ -16,7 +20,11 @@ import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
 import { ensureCliRecordingEntitlement } from './recording-access'
 import type { PerformResult, PerformStep, ResetResult } from '../src/bridge-contract'
 import type { WsBridge } from './ws-bridge'
-import type { SootSimReplayTarget, SootSimTapResult } from '@peach/globals'
+import type {
+  PeachAccessibilityNode,
+  SootSimReplayTarget,
+  SootSimTapResult,
+} from '@peach/globals'
 import type {
   SootSimExternalAppLifecycleOptions,
   SootSimLaunchArguments,
@@ -46,6 +54,9 @@ type FlowTargetSelector = {
   enabled?: boolean
   selected?: boolean
   checked?: boolean
+  focused?: boolean
+  containsChild?: FlowTargetSelector
+  containsDescendants?: FlowTargetSelector[]
   below?: string | FlowTargetSelector
   above?: string | FlowTargetSelector
   leftOf?: string | FlowTargetSelector
@@ -105,16 +116,10 @@ const SELECTOR_FILTER_KEYS = [
   'leftOf',
   'rightOf',
 ] as const
-// maestro filters without a verified ios reading here yet: `containsChild` and
-// `containsDescendants` walk the ios accessibility hierarchy, which hides the
-// children of an accessible element; `focused` is XCUIElement.hasFocus; `css`
-// is web only.
-const UNSUPPORTED_SELECTOR_KEYS = [
-  'containsChild',
-  'containsDescendants',
-  'focused',
-  'css',
-]
+// maestro filters without a verified ios reading here yet: `css` is web only.
+// `containsChild`, `containsDescendants`, and `focused` read the engine's
+// XCTest accessibility projection (see findElementAccessibilityTree).
+const UNSUPPORTED_SELECTOR_KEYS = ['css']
 // ignoring a key widens the match, so an assertion passes that maestro fails.
 function assertSupportedSelector(selector: unknown) {
   if (!selector || typeof selector !== 'object') return
@@ -125,10 +130,384 @@ function assertSupportedSelector(selector: unknown) {
   if (unsupported.length > 0) {
     throw new Error(`selector ${unsupported.join(', ')} is not supported by peach yet`)
   }
-  for (const key of ['childOf', 'below', 'above', 'leftOf', 'rightOf']) {
+  for (const key of ['childOf', 'below', 'above', 'leftOf', 'rightOf', 'containsChild']) {
     assertSupportedSelector(Reflect.get(selector, key))
   }
+  const descendants = Reflect.get(selector, 'containsDescendants')
+  if (descendants !== undefined) {
+    if (!Array.isArray(descendants)) {
+      throw new Error('selector containsDescendants must be a list of selectors')
+    }
+    for (const descendant of descendants) assertSupportedSelector(descendant)
+  }
+}
+
+// the filters whose meaning is defined on the XCTest accessibility hierarchy.
+// ordinary lookups stay on the faster render tree; these read the engine's
+// accessibility projection through captureAccessibilityTree().
+const ACCESSIBILITY_SELECTOR_KEYS = [
+  'containsChild',
+  'containsDescendants',
+  'focused',
+] as const
+
+function needsAccessibilityProjection(selector: string | FlowTargetSelector): boolean {
+  if (typeof selector === 'string') return false
+  if (ACCESSIBILITY_SELECTOR_KEYS.some((key) => selector[key] != null)) return true
+  return ['childOf', 'below', 'above', 'leftOf', 'rightOf'].some((key) => {
+    const nested: unknown = Reflect.get(selector, key)
+    return isSelectorRecord(nested) && needsAccessibilityProjection(nested)
+  })
+}
+
+type AccessibilityNodePredicate = (node: PeachAccessibilityNode) => boolean
+
+// preorder aggregate, the same order TreeNode.aggregate() walks on ios.
+function accessibilityTreeNodes(
+  tree: readonly PeachAccessibilityNode[],
+): PeachAccessibilityNode[] {
+  const out: PeachAccessibilityNode[] = []
+  const visit = (node: PeachAccessibilityNode): void => {
+    out.push(node)
+    for (const child of node.children) visit(child)
+  }
+  for (const root of tree) visit(root)
+  return out
+}
+
+// a container's own hierarchy: the node plus every descendant, matching
+// ViewHierarchy(element.treeNode).aggregate().
+function accessibilitySubtreeNodes(
+  node: PeachAccessibilityNode,
+): PeachAccessibilityNode[] {
+  return [node, ...node.children.flatMap(accessibilitySubtreeNodes)]
+}
+
+// maestro matches the whole id or text against the selector's regex; the
+// render-tree resolver compiles the same anchored pattern.
+function accessibilityTextMatcher(
+  value: string,
+  kind: 'text' | 'id',
+): (candidate: string | null) => boolean {
+  const pattern = new RegExp(`^(?:${value})$`)
+  return (candidate) => {
+    // IOSDriver emits an empty attribute for absent label, value and id.
+    const native = candidate ?? ''
+    if (kind === 'id')
+      return (
+        pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+      )
+    const stripped = native.replaceAll('\n', ' ')
+    return (
+      native === value ||
+      stripped === value ||
+      pattern.test(native) ||
+      pattern.test(stripped)
+    )
+  }
+}
+
+// maestro reads ios frames as integer edges (AXElement.boundsString).
+function accessibilityBounds(node: PeachAccessibilityNode): {
+  x: number
+  y: number
+  width: number
+  height: number
+} {
+  const left = Math.trunc(node.frame.x)
+  const top = Math.trunc(node.frame.y)
+  return {
+    x: left,
+    y: top,
+    width: Math.trunc(node.frame.x + node.frame.width) - left,
+    height: Math.trunc(node.frame.y + node.frame.height) - top,
+  }
+}
+
+const ACCESSIBILITY_TRAIT_FILTERS: Record<string, AccessibilityNodePredicate> = {
+  // IOSDriver sets attributes["text"] on every node, including empty text.
+  TEXT: () => true,
+  SQUARE: (node) => {
+    const bounds = accessibilityBounds(node)
+    return Math.abs(1 - bounds.width / bounds.height) < 0.03
+  },
+  LONG_TEXT: (node) => (node.value?.length ?? 0) > 200,
+}
+
+// Orchestra.buildFilter's basic filters, in its order: text, id, size,
+// traits, enabled, selected, checked, focused. css is refused before this runs.
+function accessibilityBasicFilters(
+  selector: FlowTargetSelector,
+): AccessibilityNodePredicate[] {
+  const filters: AccessibilityNodePredicate[] = []
+  if (selector.text != null) {
+    const matches = accessibilityTextMatcher(selector.text, 'text')
+    // ios textMatches reads attributes text, hintText (the placeholder) and
+    // accessibilityText; the canonical label/value/placeholder carry those.
+    filters.push(
+      (node) => matches(node.label) || matches(node.value) || matches(node.placeholder),
+    )
+  }
+  if (selector.id != null) {
+    const matches = accessibilityTextMatcher(selector.id, 'id')
+    filters.push((node) => matches(node.testID))
+  }
+  if (selector.width != null || selector.height != null) {
+    const tolerance = selector.tolerance ?? 0
+    filters.push((node) => {
+      const bounds = accessibilityBounds(node)
+      return (
+        (selector.width == null ||
+          Math.abs(bounds.width - selector.width) <= tolerance) &&
+        (selector.height == null ||
+          Math.abs(bounds.height - selector.height) <= tolerance)
+      )
+    })
+  }
+  for (const trait of selector.traits ? selector.traits.split(' ') : []) {
+    const filter = ACCESSIBILITY_TRAIT_FILTERS[trait.replaceAll('-', '_').toUpperCase()]
+    if (!filter) throw new Error(`unknown selector trait: ${trait}`)
+    filters.push(filter)
+  }
+  if (selector.enabled != null) {
+    filters.push((node) => node.enabled === selector.enabled)
+  }
+  if (selector.selected != null) {
+    filters.push((node) => node.selected === selector.selected)
+  }
+  if (selector.checked != null) {
+    filters.push((node) => node.checked === selector.checked)
+  }
+  // XCTest may omit hasFocus; the native driver defaults an absent snapshot
+  // key to false, and editing focus is a separate native concept.
+  if (selector.focused != null) {
+    filters.push((node) => (node.hasFocus ?? false) === selector.focused)
+  }
+  return filters
+}
+
+// Filters.deepestMatchingElement: a node contributes its deepest matching
+// descendants when any exist, else itself when it matches.
+function deepestMatchingAccessibilityNodes(
+  nodes: readonly PeachAccessibilityNode[],
+  matches: AccessibilityNodePredicate,
+): PeachAccessibilityNode[] {
+  const out: PeachAccessibilityNode[] = []
+  const included = new Set(nodes)
+  const nested = new Set(
+    nodes.flatMap((node) => node.children.filter((child) => included.has(child))),
+  )
+  for (const node of nodes.filter((node) => !nested.has(node))) {
+    const children = deepestMatchingAccessibilityNodes(node.children, matches)
+    if (children.length > 0) out.push(...children)
+    else if (matches(node)) out.push(node)
+  }
+  return distinctAccessibilityNodes(out)
+}
+
+function distinctAccessibilityNodes(
+  nodes: readonly PeachAccessibilityNode[],
+): PeachAccessibilityNode[] {
+  // TreeNode.distinct compares native fields and children, not engine identity.
+  // bucket by scalar attributes first; full subtree comparisons are only needed
+  // for nodes with identical attributes and the same number of children.
+  const buckets = new Map<string, PeachAccessibilityNode[]>()
+  return nodes.filter((node) => {
+    const key = JSON.stringify([
+      node.testID ?? '',
+      node.label ?? '',
+      node.placeholder ?? '',
+      node.value ?? '',
+      node.enabled,
+      node.selected,
+      node.checked,
+      node.clickable,
+      node.hasFocus ?? false,
+      accessibilityBounds(node),
+      node.children.length,
+    ])
+    const bucket = buckets.get(key)
+    if (bucket?.some((other) => sameNativeAccessibilityShape(node, other))) return false
+    if (bucket) bucket.push(node)
+    else buckets.set(key, [node])
+    return true
+  })
+}
+
+function isSelectorRecord(value: unknown): value is FlowTargetSelector {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function accessibilityAnchorSelector(value: unknown): FlowTargetSelector {
+  if (typeof value === 'string') return { text: value }
+  return isSelectorRecord(value) ? value : {}
+}
+
+// upstream Filters.containsChild compares the resolved child TreeNode against
+// a candidate's immediate children by structural equality: the native
+// attribute map, the boolean flags, and the children, recursively. the native
+// hintText attribute is the placeholder (accessibilityHint is not a TreeNode
+// attribute), and engine identity (elementId/nodeId) plus the projection's own
+// metadata (type, role, isAccessibilityElement, state) are not part of that
+// native shape.
+function sameNativeAccessibilityShape(
+  a: PeachAccessibilityNode,
+  b: PeachAccessibilityNode,
+): boolean {
+  if (
+    (a.testID ?? '') !== (b.testID ?? '') ||
+    (a.label ?? '') !== (b.label ?? '') ||
+    (a.placeholder ?? '') !== (b.placeholder ?? '') ||
+    (a.value ?? '') !== (b.value ?? '') ||
+    a.enabled !== b.enabled ||
+    a.selected !== b.selected ||
+    a.checked !== b.checked ||
+    a.clickable !== b.clickable ||
+    (a.hasFocus ?? false) !== (b.hasFocus ?? false) ||
+    JSON.stringify(accessibilityBounds(a)) !== JSON.stringify(accessibilityBounds(b)) ||
+    a.children.length !== b.children.length
+  ) {
+    return false
+  }
+  for (const [index, child] of a.children.entries()) {
+    const other = b.children[index]
+    if (!other || !sameNativeAccessibilityShape(child, other)) return false
+  }
+  return true
+}
+
+// Filters.containsDescendants: every selector must match inside a child
+// subtree; the node itself is excluded. A selector matches a subtree node by
+// the full filter applied to that single node (Filters' `matches`), which for
+// relative filters resolves anchors against the same one-node list.
+function accessibilitySubtreeMatches(
+  all: readonly PeachAccessibilityNode[],
+  node: PeachAccessibilityNode,
+  selector: FlowTargetSelector,
+): boolean {
+  if (filterAccessibilityNodes(all, [node], selector).length > 0) return true
+  return node.children.some((child) => accessibilitySubtreeMatches(all, child, selector))
+}
+
+// Orchestra's childOf scopes the whole lookup to the container's hierarchy
+// before any filter runs (findElementViewHierarchy + aggregate); a container
+// that does not resolve leaves nothing to search.
+function filterAccessibilityNodes(
+  all: readonly PeachAccessibilityNode[],
+  nodes: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode[] {
+  if (selector.childOf == null) {
+    return filterAccessibilityNodesIn(all, nodes, selector)
+  }
+  const container = filterAccessibilityNodes(
+    all,
+    all,
+    accessibilityAnchorSelector(selector.childOf),
+  )[0]
+  if (!container) return []
+  return filterAccessibilityNodesIn(all, accessibilitySubtreeNodes(container), selector)
 }
+
+// Orchestra.buildFilter over the accessibility projection: basic filters
+// through deepestMatching, then the relative filters intersected in
+// buildFilter's order, then index or clickableFirst. `nodes` is the candidate
+// list a relative anchor filter sees, exactly as Filters.intersect applies
+// every filter to the same input list.
+function filterAccessibilityNodesIn(
+  all: readonly PeachAccessibilityNode[],
+  nodes: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode[] {
+  const basic = accessibilityBasicFilters(selector)
+  let candidates =
+    basic.length > 0
+      ? deepestMatchingAccessibilityNodes(nodes, (node) =>
+          basic.every((filter) => filter(node)),
+        )
+      : [...nodes]
+
+  const relativeGeometry = {
+    below: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).y > accessibilityBounds(other).y,
+    above: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).y < accessibilityBounds(other).y,
+    leftOf: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).x < accessibilityBounds(other).x,
+    rightOf: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).x > accessibilityBounds(other).x,
+  } as const
+  for (const key of ['below', 'above', 'leftOf', 'rightOf'] as const) {
+    const anchor = selector[key]
+    if (anchor == null) continue
+    const anchors = filterAccessibilityNodes(
+      all,
+      nodes,
+      accessibilityAnchorSelector(anchor),
+    )
+    candidates = candidates.filter((node) =>
+      anchors.some((other) => relativeGeometry[key](node, other)),
+    )
+  }
+
+  if (selector.containsChild != null) {
+    // Orchestra resolves the child selector globally (findElement with
+    // optional=false) before the predicate runs. an unresolved child matches
+    // nothing, so a caller's retry window still applies.
+    const child = filterAccessibilityNodes(
+      all,
+      all,
+      accessibilityAnchorSelector(selector.containsChild),
+    )[0]
+    candidates = child
+      ? candidates.filter((node) =>
+          node.children.some((candidate) =>
+            sameNativeAccessibilityShape(candidate, child),
+          ),
+        )
+      : []
+  }
+
+  if (selector.containsDescendants != null) {
+    const descendants = selector.containsDescendants.map(accessibilityAnchorSelector)
+    candidates = candidates.filter((node) =>
+      descendants.every((descendant) =>
+        node.children.some((child) =>
+          accessibilitySubtreeMatches(all, child, descendant),
+        ),
+      ),
+    )
+  }
+
+  // Filters.intersect converts every filter result to a TreeNode set,
+  // including selectors containing only structural or relative filters.
+  candidates = distinctAccessibilityNodes(candidates)
+
+  if (selector.index != null) {
+    const index = Math.trunc(Number(selector.index))
+    const sorted = [...candidates].sort((a, b) => {
+      const aBounds = accessibilityBounds(a)
+      const bBounds = accessibilityBounds(b)
+      return aBounds.y - bBounds.y || aBounds.x - bBounds.x
+    })
+    const resolved = index >= 0 ? index : sorted.length + index
+    if (resolved < 0 || resolved >= sorted.length) return []
+    const picked = sorted[resolved]
+    return picked ? [picked] : []
+  }
+  // clickableFirst is a stable descending sort; ios reports no clickable bit,
+  // so every node ties and the filter order survives.
+  return [...candidates].sort((a, b) => Number(b.clickable) - Number(a.clickable))
+}
+
+function resolveAccessibilitySelector(
+  tree: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode | null {
+  const all = accessibilityTreeNodes(tree)
+  return filterAccessibilityNodes(all, all, selector)[0] ?? null
+}
+
 type FocusedTextInputInfo = {
   nodeId?: number | null
   id?: string | null
@@ -910,6 +1289,12 @@ export class SootSimBridgeFlowRunner {
 
   private async findElement(opts: FlowTargetSelector) {
     assertSupportedSelector(opts)
+    // the structural filters are defined on the XCTest accessibility
+    // hierarchy, so they resolve against the engine's accessibility
+    // projection instead of the render tree.
+    if (needsAccessibilityProjection(opts)) {
+      return this.findElementAccessibilityTree(opts)
+    }
     // id selectors, patterns and filtered selectors resolve over the full
     // candidate set in maestro's order, so a repeated id (one per list row)
     // means the top row. a literal text selector keeps the direct lookup.
@@ -951,6 +1336,47 @@ export class SootSimBridgeFlowRunner {
     })()`)
   }
 
+  // structural filters (containsChild / containsDescendants / focused) read the
+  // engine's XCTest accessibility projection — one bridge evaluate, then the
+  // same Orchestra.buildFilter semantics the render resolver implements, over
+  // PeachAccessibilityNode instead of the visible semantic tree.
+  private async findElementAccessibilityTree(opts: FlowTargetSelector) {
+    const tree = await this.evaluate(`(async () => {
+      const test = window.__sootsimTest
+      if (!test || typeof test.captureAccessibilityTree !== 'function') throw new Error('engine accessibility snapshot is unavailable')
+      return await test.captureAccessibilityTree()
+    })()`)
+    if (!isPeachAccessibilityTree(tree))
+      throw new Error('engine returned an invalid accessibility snapshot')
+    if (tree.length === 0) return null
+    if (tree.some((node) => node.platform !== 'ios'))
+      throw new Error(
+        'containsChild, containsDescendants and focused require the iOS accessibility hierarchy',
+      )
+    const node = resolveAccessibilitySelector(tree, opts)
+    if (!node) return null
+    const frame = node.frame
+    return {
+      nodeId: Number.isFinite(node.nodeId) ? node.nodeId : null,
+      id: node.testID,
+      testID: node.testID,
+      text: node.label,
+      accessibilityLabel: node.label,
+      absolutePosition: { x: frame.x, y: frame.y },
+      layout: { width: frame.width, height: frame.height },
+      // the engine applies Maestro's integer-frame viewport filter to the
+      // native hierarchy before this lookup; preserve the native bounds.
+      visibleFrame: {
+        x: frame.x,
+        y: frame.y,
+        width: frame.width,
+        height: frame.height,
+        area: frame.width * frame.height,
+      },
+      isTextInput: node.isTextInput,
+    }
+  }
+
   // maestro's selector resolver (Orchestra.buildFilter over Filters.kt):
   // id and text patterns, size, traits, enabled/selected, the relative
   // below/above/leftOf/rightOf filters, `index:` (nth match) and `childOf:`
@@ -1410,7 +1836,9 @@ export class SootSimBridgeFlowRunner {
     // looks up by id or text alone, so a selector that narrows further only
     // takes it for an element its own match already found.
     const narrowed =
-      opts.index != null || SELECTOR_FILTER_KEYS.some((key) => opts[key] != null)
+      opts.index != null ||
+      SELECTOR_FILTER_KEYS.some((key) => opts[key] != null) ||
+      ACCESSIBILITY_SELECTOR_KEYS.some((key) => opts[key] != null)
     const direct = element || !narrowed ? await this.activatePressTarget(opts) : null
     if (direct?.ok) {
       await this.settleAfterInput()

package/cli/commands/inspect/core.ts

@@ -27,6 +27,7 @@ import type {
   SimSemanticSelector,
 } from '../../../src/bridge-contract'
 import type {
+  PeachAccessibilityNode,
   SootSimRouteInfo,
   SootSimRequestEntry,
   SootSimTimelineEvent,
@@ -904,40 +905,108 @@ export interface AccessibilityTreeNode {
   size: { w: number; h: number } | null
 }
 
-// `get a11y` — flat accessibility summary projected from the visible semantic
-// tree, which already excludes hidden and covered content, minus the painted
-// content VoiceOver cannot reach.
+// runtime shape check for the engine's PeachAccessibilityNode projection: the
+// bridge is a JSON boundary, so a node that lost a field must read as "no
+// snapshot" rather than flatten into a half-populated row.
+export function isPeachAccessibilityTree(
+  value: unknown,
+): value is PeachAccessibilityNode[] {
+  if (!Array.isArray(value)) return false
+  return value.every((node) => {
+    if (node === null || typeof node !== 'object') return false
+    if (
+      Reflect.get(node, 'platform') !== 'ios' &&
+      Reflect.get(node, 'platform') !== 'android'
+    )
+      return false
+    if (typeof Reflect.get(node, 'elementId') !== 'string') return false
+    if (!Number.isInteger(Reflect.get(node, 'nodeId'))) return false
+    for (const key of ['type', 'role']) {
+      if (typeof Reflect.get(node, key) !== 'string') return false
+    }
+    for (const key of ['testID', 'label', 'hint', 'value', 'placeholder']) {
+      const field = Reflect.get(node, key)
+      if (field !== null && typeof field !== 'string') return false
+    }
+    for (const key of [
+      'isAccessibilityElement',
+      'enabled',
+      'selected',
+      'checked',
+      'clickable',
+      'isTextInput',
+    ]) {
+      if (typeof Reflect.get(node, key) !== 'boolean') return false
+    }
+    const hasFocus = Reflect.get(node, 'hasFocus')
+    if (hasFocus !== undefined && typeof hasFocus !== 'boolean') return false
+    const state = Reflect.get(node, 'state')
+    if (state !== null) {
+      if (typeof state !== 'object') return false
+      const checked = Reflect.get(state, 'checked')
+      if (typeof checked !== 'boolean' && checked !== 'mixed') return false
+      for (const key of ['disabled', 'selected', 'busy', 'expanded']) {
+        if (typeof Reflect.get(state, key) !== 'boolean') return false
+      }
+    }
+    const value = Reflect.get(node, 'accessibilityValue')
+    if (value !== null) {
+      if (typeof value !== 'object') return false
+      for (const key of ['min', 'max', 'now']) {
+        const field = Reflect.get(value, key)
+        if (field !== undefined && (typeof field !== 'number' || !Number.isFinite(field)))
+          return false
+      }
+      const text = Reflect.get(value, 'text')
+      if (text !== undefined && typeof text !== 'string') return false
+    }
+    if (!isSemanticGeometry(Reflect.get(node, 'frame'))) return false
+    return isPeachAccessibilityTree(Reflect.get(node, 'children'))
+  })
+}
+
+// `get a11y` — flat VoiceOver presentation of the engine's XCTest
+// accessibility projection (SootSimTestBridge.captureAccessibilityTree).
+// VoiceOver reads an accessibility element as one group, so an element's
+// children are hidden from this flat view even though the snapshot keeps them
+// for Maestro's structural selectors (containsChild / containsDescendants).
 export async function inspectAccessibilityTree(
   bridge: InspectBridge,
 ): Promise<AccessibilityTreeNode[]> {
   const result: unknown = await bridge.send({
     type: 'query',
-    query: { kind: 'find', selector: { visible: true } },
+    query: { kind: 'accessibility' },
   })
-  if (!isSemanticQueryResult(result)) return []
-  return result.nodes.flatMap((node) => {
-    if (node.accessibilityHidden) return []
-    if (!node.role && !node.label && !node.text && !node.pressable) return []
-    return [
-      {
-        role:
-          node.role ??
-          (node.pressable ? 'button' : node.type === 'text' ? 'statictext' : 'none'),
-        label: node.label ?? node.text ?? null,
-        hint: null,
-        state: null,
-        testID: node.testID ?? null,
+  const tree =
+    result !== null && typeof result === 'object'
+      ? Reflect.get(result, 'accessibility')
+      : undefined
+  if (!isPeachAccessibilityTree(tree))
+    throw new Error('engine returned an invalid accessibility snapshot')
+  const nodes: AccessibilityTreeNode[] = []
+  const visit = (node: PeachAccessibilityNode): void => {
+    if (node.isAccessibilityElement) {
+      nodes.push({
+        role: node.role,
+        label: node.label,
+        hint: node.hint,
+        state: node.state ? { ...node.state } : null,
+        testID: node.testID,
         position: {
-          x: Math.round(node.geometry.x),
-          y: Math.round(node.geometry.y),
+          x: Math.round(node.frame.x),
+          y: Math.round(node.frame.y),
         },
         size: {
-          w: Math.round(node.geometry.width),
-          h: Math.round(node.geometry.height),
+          w: Math.round(node.frame.width),
+          h: Math.round(node.frame.height),
         },
-      },
-    ]
-  })
+      })
+      if (node.platform === 'ios') return
+    }
+    for (const child of node.children) visit(child)
+  }
+  for (const root of tree) visit(root)
+  return nodes
 }
 
 // ─── find ───