@onekeyfe/react-native-native-overlay 3.0.162-alpha.270 → 6.7.0-alpha.335

package/android/build.gradle

@@ -60,6 +60,10 @@ android {
       ]
     }
   }
+
+  testOptions {
+    unitTests.includeAndroidResources = true
+  }
 }
 
 repositories {
@@ -73,6 +77,8 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "com.google.android.material:material:1.14.0-alpha05"
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.robolectric:robolectric:4.17"
 }
 
 react {

package/android/src/main/java/com/onekey/nativeoverlay/NativeOverlayAccessibilityIsolation.kt

@@ -0,0 +1,37 @@
+package com.onekey.nativeoverlay
+
+import android.view.View
+import android.view.ViewGroup
+
+/** Restores the caller's flags when a blocking overlay no longer covers it. */
+internal class NativeOverlayAccessibilityIsolation {
+  private val hidden = mutableMapOf<View, Int>()
+
+  fun update(
+    root: ViewGroup,
+    activeContainer: View?,
+    entriesBelow: List<View>,
+    globalHost: View,
+  ) {
+    val below = mutableSetOf<View>()
+    if (activeContainer != null) {
+      var node: View = activeContainer
+      while (node !== root && node.parent is ViewGroup) {
+        val parent = node.parent as ViewGroup
+        for (index in 0 until parent.childCount) {
+          val sibling = parent.getChildAt(index)
+          if (sibling !== node && sibling !== globalHost) below.add(sibling)
+        }
+        node = parent
+      }
+      if (node === root) below.addAll(entriesBelow) else below.clear()
+    }
+    hidden.keys.filter { it !in below }.forEach { view ->
+      view.importantForAccessibility = hidden.remove(view) ?: View.IMPORTANT_FOR_ACCESSIBILITY_AUTO
+    }
+    below.forEach { view ->
+      if (view !in hidden) hidden[view] = view.importantForAccessibility
+      view.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
+    }
+  }
+}

package/android/src/main/java/com/onekey/nativeoverlay/NativeOverlayHost.kt

@@ -2,7 +2,6 @@ package com.onekey.nativeoverlay
 
 import android.app.Activity
 import android.view.KeyEvent
-import android.view.View
 import android.view.ViewGroup
 import android.view.Window
 import android.widget.FrameLayout
@@ -49,12 +48,12 @@ internal class NativeOverlayHost private constructor(
   )
   private val backCallback = object : OnBackPressedCallback(false) {
     override fun handleOnBackPressed() {
-      topBlockingEntry()?.let { entry ->
+      topBackEntry()?.let { entry ->
         if (entry.dismissOnBackPress) entry.onRequestDismiss?.invoke("back")
       }
     }
   }
-  private val hiddenForAccessibility = mutableMapOf<View, Int>()
+  private val accessibilityIsolation = NativeOverlayAccessibilityIsolation()
 
   init {
     clipChildren = false
@@ -67,7 +66,7 @@ internal class NativeOverlayHost private constructor(
    * predictive back, so the dispatcher alone never runs first.
    */
   fun handleBackKey(event: KeyEvent): Boolean {
-    val entry = topBlockingEntry() ?: return false
+    val entry = topBackEntry() ?: return false
     if (event.action == KeyEvent.ACTION_UP && !event.isCanceled && entry.dismissOnBackPress) {
       entry.onRequestDismiss?.invoke("back")
     }
@@ -109,14 +108,14 @@ internal class NativeOverlayHost private constructor(
   }
 
   fun onEntriesChanged() {
-    val hasBlocking = topBlockingEntry() != null
-    if (hasBlocking && !backCallback.isEnabled) {
+    val hasBackEntry = topBackEntry() != null
+    if (hasBackEntry && !backCallback.isEnabled) {
       // The most recently added callback wins; re-add so ours runs before
       // ReactActivity's and react-native-screens' callbacks.
       backCallback.remove()
       (activity as? ComponentActivity)?.onBackPressedDispatcher?.addCallback(backCallback)
     }
-    backCallback.isEnabled = hasBlocking
+    backCallback.isEnabled = hasBackEntry
     updateAccessibility()
   }
 
@@ -134,35 +133,30 @@ internal class NativeOverlayHost private constructor(
     }
 
   /** Global overlays win; otherwise the topmost visible page overlay. */
-  private fun topBlockingEntry(): NativeOverlayEntryRootView? =
-    orderedEntries().lastOrNull { it.blocking && it.isShownForInput }
-      ?: NativeOverlayPageHostView.allHosts()
-        .filter { it.isAttachedToWindow && it.isShown }
+  private fun topBackEntry(): NativeOverlayEntryRootView? =
+    orderedEntries().lastOrNull { (it.blocking || it.dismissOnBackPress) && it.isShownForInput }
+      ?: shownPageHosts()
         .flatMap { it.shownEntries() }
-        .lastOrNull { it.blocking }
+        .lastOrNull { it.blocking || it.dismissOnBackPress }
+
+  private fun shownPageHosts(): List<NativeOverlayPageHostView> =
+    NativeOverlayPageHostView.allHosts().filter {
+      it.isAttachedToWindow && it.isShown && it.rootView === activity.window.decorView
+    }
 
   /** TalkBack only reads the topmost blocking overlay and what is above it. */
   private fun updateAccessibility() {
     val entries = orderedEntries()
     val topIndex = entries.indexOfLast { it.blocking && it.isShownForInput }
-    val content = parent as? ViewGroup
-    val below = mutableListOf<View>()
+    val content = activity.findViewById<ViewGroup>(android.R.id.content) ?: return
     if (topIndex >= 0) {
-      content?.let { group ->
-        (0 until group.childCount).map(group::getChildAt).filter { it !== this }.forEach(below::add)
-      }
-      below.addAll(entries.subList(0, topIndex))
-    }
-    val restore = hiddenForAccessibility.keys.filter { it !in below }
-    restore.forEach { view ->
-      view.importantForAccessibility = hiddenForAccessibility.remove(view) ?: IMPORTANT_FOR_ACCESSIBILITY_AUTO
-    }
-    below.forEach { view ->
-      if (view !in hiddenForAccessibility) {
-        hiddenForAccessibility[view] = view.importantForAccessibility
-        view.importantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
-      }
+      accessibilityIsolation.update(content, this, entries.take(topIndex), this)
+      return
     }
+    val pageEntry = shownPageHosts().flatMap { it.shownEntries() }.lastOrNull { it.blocking }
+    val pageHost = pageEntry?.parent as? NativeOverlayPageHostView
+    val below = pageHost?.shownEntries()?.takeWhile { it !== pageEntry }.orEmpty()
+    accessibilityIsolation.update(content, pageHost, below, this)
   }
 
   companion object {

package/android/src/main/java/com/onekey/nativeoverlay/NativeOverlayPageHostView.kt

@@ -3,6 +3,7 @@ package com.onekey.nativeoverlay
 import android.annotation.SuppressLint
 import android.content.Context
 import android.view.ViewGroup
+import com.facebook.react.bridge.ReactContext
 import com.facebook.react.uimanager.PointerEvents
 import com.facebook.react.uimanager.ReactPointerEventsView
 import java.lang.ref.WeakReference
@@ -33,6 +34,7 @@ class NativeOverlayPageHostView(context: Context) : ViewGroup(context), ReactPoi
     if (owners == suspendedOwners) return
     suspendedOwners = owners
     entries().forEach(::applySuspension)
+    onEntriesChanged()
   }
 
   internal fun attach(entry: NativeOverlayEntryRootView) {
@@ -44,10 +46,12 @@ class NativeOverlayPageHostView(context: Context) : ViewGroup(context), ReactPoi
     }
     layoutEntries()
     applySuspension(entry)
+    onEntriesChanged()
   }
 
   internal fun detach(entry: NativeOverlayEntryRootView) {
     removeView(entry)
+    onEntriesChanged()
   }
 
   /** Visible, input-ready entries in bottom-to-top order. */
@@ -56,6 +60,23 @@ class NativeOverlayPageHostView(context: Context) : ViewGroup(context), ReactPoi
 
   fun invalidateHost() {
     if (hostKey.isNotEmpty() && registry[hostKey]?.get() === this) registry.remove(hostKey)
+    onEntriesChanged()
+  }
+
+  override fun onAttachedToWindow() {
+    super.onAttachedToWindow()
+    onEntriesChanged()
+  }
+
+  override fun onDetachedFromWindow() {
+    super.onDetachedFromWindow()
+    onEntriesChanged()
+  }
+
+  private fun onEntriesChanged() {
+    (context as? ReactContext)?.currentActivity?.let {
+      NativeOverlayHost.of(it).onEntriesChanged()
+    }
   }
 
   private var layoutScheduled = false

package/android/src/main/java/com/onekey/nativeoverlay/NativeOverlayView.kt

@@ -135,6 +135,7 @@ class NativeOverlayView(
       config = OverlayAnimationConfig.parse(animationConfig)
     }
     entry?.let(::applyEntryConfiguration)
+    notifyHostEntriesChanged()
     if (visible) {
       cycleOpen = true
       if (phase == Phase.HIDDEN || phase == Phase.EXITING) present()
@@ -200,7 +201,7 @@ class NativeOverlayView(
     cancelAnimators()
     phase = Phase.ENTERING
     target.isShownForInput = true
-    host?.onEntriesChanged()
+    notifyHostEntriesChanged()
     if (blocking) {
       target.sendAccessibilityEvent(AccessibilityEvent.TYPE_WINDOW_STATE_CHANGED)
     }
@@ -226,7 +227,7 @@ class NativeOverlayView(
     cancelAnimators()
     phase = Phase.EXITING
     target.isShownForInput = false
-    host?.onEntriesChanged()
+    notifyHostEntriesChanged()
     val transition = config.exit.reduceMotionAdjusted(isReduceMotionEnabled())
     if (transition.kind == "none") return finishDismiss("programmatic")
     animate(target, hiddenState(target, transition), 0f, transition.motion) {
@@ -389,6 +390,10 @@ class NativeOverlayView(
     }
   }
 
+  private fun notifyHostEntriesChanged() {
+    reactContext.currentActivity?.let { NativeOverlayHost.of(it).onEntriesChanged() }
+  }
+
   /**
    * While hidden, keep the React child inside this invisible view. Fabric only
    * reports onLayout for attached views, and fitted sheets size themselves

package/android/src/test/java/com/onekey/nativeoverlay/NativeOverlayAccessibilityIsolationTest.kt

@@ -0,0 +1,112 @@
+package com.onekey.nativeoverlay
+
+import android.view.View
+import android.widget.FrameLayout
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class NativeOverlayAccessibilityIsolationTest {
+  private val context get() = RuntimeEnvironment.getApplication()
+
+  private class Tree(context: android.content.Context) {
+    val root = FrameLayout(context)
+    val reactRoot = FrameLayout(context)
+    val card = FrameLayout(context)
+    val content = View(context).apply { importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES }
+    val chrome = View(context)
+    val pageHost = FrameLayout(context)
+    val lower = View(context)
+    val blocker = View(context)
+    val above = View(context)
+    val globalHost = FrameLayout(context)
+
+    init {
+      root.addView(reactRoot)
+      root.addView(globalHost)
+      reactRoot.addView(card)
+      reactRoot.addView(chrome)
+      card.addView(content)
+      card.addView(pageHost)
+      pageHost.addView(lower)
+      pageHost.addView(blocker)
+      pageHost.addView(above)
+    }
+  }
+
+  @Test
+  fun pageBlockerHidesPageAndNavigationWithoutHidingTheHost() {
+    val tree = Tree(context)
+    val isolation = NativeOverlayAccessibilityIsolation()
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.content.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.chrome.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.pageHost.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.blocker.importantForAccessibility)
+  }
+
+  @Test
+  fun entriesAbovePageBlockerAndGlobalHostStayAccessible() {
+    val tree = Tree(context)
+    NativeOverlayAccessibilityIsolation().update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.lower.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.above.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.globalHost.importantForAccessibility)
+  }
+
+  @Test
+  fun dismissalOrSuspensionRestoresOriginalFlags() {
+    val tree = Tree(context)
+    tree.lower.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+    val isolation = NativeOverlayAccessibilityIsolation()
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    isolation.update(tree.root, null, emptyList(), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_YES, tree.content.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO, tree.lower.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.chrome.importantForAccessibility)
+  }
+
+  @Test
+  fun globalBlockerHidesReactRootThenPageIsolationReturns() {
+    val tree = Tree(context)
+    val globalLower = View(context)
+    tree.globalHost.addView(globalLower)
+    val isolation = NativeOverlayAccessibilityIsolation()
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    isolation.update(tree.root, tree.globalHost, listOf(globalLower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.reactRoot.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, globalLower.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_YES, tree.content.importantForAccessibility)
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.reactRoot.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, globalLower.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.content.importantForAccessibility)
+  }
+
+  @Test
+  fun detachedHostRestoresIsolationInsteadOfHidingAnotherTree() {
+    val tree = Tree(context)
+    val isolation = NativeOverlayAccessibilityIsolation()
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    tree.card.removeView(tree.pageHost)
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_YES, tree.content.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.lower.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.chrome.importantForAccessibility)
+  }
+
+  @Test
+  fun changingTheBlockingEntryRestoresEntriesNoLongerBelowIt() {
+    val tree = Tree(context)
+    val isolation = NativeOverlayAccessibilityIsolation()
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower, tree.blocker), tree.globalHost)
+    isolation.update(tree.root, tree.pageHost, listOf(tree.lower), tree.globalHost)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_AUTO, tree.blocker.importantForAccessibility)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS, tree.lower.importantForAccessibility)
+  }
+}

package/android/src/test/java/com/onekey/nativeoverlay/NativeOverlayBackTest.kt

@@ -0,0 +1,122 @@
+package com.onekey.nativeoverlay
+
+import android.view.KeyEvent
+import android.view.View
+import android.widget.FrameLayout
+import androidx.activity.ComponentActivity
+import com.facebook.react.bridge.BridgeReactContext
+import com.facebook.react.uimanager.ThemedReactContext
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class NativeOverlayBackTest {
+  private lateinit var activity: ComponentActivity
+  private lateinit var context: ThemedReactContext
+  private lateinit var host: NativeOverlayHost
+  private val dismissals = mutableListOf<String>()
+
+  @Before
+  fun setUp() {
+    activity = Robolectric.buildActivity(ComponentActivity::class.java).setup().visible().get()
+    val reactContext = BridgeReactContext(activity)
+    reactContext.onHostResume(activity)
+    context = ThemedReactContext(reactContext, activity, "OverlayBackTest", 1)
+    host = NativeOverlayHost.of(activity)
+  }
+
+  private fun entry(name: String, blocking: Boolean, dismissible: Boolean, order: Int = 0) =
+    NativeOverlayEntryRootView(context).apply {
+      this.blocking = blocking
+      dismissOnBackPress = dismissible
+      stackOrder = order
+      isShownForInput = true
+      onRequestDismiss = { dismissals.add("$name:$it") }
+    }
+
+  private fun back(action: Int = KeyEvent.ACTION_UP, flags: Int = 0) =
+    host.handleBackKey(KeyEvent(0L, 0L, action, KeyEvent.KEYCODE_BACK, 0, 0, 0, 0, flags))
+
+  @Test
+  fun dismissibleNonBlockingGlobalEntryWinsOverLowerBlocker() {
+    host.attach(entry("lower", true, true), NativeOverlayLevel.MODAL)
+    host.attach(entry("top", false, true), NativeOverlayLevel.TOAST)
+    assertTrue(back(KeyEvent.ACTION_DOWN))
+    assertEquals(emptyList<String>(), dismissals)
+    assertTrue(back())
+    assertEquals(listOf("top:back"), dismissals)
+  }
+
+  @Test
+  fun dispatcherHandlesNonBlockingEntryAndKeepsPageAccessible() {
+    val page = View(activity).apply { importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES }
+    activity.setContentView(page)
+    val top = entry("top", false, true)
+    host.attach(top, NativeOverlayLevel.MODAL)
+    activity.onBackPressedDispatcher.onBackPressed()
+    assertEquals(listOf("top:back"), dismissals)
+    assertEquals(View.IMPORTANT_FOR_ACCESSIBILITY_YES, page.importantForAccessibility)
+    host.detach(top)
+    assertFalse(back())
+  }
+
+  @Test
+  fun nonDismissibleBlockerConsumesBackWithoutClosingLowerEntry() {
+    host.attach(entry("lower", false, true), NativeOverlayLevel.MODAL)
+    host.attach(entry("lock", true, false), NativeOverlayLevel.LOCK)
+    assertTrue(back())
+    assertEquals(emptyList<String>(), dismissals)
+  }
+
+  @Test
+  fun passiveOrNotInputReadyEntriesDoNotTakeBack() {
+    host.attach(entry("passive", false, false), NativeOverlayLevel.TOAST)
+    host.attach(entry("hidden", true, true).apply { isShownForInput = false }, NativeOverlayLevel.LOCK)
+    assertFalse(back())
+    assertEquals(emptyList<String>(), dismissals)
+  }
+
+  @Test
+  fun canceledKeyUpDoesNotDismiss() {
+    host.attach(entry("top", false, true), NativeOverlayLevel.MODAL)
+    assertTrue(back(flags = KeyEvent.FLAG_CANCELED))
+    assertEquals(emptyList<String>(), dismissals)
+  }
+
+  @Test
+  fun dismissiblePageEntryWinsOverLowerPageBlockerAndSuspensionSkipsIt() {
+    val pageHost = NativeOverlayPageHostView(context).apply { hostKey = "page-back-test" }
+    activity.setContentView(pageHost)
+    val lower = entry("lower", true, true).apply { ownerKey = "owner" }
+    val top = entry("top", false, true, 1).apply { ownerKey = "owner" }
+    pageHost.attach(lower)
+    pageHost.attach(top)
+    assertTrue(back())
+    assertEquals(listOf("top:back"), dismissals)
+    pageHost.setSuspendedOwners("owner")
+    assertFalse(back())
+    pageHost.invalidateHost()
+  }
+
+  @Test
+  fun globalEntryTakesBackBeforePageEntryAndDismissalRestoresPageTarget() {
+    val pageHost = NativeOverlayPageHostView(context).apply { hostKey = "page-global-test" }
+    activity.setContentView(FrameLayout(activity).apply { addView(pageHost) })
+    pageHost.attach(entry("page", false, true))
+    val global = entry("global", false, true)
+    host.attach(global, NativeOverlayLevel.MODAL)
+    assertTrue(back())
+    host.detach(global)
+    assertTrue(back())
+    assertEquals(listOf("global:back", "page:back"), dismissals)
+    pageHost.invalidateHost()
+  }
+}

package/docs/SPEC.md

@@ -35,12 +35,13 @@ retains its original implementation attribution in source comments.
 
 ### Release boundary
 
-This branch aligns all 42 publishable workspaces to `3.0.162-alpha.270`.
-Publish with the existing `package-publish` workflow dispatch, `npm_dist_tag=next`
-and an empty `only_workspace`, which publishes and registry-verifies all 42.
-Do not merge either repository PR or change the `latest` tag. The app-monorepo
-workspace copy is removed only after this release succeeds and every target
-version and tarball is available. Versions already published on npm are immutable.
+The earlier `3.0.162-alpha.272` release remains immutable. This branch now
+includes the current main SDK baseline, with all publishable workspaces aligned
+before release. Use `package-publish` with `npm_dist_tag=next` and an empty
+`only_workspace` to generate a fresh `6.7.0-alpha.N` preview, publish every
+workspace, and verify every registry version. Preserve `latest` and keep both
+repository PRs open. App consumers pin the verified exact preview version and
+refresh dependency and native locks before installed-version acceptance.
 
 ## 5.1 Purpose, scope, and non-goals
 
@@ -136,6 +137,11 @@ visible)`, `removePage(ownerKey)`.
 
 - `usePageOverlayHost()` resolves `hostKey` and `ownerKey` from navigation
   context.
+- A declarative page overlay keeps `scope: 'page'` while either key is
+  unavailable. It does not request or present an entry until both keys are
+  available; becoming ready while visible requests it in the page lane.
+  Hiding or unmounting before readiness creates no entry or close callback.
+  Direct store requests still throw for missing page keys.
 - `useInPageDialog`, `useInModalDialog`, and `useInTabDialog` become aliases of
   page scope. Tab scope is removed.
 
@@ -208,6 +214,30 @@ request ─► queued ─► active ─► (enter anim) presented
 - Threads: store mutations happen on the JS thread. Native animation and layout
   run on the UI thread. Events are delivered as direct events.
 
+### Web presentation updates (OK-50653)
+
+For an open Web overlay that keeps its portal host, changing `presentation`
+between sheet and a non-sheet frame MUST preserve the mounted content subtree.
+Its props and React context continue to update normally. Changing the optional
+sheet handle MUST NOT move the content into a different React child slot.
+Closing without `keepContentMounted` still unmounts content after exit; reopening
+creates a fresh content lifecycle. Business entity changes and draft resets
+remain caller-owned; the overlay does not cache or persist form values.
+
+The stable sheet shell must not change non-sheet animation origins or keyboard
+avoidance geometry. Switching away from a sheet clears any pan offset and its
+backdrop opacity override, and releases an active pointer capture.
+
+Conformance: `src/__tests__/draftRetention.web.test.ts` exercises the real Web
+host, portal and store for presentation changes, live props/context/callbacks,
+close/reopen, animation origins, keyboard geometry and an interrupted pan.
+Chrome extension side-panel and ordinary-tab checks use synthetic content;
+this correction does not claim new iOS/Android runtime verification.
+
+These source changes require a new published package version before the app
+can consume them from npm. This fix leaves package versions and lockfiles at
+their existing values and does not publish a release.
+
 ## 5.5 Data, cache, and identity
 
 - Identity is the entry `id`: caller-provided, otherwise `overlay-<seq>`.
@@ -216,6 +246,17 @@ request ─► queued ─► active ─► (enter anim) presented
 
 ## 5.6 Platform contract
 
+### Web keyboard focus containment
+
+The topmost active, unsuspended blocking Web entry MUST contain sequential
+keyboard focus. Tab from its last tabbable child wraps to the first;
+Shift+Tab from its first wraps to the last. From the entry root, focus enters
+the first/last child respectively. With no tabbable children, focus stays on
+the entry root. Disabled, negative-tabindex, hidden and inert subtrees are
+excluded. Positive tabindex values precede ordinary DOM-order tab stops.
+Non-blocking, lower, closing, suspended and parked entries MUST NOT run a
+focus loop. Existing focus entry/restore and Escape policies are unchanged.
+
 | Concern                                    | iOS                                                                                                                                                          | Android                                                                                                                                                                                                                                                                                                                                                                                                                 | Web                                                                                                                 |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | Global level host                          | One passthrough `UIWindow` per active level per `UIWindowScene`, ordered by `windowLevel`. `lock` sits above RN Alert (2001).                                | One `OverlayHost` FrameLayout in `android.R.id.content` above the ReactRootView, with one child container per level.                                                                                                                                                                                                                                                                                                    | Sibling `div[data-onekey-layer]` roots under `body`, one z-index band per level (`OVERLAY_WEB_Z_INDEX_BASE`).       |
@@ -224,7 +265,7 @@ request ─► queued ─► active ─► (enter anim) presented
 | Page host                                  | Fabric `PageOverlayHost` as the last child of the root-route screen. Custom-drawn sheet, because UIKit sheets cannot be page-scoped.                         | The same host inside the root-route screen. The ReactRootView already dispatches touches, so no nested RootView.                                                                                                                                                                                                                                                                                                        | `position: absolute` host inside the root-route card.                                                               |
 | Header / tab bar coverage (page)           | Covered: the host is above the tab controller and navigation bars.                                                                                           | Covered.                                                                                                                                                                                                                                                                                                                                                                                                                | Covered.                                                                                                            |
 | Touch passthrough (toast, debug, box-none) | `hitTest` returns nil on the window or root view.                                                                                                            | A non-blocking entry hit-tests its React content with `TouchTargetHelper` (honoring `box-none`) and falls through to the FrameLayout sibling on a miss.                                                                                                                                                                                                                                                                 | `pointer-events: none` root, `auto` per entry.                                                                      |
-| Back / Escape                              | Escape via `accessibilityPerformEscape`. The interactive pop gesture is disabled while a blocking page overlay is shown.                                     | A `Window.Callback` wrapper consumes `KEYCODE_BACK` while a blocking overlay is shown. `ReactActivity.onBackPressed` hands back to JS BackHandler (react-navigation) before the `OnBackPressedDispatcher`, and the app opts out of predictive back, so a dispatcher callback alone never runs first. The dispatcher callback is kept for the predictive-back path. The IME still gets back first to close the keyboard. | Capture-phase `keydown` that ignores IME composition.                                                               |
+| Back / Escape                              | Escape via `accessibilityPerformEscape`. The interactive pop gesture is disabled while a blocking page overlay is shown.                                     | A `Window.Callback` wrapper consumes `KEYCODE_BACK` for the topmost input-ready blocking or dismissible overlay. `ReactActivity.onBackPressed` hands back to JS BackHandler (react-navigation) before the `OnBackPressedDispatcher`, and the app opts out of predictive back, so a dispatcher callback alone never runs first. The dispatcher callback is kept for the predictive-back path. The IME still gets back first to close the keyboard. | Capture-phase `keydown` that ignores IME composition.                                                               |
 | Modality / accessibility                   | `accessibilityViewIsModal` on the blocking level window; `.screenChanged` posted on present.                                                                 | `IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS` on the content below.                                                                                                                                                                                                                                                                                                                                                 | `inert` on the app root and lower layers, `role=dialog`, `aria-modal`, focus trap and restore.                      |
 | Keyboard                                   | System sheet avoidance; `keyboardLayoutGuide` for custom presentations. The main window regains key status on dismiss.                                       | `WindowInsetsAnimationCompat` per sheet (the app uses `adjustPan`).                                                                                                                                                                                                                                                                                                                                                     | `visualViewport`.                                                                                                   |
 | Animation engine                           | `UIViewPropertyAnimator` + `UISpringTimingParameters(mass:stiffness:damping:)`, which maps 1:1 and supports damping ratio > 1.                               | `SpringAnimation` with `stiffness = k/m` and `dampingRatio`; `PathInterpolator` for timing curves.                                                                                                                                                                                                                                                                                                                      | WAAPI `element.animate`. Timing presets use `cubic-bezier`; custom springs use `linear()`.                          |
@@ -273,10 +314,47 @@ Known divergences:
   such as the DatePicker month-row interpolation, are clipped inside the
   content.
 
+### Page interaction and accessibility isolation (review correction)
+
+The existing ordering and suspension contract also applies when a page entry
+mounts after its owner was suspended. Such entries MUST remain hidden and inert
+until that owner resumes. Resuming an owner MUST NOT clear isolation imposed by
+a higher blocking entry. Web page isolation compares level first, then request
+order within that level; dismissal restores entries no longer below a blocker.
+
+On Android, a blocking page entry MUST hide underlying page/navigation siblings
+from accessibility while preserving the page host and the blocking entry. Entries
+above it, including non-blocking global overlays, remain accessible. Global
+blockers still win over page entries. Attachment, detachment, suspension,
+resumption, input-readiness and blocking changes MUST refresh isolation and
+restore each view's original accessibility flag when it is no longer covered.
+
+These are corrections within the existing contract, not new public props. DOM
+and Robolectric tests will verify lifecycle and native flags; manual TalkBack
+navigation remains a separate runtime acceptance item.
+
 ## 5.9 Conformance and acceptance
 
 Automated (P0):
 
+- `src/__tests__/focusTrap.web.test.ts` mounts real Web overlays and checks
+  both Tab boundaries, root/empty fallback, inaccessible children, positive
+  tabindex order, top-entry precedence, page scope, suspension and parking.
+- `src/__tests__/useOverlayController.test.ts` exercises the actual hook and
+  page scope providers: missing/empty keys, delayed readiness, one request,
+  page suspension/removal, hiding/unmounting before readiness and global scope.
+- `NativeOverlayBackTest` exercises the Android host's key interceptor and
+  Back dispatcher with actual entry/page views: dismissible non-blockers,
+  blockers, input readiness, canceled key-up, global/page precedence,
+  suspension and blocking-only accessibility isolation.
+- `src/__tests__/pageIsolation.web.test.ts` mounts a real React portal in a
+  DOM host and verifies late suspension, level ordering and restoration after
+  the blocking entry is removed.
+- `NativeOverlayAccessibilityIsolationTest` runs six Robolectric cases against
+  Android views: page/navigation siblings, entries above the blocker, original
+  flags, global/page transitions, detached hosts and changing blockers. These
+  tests do not replace manual TalkBack navigation.
+
 - `src/__tests__/OverlayStore.test.ts` covers:
   - level ordering regardless of request order;
   - page below global;
@@ -304,7 +382,10 @@ Runtime matrix, required per platform before migrating callers (P1–P3):
    - switch tab and come back: it restores;
    - remove the page: it closes with `page-removed`;
    - the native header and tab bar are covered.
-5. Back/Escape reaches the topmost blocking overlay; the lock swallows it.
+5. Back/Escape reaches the topmost input-ready overlay that is blocking or
+   explicitly dismissible, global before page. A non-dismissible blocker
+   consumes Back without closing; a passive non-blocking entry passes through.
+   Accessibility isolation remains blocking-only. The lock swallows Back.
 6. Keyboard: an input in a global sheet, a page sheet and a secure dialog.
 7. iOS: a system picker opened from an overlay appears above it.
 8. Split view: page overlays stay in their own pane.
@@ -335,8 +416,8 @@ P3 page scope notes:
   their global sheet implementation inside the page host.
 - Android back also resolves page entries: global overlays first, then the
   topmost visible page overlay.
-- A page request without a resolvable host or owner falls back to global
-  scope.
+- A declarative page overlay waits for a resolvable host and owner; it never
+  falls back to global scope. Direct store requests require both keys.
 
 P2 sheet notes: