setActive

Marks the frame handle refers to as taking part in resolution, or not. An inactive frame keeps its position and its contents but contributes nothing — no screen, no section, no scope — as if it were not on the stack at all. The frames nested under it drop out with it — ambiently always, from an origin unless the frame belongs to the origin's own surface; see recompute and the origin-taking current for the split.

This is the "is this surface the one on display?" bit, and position cannot answer it. Position stands in for recency of becoming foreground, which only holds while a frame leaves when its surface does. A host that keeps several surfaces mounted at once and merely demotes the ones off-screen — a pager caching neighbouring pages, a container that pauses rather than destroys — breaks that: the demoted surface's frame stays where it was, and, being later in the list than the one the user came back to, wins. Removing the frame instead would be wrong for the opposite reason: it must come back, at the same position, without the surface being rebuilt.

A frame is active when pushed. Toggling it does not move it, so a caller may reserve a position once, early, and switch the frame on and off for the life of the surface.

Handles that were already removed, or belong to another stack, are skipped. Passing a value the frame already has is a no-op and republishes nothing.

setActive for several frames at once, publishing one snapshot for the whole batch.

A surface owns more than one frame — its screen, its mask, the scopes under it — and they have to change together. Toggling them one at a time republishes an intermediate context in which some of a surface's frames answer and others do not; a tap captured against that snapshot reads a state the app was never in. Callers that own a surface should switch its frames through this, not in a loop.

No-ops (unknown handles, values already set) drop out; nothing is republished if none remain.

Takes a List rather than the wider Collection it only needs, because this class is exported into the Swift-facing Autograph.xcframework and Kotlin/Native maps only List/Set/Map to an Objective-C collection. A Collection parameter degrades to an untyped id, i.e. Any in Swift — so setActive(handles: "oops", active: false) would compile — and autograph-context is SemVer-ABI-stable (docs/adr/0001-public-api-evolution.md §1), so narrowing it afterwards would need a major bump. Measured in the generated header, both before and after.