Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

test: document and cover native AX hierarchy

Yanni Pang3f64e21bf42f
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 7fee0469..29b5dad9 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -2125,7 +2125,7 @@ live-tested with this change.
## Opt-in native accessibility hierarchy (2026-09-30)
-The local native bridge behind ui.tree with nested:true follows private iOS
+The opt-in native bridge behind ui.tree with nested:true follows private iOS
attribute 5001 (immediate children) and checks each edge against attribute 5002
(parent) using CFEqual identity. The existing flat interface continues to use
icli's visible-element query; this bridge does not infer ancestry from frames,
@@ -2133,16 +2133,17 @@ labels, identifiers, or the visible-element array. Primary attribute mappings
are in [MCPAXNodeSource.m](https://github.com/witchan/ios-mcp/blob/8f46b68/MCPAXNodeSource.m)
and [MCPAXAttributeBridge.m](https://github.com/witchan/ios-mcp/blob/8f46b68/MCPAXAttributeBridge.m).
-An isolated entitled helper on pcc-research-01, iOS 27, returned 176 Settings
+An isolated entitled helper on an iOS 27 research VM returned 176 Settings
nodes with 173 matching parent back-references and 3 mismatches, 44 Calculator
nodes with 42 matches and 1 mismatch, and 66 Clock nodes with 65 matches and
-no mismatch. Settings and Calculator are explicitly partial. These counts
-include unnamed, offscreen, zero-frame, and frameless structure; repeated
-objects use snapshot-local references. Node, depth, query, and deadline limits
+no mismatch. Settings and Calculator are explicitly partial. Tests cover
+unnamed, offscreen, zero-frame, and frameless structure; live snapshots preserve
+unnamed containers and repeated objects through snapshot-local references.
+Node, depth, query, and deadline limits
are explicit, and a missing or failed messaging timeout blocks the AX query.
Foreground PID stayed unchanged and accessibility switches were restored for
-each helper run. Temporary services were unloaded and their directories removed;
-pcc-research-02 was untouched. Helper evidence is not an integrated daemon
+each helper run. Temporary services were unloaded and their directories removed.
+Helper evidence is not an integrated daemon
release or cold-start readiness claim.
Installed-daemon cold-read testing subsequently exposed an initial Settings
@@ -2152,12 +2153,12 @@ enabled accessibility, after one 400 ms readiness wait. It shares the original
deadline and query budget, preserves the initial error in readiness metadata,
and retains unresolved errors. No child error or action is retried.
-After a supported bundle installation and phone01 restart, the first Settings
+After a supported bundle installation and VM restart, the first Settings
CLI read recovered and returned 220 nodes with 217 matching parent checks and
3 disagreements; subsequent reads returned 176. Fresh Calculator returned
44 partial nodes and Clock 66 complete nodes. Flat queries and the nested
alias also worked. These are diagnostic inspection results on that VM,
-not full action-cycle performance acceptance. Phone02 remained stopped.
+not full action-cycle performance acceptance or repeat cold-start reliability.
The Release build also reproduced SIGPIPE failures in bundle validation:
early-exiting grep and awk closed their file/vtool producers under pipefail.
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index e0e23be5..30396dc6 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -301,6 +301,72 @@ panels an older agent cannot serve. icli failures reach the caller with
icli's own error `code` (`failed`, `unavailable`, `device_locked`, …) and
message.
+## Nested accessibility snapshots
+
+`ui.tree` (alias `accessibility.tree`) keeps its existing flat result unless
+the RPC params contain `"nested": true`. `nested` must be a JSON boolean.
+For example:
+
+```json
+{"method":"ui.tree","params":{"nested":true,"max_elements":500,"max_depth":32,"timeout_ms":5000}}
+```
+
+Nested snapshots accept only integer bounds: `max_elements` defaults to 500
+(1–2000), `max_depth` to 32 (1–32, with the root at depth 0), and `timeout_ms`
+to 5000 (100–10000). They preserve structural nodes: omit `visible_only` and
+`limit`, and do not enable `clickable_only`; these filters are rejected.
+The daemon verifies the same foreground application and PID before and after
+the snapshot. A changed or unverifiable foreground returns an operation error.
+
+The native walker starts from that application's AX root and reads immediate
+children through private iOS attribute 5001. Attribute 5002 independently
+checks each child's parent; labels, frames and visible/explorer arrays do not
+establish relationships. The result contains `source: "ax"`, `format: "nested"`,
+`relationship_source`, `roots`, and a unique-node `count`. Each node has a
+snapshot-local `id`, `label`, `identifier`, `role`, `frame` (or null), `depth`,
+`children`, `children_status`, `parent_verified`, and `query_errors`.
+Repeated nodes use `ref`; `cycle` distinguishes an active ancestor from a
+shared node. IDs do not persist between snapshots. `action_eligible: false`
+marks the snapshot as diagnostic; its IDs are not tap selectors.
+
+Inspect `status` (`complete`, `partial`, or `unavailable`), `truncated`, and
+`truncation_reasons` before consuming the tree. Element, depth, query and time
+limits produce partial results; the query budget is `max_elements * 8`.
+`limits`, `queries`, `elapsed_ms`, and `parent_checks` (verified, mismatch,
+unavailable) expose the walk's bounds and relationship checks. Per-node errors
+include the attribute number and native error code; optional text or frame
+attributes can be unavailable even when the structural walk is complete.
+`symbols`, `switches_before`, and `switches_after_restore` expose native API
+availability and accessibility switch restoration; `native_exception` is
+included if a native exception prevented the snapshot. `foreground_before`,
+`foreground_after`, and `runtime` identify the verified app and serving daemon.
+
+`readiness` reports `switches_enabled_for_invocation`, `retry_attempted`,
+`retry_resolved`, `wait_ms`, `max_wait_ms`, and `initial_query_errors`.
+Only an invocation that newly enables an AX switch may retry the first root
+label query after error -25215 with no value. It waits once for 400 ms only
+when more than 400 ms remain, sharing the original deadline and query budget.
+Resolved initial errors stay in `readiness.initial_query_errors`; child errors
+do not trigger this retry. Attribute calls request at most a 100 ms messaging
+timeout, but private API calls can exceed it if the OS does not honor it.
+
+This is an opt-in diagnostic path using private iOS AX symbols and attribute
+numbers, whose availability and behavior can change between OS releases.
+Partial checks remain necessary on each snapshot. Run the native walker tests
+from the checkout on a Mac with Xcode tools:
+
+```sh
+VPhoneDaemon/Tests/run-hierarchy-tests.sh
+```
+
+The runner builds in a temporary directory, checks injected child/parent links,
+cycles, malformed values, limits, timeout failures and readiness recovery,
+prints native coverage, and removes its outputs. The script also accepts an
+absolute invocation path from any working directory. It does not require a guest;
+these tests do not establish compatibility with every iOS build.
+
+## Environment and identity updates
+
The environment update keeps `launchdhook-vphone.dylib`,
`SystemHook-vphone.dylib`, `libvcamcaptured.dylib` and `libcamfix.dylib` in
`/usr/lib` in step with the host bundle. After each connection the VM
diff --git a/VPhoneDaemon/Tests/HierarchyTests.m b/VPhoneDaemon/Tests/HierarchyTests.m
new file mode 100644
index 00000000..d1be7663
--- /dev/null
+++ b/VPhoneDaemon/Tests/HierarchyTests.m
@@ -0,0 +1,162 @@
+#import <Foundation/Foundation.h>
+#import <unistd.h>
+#import <CoreGraphics/CoreGraphics.h>
+#import <assert.h>
+#import <math.h>
+#import "../Native/vphoned_ax_hierarchy.h"
+
+// Injected AX functions exercise the walker on macOS without a guest or private AX symbols.
+// VP_HIERARCHY_RECEIPTS, when set by the runner, checks JSON output in its temporary directory.
+static int calls;
+static int mode;
+static int rootLabels;
+static NSDictionary *coldWalk(VPAxFunctions f, BOOL enabled, int elements, int duration) {
+ calls=0;rootLabels=0;
+ return vp_ax_walk_with_readiness(f,(__bridge CFTypeRef)@"A",42,elements,8,duration,enabled);
+}
+static void receipt(NSString *name, NSDictionary *report) {
+ NSString *directory=NSProcessInfo.processInfo.environment[@"VP_HIERARCHY_RECEIPTS"];
+ if(!directory)return;
+ NSData *data=[NSJSONSerialization dataWithJSONObject:report options:NSJSONWritingPrettyPrinted|NSJSONWritingSortedKeys error:NULL];
+ assert(data && [data writeToFile:[directory stringByAppendingPathComponent:[name stringByAppendingString:@".json"]] atomically:YES]);
+}
+static int copyAttr(CFTypeRef element, CFStringRef attr, CFTypeRef *out) {
+ ++calls; if(mode==6) usleep(120000);
+ NSString *key=(__bridge NSString *)element;
+ unsigned long code=(uintptr_t)attr;
+ id result=nil;
+ if(code==2001 && [key isEqual:@"A"]) ++rootLabels;
+ if(((mode>=9 && mode<=11) || mode==17) && rootLabels<2) return mode==11?-25212:-25215;
+ if(mode==10) return -25215;
+ if(mode==12 && code==2001 && [key isEqual:@"B"]) return -25215;
+ if(mode==13 && calls==1) {usleep(750000);return -25215;}
+ if(mode==14 && calls==1) return -25215;
+ if(code==2003 && ((mode>=18 && mode<=20) || (mode==21 && [key isEqual:@"B"]))) result=[NSData data];
+ else if(code==5001) {
+ if((mode==7 || mode==14) && [key isEqual:@"A"]) { *out=CFBridgingRetain([NSArray arrayWithObjects:@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",@"B",nil]);return 0;}
+ if((mode==7 || mode==14) && [key isEqual:@"B"]) {*out=CFBridgingRetain(@[]);return 0;}
+ if(mode==2) return -25212;
+ if(mode==3) { *out=CFBridgingRetain(@"not array");return 0;}
+ if(mode==4 && [key isEqual:@"C"]) result=@[@"D"];
+ else if(mode==1 && [key isEqual:@"B"]) result=@[@"A"];
+ else if([key isEqual:@"A"]) result=@[@"B",@"C"];
+ else if([key isEqual:@"B"]) result=@[@"D"];
+ else result=@[];
+ } else if(code==5002 && mode==5) return -25212;
+ else if(code==5002 && ![key isEqual:@"A"]) result=[key isEqual:@"D"]?@"B":@"A";
+ else if(code==2001) result=mode==21 && [key isEqual:@"B"]?@"":@"same label";
+ else return -25212;
+ *out=CFBridgingRetain(result);return 0;
+}
+static CFTypeID typeID(void) {return CFStringGetTypeID();}
+static Boolean frameValue(CFTypeRef value,int kind,void *out) {
+ (void)value;assert(kind==3);
+ if(mode==20)return false;
+ if(mode==21) {*(CGRect *)out=CGRectMake(-250,-30,0,0);return true;}
+ *(CGRect *)out=CGRectMake(mode==19?NAN:10,20,30,40);return true;
+}
+static int timeout(CFTypeRef a,float t) {(void)a;(void)t;return mode==8?-25204:mode==15?-25215:mode==17 && rootLabels==1?-25204:0;}
+int main(void) {@autoreleasepool {
+ VPAxFunctions f={.copy=copyAttr,.elementTypeID=typeID,.setTimeout=timeout};
+ NSDictionary *r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"count"] intValue]==4);assert(![r[@"truncated"] boolValue]);
+ assert(![r[@"readiness"][@"switches_enabled_for_invocation"] boolValue]);
+ assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert(![r[@"readiness"][@"retry_resolved"] boolValue]);
+ assert([r[@"readiness"][@"initial_query_errors"] count]==0);
+ assert([r[@"readiness"][@"wait_ms"] doubleValue]==0);
+ assert([r[@"parent_checks"][@"verified"] intValue]==3);
+ NSDictionary *root=r[@"roots"][0];assert(root[@"frame"]==NSNull.null);
+ assert([root[@"children"] count]==2);assert([root[@"children"][0][@"children"] count]==1);
+ r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,2,8,1000);
+ assert([r[@"count"] intValue]==2);assert([r[@"truncated"] boolValue]);
+ r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,0,1000);
+ assert([r[@"count"] intValue]==1);assert([r[@"truncated"] boolValue]);
+ mode=1; r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"count"] intValue]==3);assert([r[@"roots"][0][@"children"][0][@"children"][0][@"cycle"] boolValue]);
+ mode=2;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"status"] isEqual:@"partial"]);assert([r[@"roots"][0][@"children_status"] isEqual:@"unavailable"]);
+ mode=3;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"roots"][0][@"query_errors"] lastObject][@"invalid_type"]);
+ mode=4;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"parent_checks"][@"mismatch"] intValue]==1);
+ assert(![r[@"roots"][0][@"children"][1][@"children"][0][@"cycle"] boolValue]);
+ mode=5;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert([r[@"parent_checks"][@"unavailable"] intValue]==3);
+ mode=6;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,100);
+ assert([r[@"truncation_reasons"] containsObject:@"timeout"]);assert([r[@"queries"] intValue]==1);
+ mode=0;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,1,8,1000);
+ assert([r[@"queries"] intValue]<=8);
+ mode=7;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,2,8,1000);
+ assert([r[@"truncation_reasons"] containsObject:@"max_queries"]);assert([r[@"queries"] intValue]==16);
+ mode=8;calls=0;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert(calls==0);assert([r[@"queries"] intValue]==0);assert([r[@"status"] isEqual:@"partial"]);
+ f.setTimeout=NULL;mode=0;calls=0;r=vp_ax_walk(f,(__bridge CFTypeRef)@"A",42,20,8,1000);
+ assert(calls==0);assert([r[@"queries"] intValue]==0);
+ r=vp_ax_hierarchy(0,20,8,1000);assert([r[@"status"] isEqual:@"unavailable"]);
+ f.setTimeout=timeout;
+ mode=9;r=coldWalk(f,YES,20,1000);
+ receipt(@"recovered-cold-root",r);
+ assert([r[@"count"] intValue]==4); // Cold root must be retried before its children query.
+ assert(rootLabels==2);assert([r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert([r[@"readiness"][@"retry_resolved"] boolValue]);
+ assert([r[@"readiness"][@"initial_query_errors"] count]==1);
+ assert([r[@"readiness"][@"initial_query_errors"][0][@"error_code"] intValue]==-25215);
+ assert([r[@"roots"][0][@"query_errors"] count]==3);
+ assert([r[@"roots"][0][@"children_status"] isEqual:@"complete"]);
+ assert([r[@"status"] isEqual:@"complete"]);
+ assert([r[@"elapsed_ms"] doubleValue]>=390 && [r[@"elapsed_ms"] doubleValue]<1000);
+ assert([r[@"readiness"][@"wait_ms"] doubleValue]>=390 && [r[@"readiness"][@"wait_ms"] doubleValue]<500);
+ assert([r[@"queries"] intValue]==calls && calls==24);
+ mode=9;r=coldWalk(f,NO,20,1000);receipt(@"disabled-retry",r);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert([r[@"roots"][0][@"children_status"] isEqual:@"unavailable"]);
+ assert([r[@"roots"][0][@"query_errors"] count]==5);
+ mode=11;r=coldWalk(f,YES,20,1000);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ mode=0;r=coldWalk(f,YES,20,1000);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ mode=12;r=coldWalk(f,YES,20,1000);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ mode=9;r=coldWalk(f,YES,20,100);receipt(@"insufficient-budget",r);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert([r[@"readiness"][@"wait_ms"] doubleValue]==0);
+ assert([r[@"roots"][0][@"query_errors"] count]==5);
+ mode=13;r=coldWalk(f,YES,20,1000);
+ assert(rootLabels==1);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert([r[@"elapsed_ms"] doubleValue]<1000);
+ mode=10;r=coldWalk(f,YES,20,1000);receipt(@"failed-retry",r);
+ assert(rootLabels==2);assert([r[@"readiness"][@"retry_attempted"] boolValue]);
+ assert(![r[@"readiness"][@"retry_resolved"] boolValue]);
+ assert([r[@"status"] isEqual:@"partial"]);
+ assert([r[@"roots"][0][@"children_status"] isEqual:@"unavailable"]);
+ assert([r[@"roots"][0][@"query_errors"] count]==6);
+ assert([r[@"roots"][0][@"query_errors"] lastObject][@"attribute"]);
+ assert([[r[@"roots"][0][@"query_errors"] lastObject][@"attribute"] intValue]==5001);
+ assert([[r[@"roots"][0][@"query_errors"] lastObject][@"error_code"] intValue]==-25215);
+ mode=14;r=coldWalk(f,YES,2,1000);receipt(@"shared-query-budget",r);
+ assert([r[@"queries"] intValue]==16 && calls==16);
+ assert([r[@"truncation_reasons"] containsObject:@"max_queries"]);
+ mode=15;r=coldWalk(f,YES,20,1000);
+ assert(calls==0);assert(![r[@"readiness"][@"retry_attempted"] boolValue]);
+ mode=17;r=coldWalk(f,YES,20,1000);receipt(@"retry-timeout-configuration-failed",r);
+ assert(calls==1);assert(![r[@"readiness"][@"retry_resolved"] boolValue]);
+ assert([r[@"roots"][0][@"children_status"] isEqual:@"unavailable"]);
+ f.valueTypeID=CFDataGetTypeID;f.getValue=frameValue;
+ mode=18;r=coldWalk(f,YES,20,1000);
+ assert([r[@"roots"][0][@"frame"][@"x"] intValue]==10);
+ assert([r[@"roots"][0][@"frame"][@"height"] intValue]==40);
+ mode=19;r=coldWalk(f,YES,20,1000);assert(r[@"roots"][0][@"frame"]==NSNull.null);
+ mode=20;r=coldWalk(f,YES,20,1000);assert(r[@"roots"][0][@"frame"]==NSNull.null);
+ // An unnamed, offscreen, zero-size structural node must retain its descendants.
+ mode=21;r=coldWalk(f,YES,20,1000);
+ assert([r[@"count"] intValue]==4);assert([r[@"status"] isEqual:@"complete"]);
+ assert([r[@"roots"][0][@"children"] count]==2);
+ NSDictionary *structural=r[@"roots"][0][@"children"][0];
+ assert([structural[@"label"] isEqual:@""]);
+ assert([structural[@"children"] count]==1);
+ assert([structural[@"children_status"] isEqual:@"complete"]);
+ assert(([structural[@"frame"] isEqual:@{@"x":@-250,@"y":@-30,@"width":@0,@"height":@0}]));
+ receipt(@"unnamed-offscreen-structural-node",r);
+ puts("hierarchy tests passed, including cold readiness guards");
+}}
diff --git a/VPhoneDaemon/Tests/run-hierarchy-tests.sh b/VPhoneDaemon/Tests/run-hierarchy-tests.sh
new file mode 100755
index 00000000..46f171ec
--- /dev/null
+++ b/VPhoneDaemon/Tests/run-hierarchy-tests.sh
@@ -0,0 +1,23 @@
+#!/bin/zsh
+set -euo pipefail
+
+daemon="${0:a:h:h}"
+temporary="$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/vphone-hierarchy-tests.XXXXXX")"
+trap '/bin/rm -rf "$temporary"' EXIT
+
+source="$daemon/Native/vphoned_ax_hierarchy.m"
+tests="$daemon/Tests/HierarchyTests.m"
+
+/usr/bin/xcrun --sdk macosx clang -fobjc-arc \
+ -fprofile-instr-generate -fcoverage-mapping \
+ -framework Foundation -framework CoreGraphics \
+ "$tests" "$source" -o "$temporary/hierarchy-tests"
+
+VP_HIERARCHY_RECEIPTS="$temporary" \
+ LLVM_PROFILE_FILE="$temporary/hierarchy.profraw" \
+ "$temporary/hierarchy-tests"
+
+/usr/bin/xcrun llvm-profdata merge -sparse "$temporary/hierarchy.profraw" \
+ -o "$temporary/hierarchy.profdata"
+/usr/bin/xcrun llvm-cov report "$temporary/hierarchy-tests" \
+ -instr-profile="$temporary/hierarchy.profdata" "$source"