docs: say that the page lags behind the wallet on the way back, and to wait it out (#177)

Every wallet round-trip on a phone -- signing the identity, adding a chain,
switching to one -- ends the same way: the user approves in MetaMask, comes back,
and the tab still says "Connecting Wallet...". Android suspends the browser's
connection while it is in the background, so the page only sees the approval once
that connection is re-established. Nothing here said so, and the natural reaction
is to tap again or reload -- which cancels the request they just approved and
sends them round the loop a second time.

So: an admonition at "Set your identity", one at the return step of both
chain-switch walkthroughs, and troubleshooting entries in both places. Each says
the same two things -- this is expected, and helping makes it worse.

Also brings the stuck-wallet advice in line with what the app now tells you.
The app leads with "tap Open wallet to approve again" and only falls back to the
force-quit; the docs led with the force-quit, which is the heavier step and skips
straight past the cheap one.


Claude-Session: https://claude.ai/code/session_013BpqXrkEPA9odTyRdK5Mnx

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ehsan6sha

docs/functionyard/fxblox-app.md

@@ -56,8 +56,18 @@ Enter a memorable **password** — this encrypts your data and is **not** your M
 
 Your password plus that one signature is what produces your identity. **Write the password down**: the same password with the same wallet always produces the same identity, and a different password produces a different one.
 
+On a phone this takes two taps, on purpose: the first **Sign with Wallet** connects the wallet, and the second sends it the signature request. A browser is only allowed to switch to another app from a real tap, so the second one cannot happen for you.
+
+:::info Coming back from your wallet? Give the page a few seconds
+After you approve in MetaMask — or any other wallet — and return to the FxBlox tab, the page can still show **Connecting Wallet…** for a few seconds before it catches up. That is normal. Android suspends the browser's connection while you are away in another app, and it has to be re-established before the page can see what you approved.
+
+**Wait for it rather than helping.** Tapping the button again, reloading the tab or going back a screen cancels the request you just approved, and you have to start the whole hand-off over. Only if nothing has changed after roughly half a minute is something actually wrong.
+:::
+
 :::tip Wallet opened but stuck on its splash screen?
-On Android this happens occasionally. Close MetaMask completely from your recent apps, return to the FxBlox tab and tap **Open wallet to approve** again — your signature request is still waiting.
+This happens on Android, most often on the first signature right after connecting. Come back to the FxBlox tab and tap **Open wallet to approve** once more — the second attempt opens the wallet a different way and usually gets past it.
+
+If it is still stuck, close the wallet completely from your recent apps and tap **Open wallet to approve** again. Your signature request stays valid throughout, so nothing is lost and you do not need to start again.
 :::
 
 ### 4. Connect to your Blox
@@ -111,7 +121,7 @@ We recommend unplugging and replugging the Blox once after the initial setup. It
 
 **You do not need to set your Blox up again.** The web app derives your identity exactly the same way the mobile app does: the same password with the same wallet produces the same identity, so a Blox that was paired from your phone recognises the browser straight away.
 
-Open the web app, enter your existing password, sign with the same wallet, then choose **Reconnect to existing blox**:
+Open the web app, enter your existing password, sign with the same wallet, then choose **Reconnect to existing blox**. Signing works exactly as in [step 3](#3-set-your-identity) — including the wait after you come back from your wallet:
 
 <img src="/img/fxblox-web/04-connect-existing.jpg" alt="Finding Bloxes on your network" style={{maxWidth: '250px'}} />
 
@@ -163,7 +173,8 @@ The Blox reconnects to the network and saves chain history automatically.
 - **Chrome's Bluetooth chooser is empty.** Leave it open for up to 90 seconds — the Blox advertises periodically rather than continuously. Make sure Bluetooth is switched on, and that the browser itself is allowed to use it (see the macOS and Android notes below).
 - **On macOS**, Chrome needs two permissions from the system or it will fail quietly. Grant both under  **System Settings → Privacy & Security**: **Bluetooth** (otherwise the device chooser stays empty) and **Local Network** (otherwise the app cannot reach the Blox over Wi-Fi). Quit and reopen Chrome after changing them.
 - **On Android**, the browser needs the location / nearby-devices permission before it can scan for Bluetooth devices.
-- **The wallet does not come back after signing.** Switch back to the FxBlox tab yourself. If MetaMask is stuck on its splash screen, close it fully from recent apps and tap **Open wallet to approve** again.
+- **The page still says "Connecting Wallet…" after you approved.** Wait a few seconds. The browser's connection is suspended while you are away in your wallet and has to be re-established on the way back, so the page notices a little after you do. Do not tap again or reload — that cancels the request you just approved.
+- **The wallet does not come back after signing.** Switch back to the FxBlox tab yourself. If MetaMask is stuck on its splash screen, tap **Open wallet to approve** once more first; if it is still stuck, close MetaMask fully from recent apps and tap it again. The signature request stays valid either way.
 - **Connection problems at the final step.** Connect to the same Wi-Fi as the Blox, reload the page, and use **Reconnect to existing blox**. If that does not work, restart the Blox, wait for the flashing light blue, and set it up again.
 - **Starting completely over.** The browser equivalent of uninstalling and reinstalling the app is **Clear app storage** on the *Set identity* screen. It deletes everything FxBlox stored in this browser — identity, Blox list, settings and caches — and reloads the page.
 - **Nothing loads after a new release.** Reload the tab. If a "new version available" prompt appears, accept it.

docs/functionyard/mainnet-transition/android-connected.md

@@ -21,6 +21,10 @@ Open **[https://docs.fx.land/fxblox-web/](https://docs.fx.land/fxblox-web/)** in
 
 Sign in with the same password and the same wallet you used before; your Blox is recognised immediately. If it does not appear, use **Reconnect to existing blox** and search your network.
 
+:::info Signing on a phone? Give the page a few seconds afterwards
+When you come back from MetaMask, the FxBlox tab can still say **Connecting Wallet…** for a few seconds before it catches up — the browser's connection is suspended while you are away in another app. Wait rather than tapping again or reloading, which cancels what you just approved. Full walkthrough: [Set your identity](/functionyard/fxblox-app#3-set-your-identity).
+:::
+
 You can check the version at any time in **Settings > About**.
 
 :::info Still on the mobile app?
@@ -53,7 +57,8 @@ Default selection is **Skale**. If you have an authorization code, change to **B
 3. **Wait a few seconds** on MetaMask
 4. You'll see a "Go back to application" message
 5. Switch back to the FxBlox app
-6. The button should disappear
+6. **Wait a few more seconds there** — the page reconnects to your wallet before it can see the change, so it lags a little behind MetaMask. Tapping the button again or reloading in the meantime cancels what you just approved.
+7. The button should disappear
 
 :::tip Success Indicator
 When the "Switch to Skale/Base" button disappears from the home screen, the transition is successful!

docs/functionyard/troubleshooting/switch-chain.md

@@ -60,8 +60,15 @@ When you see "Return to App" in MetaMask, it means the network switching process
 
 #### Step 6: Return to FxBlox App
 1. **Click "Return to App"** in MetaMask or switch back to the FxBlox app
-2. **The "Switch to Chain" button should now disappear**
-3. **Your app should now be properly connected** to the selected network
+2. **Give the page a few seconds** — see the note below
+3. **The "Switch to Chain" button should now disappear**
+4. **Your app should now be properly connected** to the selected network
+
+:::info The page may lag a few seconds behind your wallet
+On a phone, the browser's connection to your wallet is suspended while you are away in MetaMask, and has to be re-established when you come back. So the FxBlox tab can still show **Connecting Wallet…**, or still show the old button, for a few seconds after you have already approved.
+
+**Wait rather than helping.** Tapping the button again or reloading the tab in those first seconds cancels the request you just approved and starts the hand-off over. Only if nothing has changed after roughly half a minute should you try the steps again.
+:::
 
 ## Troubleshooting Tips
 
@@ -76,6 +83,8 @@ When you see "Return to App" in MetaMask, it means the network switching process
 - **Contact support** if you believe you should have access to a specific chain
 
 ### MetaMask Connection Problems
+- **Give it a few seconds first** if the app still says "Connecting Wallet…" after you came back from MetaMask — on a phone the page catches up a little after you do, and tapping again in the meantime cancels what you just approved
+- **On Android, if MetaMask opens and sits on its splash screen**, come back to the FxBlox tab and tap the button once more; if it is still stuck, close MetaMask completely from your recent apps and tap again
 - **Refresh the MetaMask extension** if it appears unresponsive
 - **Check MetaMask permissions** for the FxBlox app
 - **Try using a different browser** if issues persist