@multiplatform.one/web3 7.26.0 → 7.28.1

package/src/connectkit/siwe/connectIntent.ts

@@ -9,54 +9,128 @@
  * shut, so web3Bridge would route to the sign-in screen without anything on screen —
  * the user has to press connect a second time just to reach the signature prompt.
  *
- * sessionStorage survives that reload (same tab), so the intent does too.
+ * The intent lives in localStorage. A phone often kills the whole browser while the
+ * wallet app is in front, and that loses sessionStorage along with the page (measured
+ * on Android 16 Chrome, PROMA-87). It is only read, never used up, when the page comes
+ * back: a page that reads it and is then discarded before the user sees it would
+ * otherwise take it along. It ends with the sign-in (web3Bridge), a disconnect, the
+ * user closing the modal, or its expiry.
+ *
+ * localStorage outlives the tab, so only two pages act on it: the one that set it, and
+ * one the browser brought back (a reload, or the history restore Android Chrome does
+ * for a tab it killed). A page opened fresh, a new tab say, leaves it alone.
  *
  * It is deliberately an INTENT flag rather than "reopen whenever connected": a cold
  * page load with a wallet already connected must NOT pop a modal the user never asked
- * for. Only a connect the user just initiated carries the intent, and it's consumed
- * once acted on.
+ * for. Only a connect the user started carries the intent.
  *
  * The stored value is the moment the intent expires. An abandoned connect (the user
- * opened the wallet and never came back) would otherwise leave the flag set for the
- * rest of the tab's life, and a later visit whose wallet auto-reconnects would pop a
- * signature request nobody asked for.
+ * opened the wallet and never came back) would otherwise leave the flag set, and a
+ * later visit whose wallet auto-reconnects would pop a signature request nobody asked
+ * for.
  */
 const KEY = "wallet:connect-intent";
 
-/** How long a connect intent stays good. Long enough for a wallet app round trip. */
-export const CONNECT_INTENT_TTL_MS = 90_000;
+/**
+ * How long a connect intent stays good: a wallet app's cold start, its unlock and the
+ * user reading two screens, the same budget MetaMask Connect gives its own request.
+ */
+export const CONNECT_INTENT_TTL_MS = 600_000;
 
-export function setConnectIntent(ttlMs: number = CONNECT_INTENT_TTL_MS, now: number = Date.now()) {
-  if (typeof window === "undefined") return;
+type IntentStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+function storageOf(name: "localStorage" | "sessionStorage"): IntentStorage | null {
+  if (typeof window === "undefined") return null;
   try {
-    window.sessionStorage.setItem(KEY, String(now + ttlMs));
+    const storage = window[name];
+    if (typeof storage?.getItem === "function" && typeof storage.removeItem === "function") {
+      return storage;
+    }
   } catch {
-    // Private mode / storage disabled — degrade to the old behaviour, don't throw.
+    // A blocked storage throws on access.
   }
+  return null;
 }
 
 /**
- * Reads and clears the flag; true only for a connect the user initiated within the
- * TTL. A second call returns false.
+ * Where the intent lives: localStorage, which a browser kill keeps, and sessionStorage,
+ * which a same-tab reload keeps whatever the browser reports about the navigation.
  */
-export function consumeConnectIntent(now: number = Date.now()): boolean {
-  if (typeof window === "undefined") return false;
+function intentStorages(): IntentStorage[] {
+  return [storageOf("localStorage"), storageOf("sessionStorage")].filter(
+    (storage): storage is IntentStorage => storage !== null,
+  );
+}
+
+function liveIn(storage: IntentStorage | null, now: number): boolean {
+  const raw = storage?.getItem(KEY) ?? null;
+  if (raw === null) return false;
+  const expiresAt = Number(raw);
+  if (Number.isFinite(expiresAt) && now < expiresAt) return true;
+  storage?.removeItem(KEY);
+  return false;
+}
+
+let setByThisPage = false;
+
+/**
+ * Whether the browser brought this document back rather than opening it: a reload, a
+ * history restore (Android Chrome restores a tab it killed as `back_forward`, measured
+ * on Android 16) or a discarded tab.
+ */
+export function isRestoredPage(): boolean {
   try {
-    const raw = window.sessionStorage.getItem(KEY);
-    if (raw === null) return false;
-    window.sessionStorage.removeItem(KEY);
-    const expiresAt = Number(raw);
-    return Number.isFinite(expiresAt) && now < expiresAt;
+    if ((globalThis.document as { wasDiscarded?: boolean } | undefined)?.wasDiscarded) return true;
+    const [entry] = globalThis.performance?.getEntriesByType?.("navigation") ?? [];
+    const type = (entry as { type?: string } | undefined)?.type;
+    return type === "reload" || type === "back_forward";
   } catch {
     return false;
   }
 }
 
-export function clearConnectIntent() {
-  if (typeof window === "undefined") return;
+export function setConnectIntent(ttlMs: number = CONNECT_INTENT_TTL_MS, now: number = Date.now()) {
+  setByThisPage = true;
+  for (const storage of intentStorages()) {
+    try {
+      storage.setItem(KEY, String(now + ttlMs));
+    } catch {
+      // Private mode / storage disabled — degrade to the old behaviour, don't throw.
+    }
+  }
+}
+
+/**
+ * True while a connect the user started is still good, in the tab that started it or
+ * on a page the browser brought back. Reading it leaves it in place.
+ */
+export function hasConnectIntent(
+  now: number = Date.now(),
+  restored: boolean = isRestoredPage(),
+): boolean {
   try {
-    window.sessionStorage.removeItem(KEY);
+    const session = storageOf("sessionStorage");
+    const local = storageOf("localStorage");
+    const inThisTab = liveIn(session, now);
+    const kept = local !== null && local !== session && liveIn(local, now);
+    return inThisTab || (kept && (setByThisPage || restored));
   } catch {
-    // ignore
+    return false;
+  }
+}
+
+/** Test seam: forget that this page set the intent, as the next document would. */
+export function resetConnectIntentPage(): void {
+  setByThisPage = false;
+}
+
+export function clearConnectIntent() {
+  setByThisPage = false;
+  for (const storage of intentStorages()) {
+    try {
+      storage.removeItem(KEY);
+    } catch {
+      // ignore
+    }
   }
 }

package/src/connectkit/siwe/useSIWE.ts

@@ -22,7 +22,10 @@ type UseSIWEConfig = {
   onSignOut?: () => void;
 };
 
-// Consumer-facing hook
+/**
+ * The SIWEProvider's sign-in state.
+ * @deprecated Goes in 8.0.0 with SIWEProvider; `useSignIn()` reads a SignInProvider.
+ */
 export const useSIWE = ({ onSignIn, onSignOut }: UseSIWEConfig = {}): HookProps | any => {
   const siweContextValue = useContext(SIWEContext);
   if (!siweContextValue) {

package/src/connectkit/web3Bridge.tsx

@@ -1,4 +1,4 @@
-import React, { useContext as useReactContext, useEffect, useMemo } from "react";
+import React, { useContext as useReactContext, useEffect, useMemo, useRef } from "react";
 import { useAccount, useAccountEffect, useConfig } from "wagmi";
 
 import { ModalState, ModalStateProvider, routes, useContext } from "@multiplatform.one/connectkit";
@@ -7,11 +7,12 @@ import { Web3ScreenRegistrar } from "./screens";
 import { ensureWalletConnectors } from "./connectors/ensureWalletConnectors";
 import { useChainIsSupported } from "./hooks/useChainIsSupported";
 import { useConnectCallback, useConnectCallbackProps } from "./hooks/useConnectCallback";
-import { clearConnectIntent, consumeConnectIntent } from "./siwe/connectIntent";
-import { SIWEContext } from "./siwe/SIWEContext";
+import { clearConnectIntent, hasConnectIntent } from "./siwe/connectIntent";
+import { SIWEContext, StatusState } from "./siwe/SIWEContext";
 import { GpgContext } from "@multiplatform.one/gpg";
 import { useWallet } from "./wallets/useWallets";
 import { ConnectorLauncherProvider } from "./openConnector";
+import { WagmiConnectionHost } from "../wagmi/host";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // The web3 ⇄ connectkit bridge: the ONE place that knows both wagmi and the
@@ -25,8 +26,15 @@ import { ConnectorLauncherProvider } from "./openConnector";
 //
 // A gpg-only host renders no bridge → connectkit's default empty ModalState → no
 // viem anywhere in the tree.
+//
+// Under a bare WagmiProvider (no Web3Provider above) it also mounts the
+// connection store over that config, so useConnection() works wherever the
+// modal does.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** How long a page stays disconnected on load before a live intent reopens the list. */
+export const RESUME_SETTLE_MS = 1_000;
+
 export type Web3ModalBridgeProps = {
   children: React.ReactNode;
 } & useConnectCallbackProps;
@@ -40,10 +48,11 @@ export const Web3ModalBridge: React.FC<Web3ModalBridgeProps> = ({
 
   useConnectCallback({ onConnect, onDisconnect });
 
-  const { isConnected, chain } = useAccount();
+  const { isConnected, chain, status } = useAccount();
   const chainIsSupported = useChainIsSupported(chain?.id);
 
-  const signInWithEthereum = useReactContext(SIWEContext)?.enabled ?? false;
+  const siwe = useReactContext(SIWEContext);
+  const signInWithEthereum = siwe?.enabled ?? false;
   const signInWithGpg = useReactContext(GpgContext)?.enabled ?? false;
   const { isSignedIn } = useSIWESignedIn();
 
@@ -71,6 +80,16 @@ export const Web3ModalBridge: React.FC<Web3ModalBridgeProps> = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isConnected, chainIsSupported, chain]);
 
+  // The bridge's own closes (no answer from a reconnect, a wallet connected with no
+  // sign-in step) are not the user closing the modal, so they leave the intent alone.
+  const openNow = useRef(context.open);
+  openNow.current = context.open;
+  const closingForBridge = useRef(false);
+  const closeForBridge = () => {
+    if (openNow.current) closingForBridge.current = true;
+    context.setOpen(false);
+  };
+
   // On connect: redirect to SIWE (when enabled) or close the modal.
   useEffect(() => {
     if (isConnected) {
@@ -90,15 +109,16 @@ export const Web3ModalBridge: React.FC<Web3ModalBridgeProps> = ({
           // setting the route alone left the sign-in screen mounted behind a shut
           // modal, and the user had to press connect a second time just to get the
           // signature prompt. Reopen only when the user actually initiated this
-          // connect (consumeConnectIntent) — a cold load with a wallet already
+          // connect (hasConnectIntent) — a cold load with a wallet already
           // connected must not pop a modal nobody asked for.
-          if (consumeConnectIntent()) context.setOpen(true);
+          if (hasConnectIntent()) context.setOpen(true);
         } else {
-          context.setOpen(false);
+          clearConnectIntent();
+          closeForBridge();
         }
       }
     } else {
-      context.setOpen(false);
+      closeForBridge();
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isConnected]);
@@ -107,6 +127,44 @@ export const Web3ModalBridge: React.FC<Web3ModalBridgeProps> = ({
   // next reconnect.
   useAccountEffect({ onDisconnect: () => clearConnectIntent() });
 
+  // So does the sign-in, and the user shutting the modal.
+  const siweStatus = siwe?.status;
+  useEffect(() => {
+    if (isSignedIn || siweStatus === StatusState.SUCCESS || siweStatus === StatusState.REJECTED) {
+      clearConnectIntent();
+    }
+  }, [isSignedIn, siweStatus]);
+  const wasOpen = useRef(context.open);
+  useEffect(() => {
+    if (wasOpen.current && !context.open && !closingForBridge.current) clearConnectIntent();
+    closingForBridge.current = false;
+    wasOpen.current = context.open;
+  }, [context.open]);
+
+  // A page the browser threw away during the wallet trip comes back without the
+  // connect's answer. Once wagmi has settled on disconnected, a live intent reopens
+  // the wallet list, one tap from the wallet, instead of leaving the bare page.
+  const latestStatus = useRef(status);
+  latestStatus.current = status;
+  const resumeChecked = useRef(false);
+  useEffect(() => {
+    if (resumeChecked.current) return;
+    if (status === "connected") {
+      resumeChecked.current = true;
+      return;
+    }
+    if (status !== "disconnected") return;
+    const timer = setTimeout(() => {
+      if (resumeChecked.current || latestStatus.current !== "disconnected") return;
+      resumeChecked.current = true;
+      if (openNow.current || !hasConnectIntent()) return;
+      context.setRoute(routes.CONNECTORS);
+      context.setOpen(true);
+    }, RESUME_SETTLE_MS);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [status]);
+
   const modalState = useMemo<ModalState>(
     () => ({
       connected: isConnected,
@@ -120,12 +178,14 @@ export const Web3ModalBridge: React.FC<Web3ModalBridgeProps> = ({
   );
 
   return (
-    <Web3ContextProvider>
-      <Web3ScreenRegistrar />
-      <ModalStateProvider value={modalState}>
-        <ConnectorLauncherProvider>{children}</ConnectorLauncherProvider>
-      </ModalStateProvider>
-    </Web3ContextProvider>
+    <WagmiConnectionHost>
+      <Web3ContextProvider>
+        <Web3ScreenRegistrar />
+        <ModalStateProvider value={modalState}>
+          <ConnectorLauncherProvider>{children}</ConnectorLauncherProvider>
+        </ModalStateProvider>
+      </Web3ContextProvider>
+    </WagmiConnectionHost>
   );
 };
 

package/src/core/family.spec.ts

@@ -50,6 +50,25 @@ describe("defineWalletFamily", () => {
     );
   });
 
+  it("carries a frozen bridge namespace and driver, and refuses a bad one", () => {
+    const bridgeDriver = () => testDriver("solana", [], {});
+    const family = defineWalletFamily({
+      ...sol,
+      bridge: { namespace: "solana", driver: bridgeDriver },
+    });
+    expect(family.bridge).toEqual({ namespace: "solana", driver: bridgeDriver });
+    expect(Object.isFrozen(family.bridge)).toBe(true);
+    expect(defineWalletFamily({ ...gpg, bridge: { namespace: "gpg" } }).bridge?.namespace).toBe(
+      "gpg",
+    );
+    expect(() => defineWalletFamily({ ...sol, bridge: { namespace: "Solana" } })).toThrow(
+      /bridge namespace must be lowercase/,
+    );
+    expect(() =>
+      defineWalletFamily({ ...gpg, bridge: { namespace: "gpg", driver: bridgeDriver } }),
+    ).toThrow(/connectionless and cannot have a bridge driver/);
+  });
+
   it("a connectable family needs a driver", () => {
     expect(() => defineWalletFamily({ ...sol, driver: undefined })).toThrow(/needs a driver/);
   });

package/src/core/family.ts

@@ -8,6 +8,34 @@ import {
 import { assertName, nameTable } from "./names";
 import type { ConnectionDriver } from "./types";
 
+/** What a bridge driver asks of the native app's bridge client (`BridgeClient` fits). */
+export interface BridgeRequester {
+  request(
+    ns: string,
+    method: string,
+    params?: unknown,
+    options?: { timeoutMs?: number; signal?: AbortSignal },
+  ): Promise<unknown>;
+  /** Every event the hosted page pushes. Returns the unsubscribe. */
+  on(handler: (ns: string, method: string, params: unknown) => void): () => void;
+}
+
+/**
+ * How a React Native app reaches the family's wallets: the hosted wallet page
+ * runs them and serves the family on one bridge namespace.
+ */
+export interface FamilyBridge {
+  /** The namespace the page serves the family on: `evm`, `solana`, `sui`, `gpg`. */
+  readonly namespace: string;
+  /**
+   * The family's connection driver over the bridge, which the native
+   * Web3Provider uses in place of `driver`. Without it the family connects
+   * some other way on native (eth through the bridge's wagmi connector) or
+   * signs without connecting (gpg).
+   */
+  readonly driver?: (bridge: BridgeRequester) => ConnectionDriver;
+}
+
 /** What a family package hands the core: `eth({chains})`, `sol({rpcUrl})`, `gpg()`. */
 export interface WalletFamilyDefinition {
   /** Short family id, the one the Keycloak message names: `eth`, `sol`, `sui`, `btc`, `gpg`. */
@@ -27,6 +55,8 @@ export interface WalletFamilyDefinition {
   readonly screens?: readonly ScreenDef[];
   /** A provider the family needs mounted around the app. */
   readonly Provider?: ComponentType<{ children?: ReactNode }>;
+  /** How a native app reaches the family's wallets through the hosted wallet page. */
+  readonly bridge?: FamilyBridge;
 }
 
 export interface WalletFamily extends WalletFamilyDefinition {
@@ -58,12 +88,25 @@ export function defineWalletFamily(definition: WalletFamilyDefinition): WalletFa
   if (!connectionless && typeof definition.driver !== "function") {
     throw new Error(`wallet family ${definition.id} needs a driver, or connectionless: true`);
   }
+  const { bridge } = definition;
+  if (bridge !== undefined) {
+    assertName(`wallet family ${definition.id} bridge namespace`, bridge.namespace);
+    if (bridge.driver !== undefined && typeof bridge.driver !== "function") {
+      throw new Error(`wallet family ${definition.id}'s bridge driver must be a function`);
+    }
+    if (bridge.driver && connectionless) {
+      throw new Error(
+        `wallet family ${definition.id} is connectionless and cannot have a bridge driver`,
+      );
+    }
+  }
   return Object.freeze({
     ...definition,
     aliases: Object.freeze(aliases),
     connectionless,
     message: Object.freeze({ ...message }),
     ...(definition.screens ? { screens: Object.freeze([...definition.screens]) } : {}),
+    ...(bridge ? { bridge: Object.freeze({ ...bridge }) } : {}),
   });
 }
 

package/src/core/imports.spec.ts

@@ -67,7 +67,7 @@ function runtimeGraph(start: string) {
 describe("the core entry", () => {
   it("loads no chain SDK: only React and its own files", () => {
     const { files, packages } = runtimeGraph(entry);
-    expect(Object.fromEntries(packages)).toEqual({ react: "core/react.ts" });
+    expect([...packages.keys()]).toEqual(["react"]);
     expect(files.every((file) => file.startsWith("core/") || file === "clients/types.ts")).toBe(
       true,
     );

package/src/core/index.ts

@@ -4,6 +4,8 @@
 export {
   createFamilyRegistry,
   defineWalletFamily,
+  type BridgeRequester,
+  type FamilyBridge,
   type FamilyRegistry,
   type WalletFamily,
   type WalletFamilyDefinition,
@@ -22,13 +24,33 @@ export {
   type ConnectionStoreOptions,
   type FamilyConnector,
 } from "./store";
+export {
+  lightDriver,
+  type LightDriverOptions,
+  type LightWallet,
+  type LightWalletAdapter,
+} from "./lightDriver";
 export {
   ConnectionProvider,
   useConnection,
   useConnectionStore,
+  useOptionalConnectionStore,
   type ConnectionProviderProps,
 } from "./react";
+export {
+  SignInProvider,
+  signInWithConnection,
+  useOptionalSignIn,
+  useSignIn,
+  type SignIn,
+  type SignInConfig,
+  type SignInCredential,
+  type SignInMessageArgs,
+  type SignInProviderProps,
+  type SignInStatus,
+} from "./signIn";
 export type {
+  ConnectOptions,
   ConnectionDriver,
   ConnectionState,
   ConnectionStatus,
@@ -40,6 +62,7 @@ export type {
   WalletConnector,
 } from "./types";
 export {
+  ReadOnlyClientError,
   UnsupportedClientMethodError,
   type ChainClient,
   type ClientCapability,