Platform limitations

iOS constraints

• iOS Safari never fires beforeinstallprompt. There is no programmatic install flow, so an iOS build must render product-specific Share → Add to Home Screen guidance instead.
• An installed iOS PWA can have its storage evicted and its background work constrained, so a waiting service-worker update may not apply until the next foreground launch.
• iOS auto-scrolls the focused field when the software keyboard opens. That can compound with KeyboardAvoidingView using behavior="position"; verify the padding and height behaviors on a real device.
• The web platform cannot use native iOS action-sheet chrome or system haptics. ActionSheet is a faithful web presentation, not the system control.
• The home-indicator area in an installed PWA is handled with the footer safe-area inset, not by the OS.

Android keyboard & viewport policy

On Android, what the software keyboard does to the viewport is decided by the page's interactive-widget policy, and PWA UI derives keyboard height from the visual viewport shrinking.

iOS Safari ignores interactive-widget entirely and always reports a shrinking visual viewport, so the keyboard hooks work there regardless of the policy you set. See Browser support for the full tradeoff.

Connectivity signal

• navigator.onLine is a hint, not proof of connectivity. It can report online behind a captive portal with no working internet, and it can report offline while requests still succeed.
• Never gate a critical action on the reported status. Always handle failed requests directly and treat OfflineBanner as context for the user rather than a guard.

Safe-area availability

• env(safe-area-inset-*) only reports non-zero values when the page sets viewport-fit=cover on a device with display cutouts, or on an installed or otherwise edge-to-edge surface.
• Everywhere else — including an ordinary desktop or mobile browser tab — these values resolve to 0 by design. SafeArea and the AppShell chrome regions degrade to no padding rather than guessing at device models.
• --pwa-viewport-height tracks the visual viewport and shrinks when the keyboard opens. Anchor fixed chrome with the safe-area padding these components apply rather than with 100vh.

Base UI Drawer dependency

• Gesture physics, snap points, dismissal, and focus management for BottomSheet, ActionSheet, and the mobile presentation of ResponsiveDialog come from Base UI's Drawer. These components target @base-ui/react 1.x.
• Drawer's interaction details remain an external behavioral dependency: pin the version you tested, and re-run your gesture and snap checks when you upgrade it.
• The drag handle is decorative and is not operable by assistive technology. Provide a visible Close, or rely on Escape and backdrop dismissal, for users who cannot perform the gesture.

Display-mode detection

• Display mode and breakpoint checks are media queries resolved on the client. useDisplayMode reports unknown during server rendering, and the responsive presentation assumes the desktop case until hydration.
• Crossing the ResponsiveDialog breakpoint while the overlay is open swaps implementations and remounts the content subtree, resetting uncontrolled state and focus. Lift state you must preserve above Content.
• Standalone detection varies by browser: iOS reports it through a non-standard navigator.standalone flag, and Firefox's installed-app support is limited.