Native iOS overlays

Control whether Magic Modal renders above native modal screens such as image pickers.

On iOS, Magic Modal can use a full-window overlay so application modals stay above native screens. This is enabled by default.

The overlay is a native window, so the portal only mounts it while the stack has something in it. An idle app has no extra window in its accessibility tree, which keeps screen readers and UI test selectors on the real screen. It stays mounted through the closing animation and unmounts once the last modal has finished animating out.

Disable it before an interaction that should sit behind a native picker:

magicModal.disableFullWindowOverlay();

try {
  await openImagePicker();
} finally {
  magicModal.enableFullWindowOverlay();
}

Both methods are no-ops on non-iOS platforms.

Always re-enable the overlay in finally. Otherwise a rejected native interaction can silently change the layering of every later modal.