deepestAccessibilityHitPath

fun deepestAccessibilityHitPath(node: Any, view: UIView, positionInWindowPx: AxPoint, scale: Float, preferClickableBranches: Boolean = true, allowScopeContainerDescent: Boolean = false): List<Any>?

Returns the path from node down to the deepest descendant whose accessibility frame contains positionInWindowPx, or null when nothing in the tree does.

The full root-to-leaf path is returned, not just the leaf, so callers can inspect ancestry — pick the nearest clickable ancestor of the hit node, or detect that the path crosses a view owned by another capture pipeline.

The starting node is not a filter. Containment gates the descent at every node except node itself: node is the caller's choice of where to search, and its own frame says nothing about where its descendants are. This is not a hypothetical distinction — it is the difference between working and reporting nothing at all: in a process no accessibility client has touched, the view autograph-compose starts from (Compose Multiplatform's OverlayInputView, via LocalUIView.current) reports an empty accessibilityFrame while every bridged element beneath it is already correct, and gating on it dropped every Compose tap for the life of the process. XCUITest cannot catch this: its runner is itself an accessibility client and warms the state away (#135; design notes).

The exemption does not rescue a UIKit/SwiftUI walk in that state: cold, UIKit and SwiftUI have built no accessibility tree at all, so every child prunes on its own empty frame. That is why the native pipeline resolves through hitTest instead — see installAutographNativeTapCapture.

What the exemption does not loosen. Two properties are preserved deliberately, because relaxing the descent could otherwise turn a dropped event into a misattributed one — the worse failure:

  • A node that does not contain the position is never returned alone; only as an ancestor of a descendant that does. Every other element on a returned path contains the position.

  • A node that is itself clickable keeps its gate, so it is never on a path it doesn't contain. It stays visible to ancestry checks on the paths it does contain, and there is no way to hold it in the path for those while withholding it from nearestAccessibilityClickable, which knows no geometry. Measured: without that clause a clickable starting node whose frame missed the tap was attributed the tap whenever any inert child contained it.

One consequence is genuinely new: a tap outside node's own frame can now resolve, where it previously always dropped. The one shipped caller passes the Compose host's overlay view, which contains every tap it is asked about, so this widens where the walk's documented overlap ambiguity below can be reached without changing which element any current tap names.

Overlap tie-break, and its limits. Children are searched in reverse order, so among subviews a later sibling — the one drawn on top — wins an overlap. That is a true z-order tie-break only for subviews, and it fails in two measured ways.

Across groups: accessibilityChildren returns accessibilityElements + subviews, a concatenation whose across-group order has no relation to what is drawn on top, and reversing it searches every subview before every accessibility element. So a node that exposes an on-top overlay through accessibilityElements while the covered content is a plain subview resolves a tap to the covered subview instead of the overlay.

Within accessibilityElements: the order there is whatever the element's provider chose, and nothing obliges a provider to choose z-order — Compose Multiplatform's bridge measurably does not. So among overlapping siblings that tie on clickability, reversing that order can name the element underneath rather than the one that received the tap: a misattribution, not a drop.

  • Compose Multiplatform narrows it: the bridge trims a covered sibling's accessibilityFrame wherever the remainder is still a rectangle, which settles the overlap before this tie-break is consulted. What is left is an untrimmable overlap (a corner, or an occluder sitting entirely inside) whose on-top element the bridge emits earlier — measured for an overhang straight up.

  • UIKit / SwiftUI: no trim was observed in the one trimmable geometry measured (SwiftUI; no UIKit hierarchy was run), so there the tie-break was left to decide an overlap Compose settles. One geometry is not a sweep. Since #191 the native pipeline does not use this walk; the Compose one still reaches native nodes through UIKit interop hosted inside a composition, and any other caller walking a native tree may meet the same gap.

Documented rather than fixed: the obvious rankings (smallest area, first emitted) each scored worse than this one against the recorded fixtures, and the bridged elements have no backing views to read a draw order from. Do not swap the tie-break without scoring it against those fixtures (#140; design notes).

Clickable branches win over the tie-break. Before z-order is consulted at all, a branch that yields a clickable (isAccessibilityButton) is preferred over one that yields none; the reverse order above decides only among branches that tie on that. Without this the walk commits to the first branch geometrically containing the point and never reconsiders, so a single empty view covering the content swallows every tap. That is not hypothetical — measured on a real SwiftUI List, where a full-screen _UITouchPassthroughView sits on top of the cells and, as its name says, passes touches straight through to them. UIKit's own hitTest gets this right because such views decline the hit; the accessibility tree carries no equivalent signal, so "did this branch lead anywhere a tap can be attributed to" is the closest available stand-in.

The trade this accepts: an opaque non-interactive overlay that genuinely does block touches — a modal scrim over a button, say — is likewise invisible to this walk, and a tap on it now resolves to the button beneath instead of to nothing. Both directions are wrong for some tree; this one is wrong for the rarer one, and it fails toward reporting an event rather than toward the pipeline being silently inert on every SwiftUI screen built out of List.

Note this is decided per branch, not globally: a subtree with no clickable anywhere still resolves exactly as before, so callers that don't care about clickability see no change.

preferClickableBranches turns the preference off, restoring the plain topmost-branch descent. That is not a compatibility shim: the preference answers "which element should this tap be attributed to", and a caller asking "where did this tap visually land" needs the other answer. The removed native resolver needed both — it decided Compose ownership from the topmost path, because a preference for clickables would otherwise route the path around a Compose host and let the native pipeline claim a tap that landed on Compose-owned content — and resolved the target from the preferred one. Conflating the two is exactly the bug that motivated splitting them.

view supplies the coordinate space and scale the point-to-pixel ratio — both are handed to accessibilityBoundsInWindowPx unchanged, so its precondition on scale applies here too.

Threading. Main thread only: every property this reads (accessibilityChildren, accessibilityFrame, subviews) is main-thread-only UIKit API.

Termination. The tree this walks is supplied by the host app, not by this module, and nothing in the UIAccessibility contract forbids an element from listing an ancestor among its accessibilityElements. Such a link makes the graph cyclic, and a naive descent would recurse until the stack overflows. Three bounds prevent that: a branch that revisits a node already on the path being built is abandoned (the parent then tries its next sibling), descent stops at MAX_ACCESSIBILITY_TREE_DEPTH, and the walk as a whole stops after MAX_ACCESSIBILITY_NODE_VISITS nodes. The last is what bounds breadth rather than depth, and it is load-bearing precisely because of the clickable preference above: exploring every branch of a clickable-free subtree compounds per level whenever a node is reachable by more than one route. All three degrade to resolving a shallower element rather than crashing — a missed leaf is a dropped event, an overflow or a multi-second walk on the main thread is a wedged app.

allowScopeContainerDescent is off by default, and only the Compose pipeline turns it on. It exempts an Autograph scope container (AUTOGRAPH_SCOPE_IDENTIFIER_PREFIX) from the containment gate, so a clickable drawn outside its scope wrapper still resolves. Confining it to the Compose adapter is what keeps two other properties intact by construction rather than by argument:

  • The ownership boundary. Both pipelines drop a tap whose path crosses a Compose host, which is how they avoid reporting the same tap twice. Historical, and stated because the shape of the argument still applies: until #191 the native pipeline arbitrated that boundary through this very walk, over the whole window — so a branch that no longer pruned on containment could resolve before the branch through the host, neither returned path would cross it, and a Compose-owned tap could be reported natively. Since #191 the native pipeline asks the question of the UIView.hitTest chain instead (see NativeHitTestResolution.kt) and does not use this walk at all, so that particular route is closed — but the marker is still an identifier the host app is free to write, so it still cannot be treated as proof of who owns a subtree, and the exemption still must not escape the Compose adapter. The Compose walk starts at the Compose host, so it stays inside one composition's subtree and never reaches a sibling of that host. Note what that does not say: accessibilityChildren unions accessibilityElements with subviews, so the walk does descend into UIKit interop (UIKitView/UIKitViewController) subtrees hosted inside the composition, and those are not Compose-owned. The exemption can therefore apply to a foreign node — bounded, since the reported clickable must still contain the tap and the native pipeline still drops any path crossing this host, but it is a bound rather than the absence of a case. An earlier draft of this note claimed everything reachable here is Compose-owned; it is not.

  • The visit budget. A non-containing branch that used to cost one visit can expose a whole subtree instead. Confined to the Compose walk that subtree is the composition's own; opened on the native walk it is the entire window, twice per tap.