pushSurface

fun pushSurface(scope: Map<String, JsonElement> = EmptyJsonObject, screen: String? = null, section: String? = null, parent: ScopeHandle? = null): ScopeHandle

push for a frame that is also an attribution boundary: the pipeline pushing it can tell, for every event it captures, whether the event happened inside this frame, and resolves such events through current with the frame — or one beneath it — as the event's origin.

A boundary changes what an origin-based resolution sees, in both directions. What is declared beneath a boundary is visible only to events whose origin is at or beneath it, never to an event resolved from outside: a native surface's frame is a boundary, so the screen a fragment names, or the mask an unnamed one raises, reaches the taps that land in that fragment and not the taps on the surface hosting it beside it. And a boundary is where the descent of current stops: an event whose origin is a surface does not pick up the declarations of the surfaces nested inside it, because its pipeline has already established the event is not in them. See current for the exact rule.

Which frames should be boundaries follows from that: those a pipeline can localize an event to and that stand for a surface of their own. Every surface a native capture reserves a frame for is one (an Activity, a fragment). The root frame a Compose provider pushes for its composition is deliberately not, although the observer can localize a tap to it: a composition is how the surface hosting it declares its screen, not a surface of its own, so a native tap on a toolbar beside the ComposeView must still see the TrackedScreen inside it. A plain push is the right call for any declaration that is not a surface — and a frame under no boundary at all applies to every event, whatever its origin (see current) (#216; design notes).

Being a boundary is static for the life of the frame; update revises the contents and reparent the parent link, never the kind.