From 87e7e00a67efb3e655f26b945e633633a39e92cf Mon Sep 17 00:00:00 2001
From: Derek <256792747+decofe@users.noreply.github.com>
Date: Sun, 31 May 2026 20:48:52 +0000
Subject: [PATCH] docs: add mobile safari popup guidance

---
 src/pages/accounts/api/dialog.iframe.mdx |  2 ++
 src/pages/accounts/api/dialog.popup.mdx  | 41 ++++++++++++++++++++++++
 src/pages/accounts/production.mdx        |  4 +++
 3 files changed, 47 insertions(+)

diff --git a/src/pages/accounts/api/dialog.iframe.mdx b/src/pages/accounts/api/dialog.iframe.mdx
index d780474f..e138acfd 100644
--- a/src/pages/accounts/api/dialog.iframe.mdx
+++ b/src/pages/accounts/api/dialog.iframe.mdx
@@ -9,6 +9,8 @@ Creates an iframe dialog that embeds the auth app in a `<dialog>` element. This
 
 Falls back to a popup on Safari (which does not support WebAuthn in cross-origin iframes) and insecure (HTTP) origins.
 
+Because Safari uses the popup fallback, open the wallet directly from the user's tap. Avoid `await`ing config fetches, dynamic imports, or other setup before calling `provider.request({ method: 'wallet_connect' })`; preload that work before rendering the button. See [`Dialog.popup`](/accounts/api/dialog.popup#mobile-safari-popup-blocking) for the recommended handler pattern.
+
 ## Usage
 
 ```ts
diff --git a/src/pages/accounts/api/dialog.popup.mdx b/src/pages/accounts/api/dialog.popup.mdx
index 5d287442..079c91b1 100644
--- a/src/pages/accounts/api/dialog.popup.mdx
+++ b/src/pages/accounts/api/dialog.popup.mdx
@@ -7,6 +7,47 @@ description: Open the Tempo Wallet auth UI in a popup window.
 
 Opens the auth app in a new browser window. Used as the default on Safari and insecure (HTTP) origins.
 
+## Mobile Safari popup blocking
+
+Mobile Safari blocks popups unless they open directly from the user's tap. Preload the Accounts SDK, provider, and any app configuration before the user taps a connect or payment button. In the tap handler, call the wallet request immediately, then continue the rest of your flow after the wallet responds.
+
+```tsx
+function ConnectButton({ provider }: { provider: Provider }) {
+  return (
+    <button
+      onClick={async () => {
+        const result = await provider.request({ method: 'wallet_connect' })
+        await continueAfterConnect(result)
+      }}
+    >
+      Connect
+    </button>
+  )
+}
+```
+
+Do not fetch config, dynamically import the SDK, or check app state before opening the wallet inside the tap handler. If preload has not finished, show a loading state and ask the user to tap again.
+
+```tsx
+function ConnectButton({ providerReady }: { providerReady: boolean }) {
+  return (
+    <button
+      onClick={async () => {
+        if (!providerReady) {
+          setMessage('Tempo Wallet is still loading. Tap again in a moment.')
+          return
+        }
+
+        const result = await provider.request({ method: 'wallet_connect' })
+        await continueAfterConnect(result)
+      }}
+    >
+      Connect
+    </button>
+  )
+}
+```
+
 ## Usage
 
 ```ts
diff --git a/src/pages/accounts/production.mdx b/src/pages/accounts/production.mdx
index 52d8d25d..a54f7919 100644
--- a/src/pages/accounts/production.mdx
+++ b/src/pages/accounts/production.mdx
@@ -13,6 +13,10 @@ To enable the `iframe` dialog on all browsers in production, ensure your website
 
 Without this, the `iframe` dialog will fallback to a popup on browsers that do not support the [IntersectionObserver v2 API](https://web.dev/articles/intersectionobserver-v2).
 
+## Mobile Safari
+
+Safari uses the popup fallback because WebAuthn is not supported in cross-origin iframes. Make sure the wallet request opens immediately from the user's tap: preload the Accounts SDK, provider, and configuration before the tap, then call `provider.request({ method: 'wallet_connect' })` as the first async wallet step in the tap handler. If preload is not ready, show a loading or retry state instead of doing setup and opening the popup later.
+
 ## Content Security Policy
 
 If you've deployed a Content Security Policy, ensure that you have the Tempo Accounts SDK configured with your CSPs.