ScopeStack
The ambient scope + screen context of the currently visible UI, as a stack of pushed frames.
This is the non-Compose home for what AutographScope and screen context express inside Compose via CompositionLocal: a place that autocapture pipelines can read at the moment a tap or screen view is observed, regardless of which UI framework produced it (Compose, UIKit/SwiftUI, or the Android View system). Each surface pushes a frame when a screen or scope comes into view and removes it when it leaves; the capture pipeline calls current and AmbientContext.enrich to attribute the event.
Read this only from auto-capture code, not from explicit track calls. The stack answers "what was on screen when the user acted", which is the right question for an autocaptured tap but the wrong one for an arbitrary track(...) — a background event (e.g. a network response that completes after navigation) must not silently inherit whatever screen happens to be visible. Explicit instrumentation keeps its own lexical scope; see the autograph-compose decorator.
Own an instance; don't share one globally. Scope a ScopeStack to the tracker it feeds so context can't leak across trackers or outlive a tracker swap on logout — screenHistory rides along and inherits that scoping, which is what resets previous_screen when the tracker is replaced. Sharing one instance across the surfaces of a single hybrid app is the exception, and the point: pass it to AutographProvider so the Compose and native pipelines attribute against the same context and share one previous_screen chain. That stack is then yours to replace when the tracker is — the provider will not swap a caller-supplied stack out from under the native side.
Threading. push, pushSurface, update, reparent, remove, setScreenMasked, setActive and the origin-taking current must be called from the main thread (push, pushSurface and remove mutate the frame list; the others mutate a frame's contents and republish the snapshot, or read the list as it stands). The no-argument current is lock-free and safe from any thread: it returns an immutable snapshot that is republished atomically on every mutation, so a background reader always sees a whole, consistent context — never a half-applied one. The unit is the call: a change that takes two calls publishes the snapshot in between (see setScreenMasked and reparent).
Properties
The screen history that travels with this stack.
Produces the AmbientContext.screenViewId of each Screen Viewed that Autograph's screen tracking emits through this stack (#242): the native screen captures and autograph-compose's screen trackers alike. Called on the main thread, once per screen view; an id it fails to produce (it throws, or returns an empty string) leaves that visit without one rather than failing the screen view.
Functions
Puts handle's frame in the visit screenViewId of screen (#242) without starting a new one and without a Screen Viewed — for a surface re-created into a view that is already in progress, such as an Android Activity or fragment after a configuration change, so the events after it stay in the visit before it. As for any visit, the stack reports it only while the frame names screen. A no-op when the frame is not on this stack. Main thread only.
The current merged ambient context, over every frame on the stack. Lock-free; safe from any thread.
Records name as the current screen and emits a Screen Viewed for it, carrying the screen it replaced as previous_screen. The one place that couples recording with emitting, so every native screen-capture caller — the iOS UIKit swizzle, the iOS explicit SwiftUI path, and the Android Activity/Fragment lifecycle capture — cannot drift on the order or on the self-previous guard.
Ends the visit handle's frame is in (#242), for a native screen capture whose surface stops being viewed while its frame stays: the next view of it starts a new visit, and until then a tap resolved from the frame must carry no visit id rather than the finished one's. A no-op when the frame holds none. Main thread only.
Pushes a frame contributing scope properties (low precedence — an explicit call-site property always wins over them) and/or a screen/section (reserved keys, high precedence). Returns a ScopeHandle to update or remove it with. A frame may carry scope only (an AutographScope analogue), screen only (a TrackedScreen analogue), or both.
Removes the frame handle refers to, by identity and independent of position — screen transitions (a Compose Crossfade, an iOS interactive-pop that the user cancels) do not guarantee frames leave in push order, so a positional pop would remove the wrong one. Removing a handle that was already removed, or one from another stack, is a no-op.
Moves the frame handle refers to under parent — or makes it a root, for null — in place, keeping its position, its contents and its switches. For a caller whose frame has moved but whose declaration has not: a composition relinked under the surface now hosting it, a surface adopted after its content was pushed, a movableContentOf subtree relocated under a different parent. Re-pushing instead would change the frame's identity and orphan any frames still pointing to it as their parent. See resolveScope for how the link is used.
The id of the visit handle's frame holds (#242), whether or not the stack reports it right now, or null when it holds none or is not on this stack — for a native screen capture that carries one view of a screen over to the frame of the surface re-creating it (see continueScreenVisit). Main thread only.
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.
setActive for several frames at once, publishing one snapshot for the whole batch.
Starts a new visit of screen on handle's frame (#242) and returns its id, or null when the generator fails or the frame is not on this stack — for an emit site outside this module that builds its own Screen Viewed, as autograph-compose's screen trackers do. Put the returned id on that screen view directly rather than reading it back from the stack; emitScreenView is this plus the emit.
Replaces the contents of the frame handle refers to, in place — keeping its position, and thus its precedence, in the stack. Use this instead of remove + push when a still-mounted frame's scope/screen/section changes: re-pushing would move the frame to the top and let it wrongly override inner frames that are still on the stack. A no-op (and no snapshot churn) if the contents are unchanged, the handle was already removed, or it belongs to another stack.