feat(android): prototype Frame-owned interactive back previews - #11558

PR Checklist

• Conventional PR title.
• Proposal tracked in Proposal: Frame-owned Android interactive back previews without changing native history #11557; public API is experimental and offered for review.
• CLA signed.
• Core unit tests pass: 540 passed, one existing skip; Core build passes.
• Tests included: unit session lifetime tests, native Frame ownership/recreation tests and a standalone toolbox example.

What is the current behavior?

Frame exposes final Back but no presentation-only interactive preview. External routers currently reparent a retained Page during Android back progress. Frame's logical history is separate from FragmentManager's back stack, so enabling FragmentManager predictive pop is not a compatible one-line change.

Native acceptance also exposed a pre-existing recreation failure: the new root view can attach while its owning Activity is INITIALIZED. Frame ignores that attach, never marks itself attached after CREATED, and subsequent navigation remains queued. A plain NativeScript reproduction fails with published Core 9.1.3 on API 35.

What is the new behavior?

Experimental Frame.beginBackPreview() creates a version-1 snapshot session on Android 14+. Progress/cancel/finish only change presentation; the caller retains gesture dispatch, guards and the final navigation decision. Frame automatically disposes the session when navigation, unload, detach or native disposal takes over. iOS returns undefined.

The previous Page is software-drawn into a bounded, accessibility-hidden Android ImageView and stays detached/unloaded. Secure windows, SurfaceView/TextureView content, custom/shared transitions, unavailable geometry and failed capture decline the session. This is intentionally opt-in: capture costs time and memory, previews are static, and no performance improvement or universal content compatibility is claimed.

The first commit independently fixes early attachment by using the owning Activity and rechecking an already-attached native view when the Frame loads. It is separable from the prototype.

Implements the prototype proposed in #11557. Related consumer investigation: rafaelaugustos/vue-router-ns#62.

Native validation

Candidate built from upstream main 3224f1b, with stock Android runtime 9.1.1 / native Core resources; the demo aliases this compiled Core rather than modifying installed packages. API 34/35/36 ARM64 emulators passed:

• Real Android system gestures for cancellation and completion; previous Page remains detached in the candidate, and FragmentManager back-stack count remains zero.
• Global guard refusal, active leave-guard suppression, custom-transition fallback, modal inner Back/results, replace/clearHistory, and interruption by a new navigation.
• Eight repeated snapshot cycles; all tracked Android Bitmaps collected through native WeakReference/ReferenceQueue after three fixed JS/native GC rounds.
• Actual same-process Activity.recreate() with both legacy and candidate previews: old session disposed, Page identities/draft retained, and Back works after recreation. The unmodified published Core negative control reproduces the queued-Back failure on API 35.

The router fixture records lifecycle traces, capture allocation/time, screenshots during native input, and process/Activity identities. The full automated Core device app was not run as a whole; the standalone native reproduction exercised the added regression behavior directly. Physical-device performance, arbitrary vendor SDK rendering, and TalkBack speech are not claimed.

See tools/notes/FrameBackPreview.md for the API, native example and limitations. The consumer continues shipping its existing preview by default.