feat: restore focus when covered overlay content is uncovered - #9

Retry initial focus after force-clearing a captured child

When the covered descendant has captured focus, the covering overlay's earlier requestFocus() is rejected because captured focus declines requests from other components (Compose FocusRequester documentation). This forced clear then removes the descendant's focus, but nothing reschedules the covering sibling's initial-focus request, leaving the window with no focused overlay until another state transition occurs. Retry the covering overlay's request after this clear or perform the forced clear before its initial request.

Useful? React with 👍 / 👎.

🤖 Fixed in 81dcb83. When a covered layer force-clears focus, it now increments a per-window snapshot counter. overlayFocusTarget observes the counter and requests focus again if it still wants initial focus, does not have focus, and is not inside a covered layer. The overlay is therefore focused after the clear, whichever order the request and the clear ran in. coveringOverlayTakesFocusOnceCoveredContentReleasesCapturedFocus captures the editor, then covers it with the coverage read during composition, so the initial request runs first and is declined. It fails on 28e8f09 and passes on 81dcb83.

🤖 [P2] Explicitly order clearing and restoration after changes apply

A plain coroutineScope.launch does not guarantee execution after the recomposition frame. With overlayFocusLayer { isCovered.value }, the snapshot observer can launch this clear before embedded Views apply their updates; the launch in uncover() can similarly attempt restoration before the covering overlay is detached. Compose 1.12.1's Android dispatcher runs queued coroutine work before frame callbacks. The new embeddedViewKeepsFocusWhileCoverIsApplied test captures isCoveredNow during composition, so it does not exercise the direct snapshot-reading path.

Could we explicitly order these operations after the relevant changes apply and add coverage using overlayFocusLayer { isCovered.value }, checking both View focus during cover application and restoration after overlay removal?

Android dispatcher implementation

🤖 Fixed in 81dcb83. Clearing and restoring now wait for withFrameNanos {} before they run. Recomposition and apply happen inside the same frame callback after sendFrame, and the continuation is dispatched, so it runs after that frame applies its changes. That holds on AndroidUiDispatcher and under the test clock (FrameDeferringContinuationInterceptor). A change observed between frames therefore waits for the frame that applies it. If the change is applied during a frame, the work waits one more frame. I added two tests that use overlayFocusLayer { showOverlay.value }:

• embeddedViewKeepsFocusWhileSnapshotCoverageIsApplied: the embedded EditText still has focus in an AndroidView update during the frame that applies the coverage, and has lost focus once the overlay is focused.
• snapshotCoverageRestoresFocusAfterCoveringOverlayIsRemoved: the editor is refocused, and its focus gain is recorded after the overlay's DisposableEffect has disposed.

Both fail on 28e8f09 and pass on 81dcb83.

One related finding: restoring focus to a View embedded directly in a layer does not work on 28e8f09 or 81dcb83. restoreFocusedChild returns false for the AndroidView focus group, so the View does not get focus back. Compose content and a layer inside an embedded ComposeView do restore. I left this out of scope here and kept the restore test on Compose content.

🤖 [P2] Keep embedded View focus requests out of covered layers

This guard blocks Compose focus entry through onEnter, but a native EditText.requestFocus() can bypass it. In Compose 1.12.1, the embedded View's global-focus listener synchronizes native focus by calling performRequestFocus() directly, which skips custom enter callbacks. After the one-time clear finishes, the layer has no focus-change observer to eject focus that re-enters this way, so covered View content can take focus away from the overlay.

Could we add a regression that lets coverage settle, calls editText.requestFocus(), and verifies the covering overlay retains focus, then handle that native View entry path?

Embedded View focus handler

🤖 Fixed in 81dcb83. The layer's focus group now has an onFocusChange. If focus enters while the layer is covered and no clear is pending, the layer launches a forced clear, which runs once the focus change that moved focus there has finished. The clear signals a release, so the covering overlay requests focus again. coveredEmbeddedViewCannotKeepFocusFromCoveringOverlay lets coverage settle, calls editText.requestFocus(), and asserts that the overlay is focused and the EditText is not. It fails on 28e8f09 and passes on 81dcb83.

🤖 [P2] Retry the covering overlay's request after clearing captured focus

This supports the existing captured-focus discussion. When the covering overlay's initial request runs before this deferred clear, a captured descendant rejects it. The forced clear then releases the descendant, but nothing retries the covering sibling's one-shot request, leaving the overlay unfocused.

Could we retry the covering overlay's request after clearing, or guarantee clearing precedes that request? A regression should focus and capture the underlying editor, open a covering overlay, and assert that the overlay becomes focused once clearing completes. This should exercise the ordering where the initial request precedes the clear.

🤖 Same fix as the thread above (81dcb83): the forced clear signals a release and the covering overlay requests focus again. The regression focuses and captures the editor, then opens the overlay. Coverage is read during composition, so the initial request runs before the clear and is declined. The test asserts the overlay ends up focused and the editor does not.

🤖 [P2] Discard stale child focus when a later cover starts with the root focused

Reproduced twice on Android 9 / API 28 through the Market catalog consuming the snapshot AARs:

1. Focus an editor inside an overlayFocusTarget.
2. Cover and uncover it; the editor is correctly restored.
3. Explicitly request focus on the overlay target itself and verify that the target is focused and the editor is not.
4. Cover and uncover again.

The second uncover focuses the old editor instead of the target that was focused immediately before this cover. A control that starts with the target focused, without the earlier editor-focus cycle, passes.

Here, the participant has focus, but saveFocusedChild() returns false when the target itself is focused. That does not clear Compose's previously saved child record. The ancestor's later recursive restoreFocusedChild() can therefore follow the editor record from the previous cycle. Could we make restoration use the path saved for the current cover cycle, rather than reuse an earlier descendant after a failed save, and add this repeated-cycle regression? uncoveringRestoresEditorInsideOverlayInsteadOfOverlay is a useful starting fixture.

🤖 Fixed in 14e4c99. When an overlayFocusTarget is itself focused at cover time, the layer now saves that target for this cover cycle and requests focus on it directly on uncover instead of following the stale recursive restoreFocusedChild() path. Added uncoveringRestoresOverlayFocusedSinceEarlierEditorRestore (your repeated-cycle repro built on uncoveringRestoresEditorInsideOverlayInsteadOfOverlay); it failed on 81dcb83 at the final overlay.assertIsFocused() and passes now on API 28.

🤖 Non-blocking: cover two independent hosts sharing a window

Could we add a regression with two independent overlay hosts in the same window, each with an uncovered target whose requestInitialFocus remains true? The window-wide counter reaches targets in both hosts, and requestWantedFocus() does not associate the release with the overlay covering that layer. Targets that lack focus may therefore compete when one host releases captured or native View focus, making the eventual recipient depend on observer notification order.

This is a coverage concern, not a device-reproduced defect. A useful test would verify that the intended covering overlay gets focus while an unrelated host does not steal it; if simultaneous independent hosts are unsupported, documenting that constraint would also clarify the contract.

🤖 Good call, this reproduced. With two hosts in sibling ComposeViews, one order let the independent host's requestInitialFocus target take released focus from the covering overlay. In 14e4c99 releases no longer go window-wide: a layer notifies targets whose composition view is the layer's own or an ancestor of it (walking the View parent chain), so overlays covering a view that hosts the layer still respond and sibling hosts do not. Added releasedFocusGoesToCoveringOverlayRatherThanHostBeforeIt / ...AfterIt covering both orders. The KDoc and CHANGELOG now state the contract; two independent hosts inside one composition still share the notification.

🤖 Non-blocking: document the native View restoration limitation in the public contract

The frame-ordering reply and PR description acknowledge that a native View embedded directly in a layer loses focus on cover but is not restored on uncover, while Compose editors and content in an embedded ComposeView do restore. This KDoc currently promises restoration of the saved descendant without making that distinction.

Could we carry the limitation into the public overlayFocusLayer KDoc and the engine guide or changelog? Keeping native View restoration out of scope is reasonable, but consumers reading the API documentation should be able to tell which interop cases the restoration contract covers.

Is the only purpose of this state to trigger one of the modifier nodes to invalidate when it changes? I noticed the value isn't actually used when it's ready in the observeReads. If so, it would be more efficient (no snapshot overhead) and simpler (conceptually, if not directly code-wise) to just make a plain old observer pattern.