PoC: pre-warm visibility cache + diagnostic logging

[Elton Carreiro (EltonCarreiro)]

Summary

/source XML generation pays a synchronous AX-framework IPC per element when computing the visible attribute. fb_isVisible (XCUIElement+FBIsVisible.m) resolves visibility through three paths:

• Cached lookup — read additionalAttributes[FB_XCAXAIsVisibleAttribute] from the snapshot.
• Descendant-cache shortcut — fb_hasVisibleDescendants walks _allDescendants; if any descendant is already cached as visible, returns YES without an AX call.
• AX-framework IPC — synchronous XCAXClient.attributesForElement:attributes:. The expensive one.

Today nothing pre-populates the cache before XML generation, so the cached lookup always misses on a fresh snapshot. The descendant shortcut also misses because none of the descendants are cached either — every node falls through to the AX IPC.

This PR adds an opt-in pre-warm pass that resolves visibility on the leaves of the snapshot tree before XML generation. Internal nodes then benefit from the descendant shortcut during XML generation (their _allDescendants walk finds at least one cached-visible leaf and short-circuits), skipping their own AX IPC.

Changes

• FBXMLGenerationOptions: new tri-state warmVisibilityCache: NSNumber? property + withWarmVisibilityCache: builder.
• FBDebugCommands.handleGetSourceCommand: parses ?warm_visibility_cache=true|1|yes (case-insensitive truthy), threads through FBXMLGenerationOptions.
• FBXPath.xmlStringWithRootElement:options:: when the flag is truthy, calls the new private +warmVisibilityCacheForSnapshot: which recurses to leaves and resolves wdVisible on each. Logs [VisCache] (FBXPath) Warmed visibility cache in N.NNNs.
• XCUIElement+FBIsVisible.fb_hasVisibleDescendants: instrumented with process-wide _Atomic counters; logs hit-rate stats every 50 calls. Always-on — runs regardless of the warming flag, so cold and warmed runs are both measurable.

Why leaves-only

The descendant shortcut looks for any cached-visible descendant, not specifically a child or a leaf. Warming leaves alone guarantees every internal node with at least one visible leaf in its subtree will short-circuit. AX-IPC cost is unchanged (same nodes still pay it: only those whose entire subtree is invisible), but we avoid one full O(n²) _allDescendants sweep that warming internal nodes would cost.

How to validate

1. Build/install on a runner.
2. Baseline: GET /source with no querystring. Tail logs for the stats line — expect near-0% hit rate.
3. Warmed: GET /source?warm_visibility_cache=true. Confirm [VisCache] (FBXPath) Warmed… appears, then watch hit rate climb on subsequent stats logs.
4. Eyeball drop in count of ! Fetching of XC_kAXXCAttributeIsVisible took N.NNs warnings per request.

Note on terminology

The code/comments shipped in this PR still carry some internal shorthand from the design discussion ("Tier B short-circuit", [VisCache] Tier-B stats: log prefix). That phrasing isn't meaningful outside the design conversation and will be cleaned up before this lands; please mentally substitute "descendant-cache shortcut" wherever you see it.

Out of scope (deferred)

• Session-wide FBConfiguration.warmVisibilityCacheInPageSource flag — promote only if results justify.
• QAWXML batched-page-source path coverage — needs Swift wrapper plumbing in ios-agent.
• Bulk-prefetch via XCAXClient's attributes: (collapses N IPCs into 1).
• Client-side on-demand visibility in the chooser.

🤖 Generated with Claude Code