@multiplatform.one/web3 5.0.27

package/src/index.ts

@@ -0,0 +1,70 @@
+// Providers
+export {
+  WalletProvider,
+  useWeb3Config,
+  defaultChains,
+  type WalletProviderProps,
+  type Web3Config,
+} from "./providers";
+
+// Hooks
+export {
+  useWallet,
+  type UseWalletResult,
+  type WalletActions,
+  type WalletState,
+  // Contract interaction hooks
+  useContractRead,
+  useContractWrite,
+  type ContractReadConfig,
+  type ContractReadResult,
+  type ContractWriteConfig,
+  type ContractWriteResult,
+  type TransactionStatus,
+  // Re-exported wagmi hooks
+  useAccount,
+  useBalance,
+  useChainId,
+  useChains,
+  useConnect,
+  useDisconnect,
+  useEnsAvatar,
+  useEnsName,
+  useSignMessage,
+  useSwitchChain,
+  useBlockNumber,
+  useReadContract,
+  useWriteContract,
+  useSimulateContract,
+  useWaitForTransactionReceipt,
+} from "./hooks";
+
+// Components
+export {
+  WalletButton,
+  WalletAvatar,
+  WalletStatus,
+  NetworkSwitcher,
+  TransactionStatus as TransactionStatusComponent,
+  ConnectKitButton,
+  type WalletButtonProps,
+  type WalletAvatarProps,
+  type WalletStatusProps,
+  type NetworkSwitcherProps,
+  type TransactionStatusProps,
+} from "./components";
+
+// Examples
+export { LockContract, lockAbi, type LockContractProps } from "./examples";
+
+// Re-export useful types from viem/wagmi
+export type { Address, Chain } from "viem";
+export { mainnet, polygon, optimism, arbitrum, base, sepolia } from "wagmi/chains";
+
+// Bridge (Hermes-safe; shared by web + the native WebView host)
+export * from "./bridge";
+
+// NOTE: SIWS (`./siws`) is intentionally NOT re-exported here. Its server-side
+// verify pulls @noble/curves + bs58 (ESM-only) which Hermes rejects in the RN
+// bundle ("import statement requires module mode"). It's server/web-side only —
+// import it directly from "@multiplatform.one/web3/siws" (or the source path).

package/src/providers/WalletProvider.native.tsx

@@ -0,0 +1,188 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { PropsWithChildren } from "react";
+import { createContext, useContext, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { AppState, Linking, StyleSheet, View } from "react-native";
+import { WebView, type WebViewMessageEvent, type WebViewProps } from "react-native-webview";
+import { http, WagmiProvider, createConfig } from "wagmi";
+import { BridgeClient } from "../bridge/BridgeClient";
+import { SolanaBridge } from "../bridge/SolanaBridge";
+import { createBridgeConnector } from "../bridge/bridgeConnector";
+import { createPostMessageTransport } from "../bridge/postMessageTransport";
+import { parseWalletReturn, shouldOpenExternally } from "./native/deepLink";
+import { buildConfigInjection, buildInjectScript } from "./native/inject";
+import { initialVisibility, nextVisibility } from "./native/visibility";
+import { type Web3Config, Web3ConfigContext, defaultChains } from "./walletConfig";
+
+type WebViewSource = NonNullable<WebViewProps["source"]>;
+
+// The wallet WebView must be loaded over a URL. WKWebView won't render the ~7MB
+// bundle inline via source={{html}} (size limit + it breaks the host render), so
+// there is no inline fallback: callers pass `webViewSource` or set `config.webViewUrl`
+// to a served copy of assets/webview.html.
+export interface WalletProviderProps extends PropsWithChildren {
+  config: Web3Config;
+  queryClient?: QueryClient;
+  /** Override the WebView content (defaults to `config.webViewUrl`). */
+  webViewSource?: WebViewSource;
+}
+
+/** Native Solana surface, mirroring the operations web's wallet-adapter exposes. */
+export interface SolanaWalletContextValue {
+  bridge: SolanaBridge;
+  publicKey: string | null;
+  connected: boolean;
+}
+
+const SolanaWalletContext = createContext<SolanaWalletContextValue | null>(null);
+
+export function useSolanaWallet(): SolanaWalletContextValue {
+  const value = useContext(SolanaWalletContext);
+  if (!value) throw new Error("useSolanaWallet must be used within a WalletProvider");
+  return value;
+}
+
+const defaultQueryClient = new QueryClient();
+
+export function WalletProvider({
+  children,
+  config: web3Config,
+  queryClient = defaultQueryClient,
+  webViewSource,
+}: WalletProviderProps) {
+  const webRef = useRef<WebView>(null);
+  const readyRef = useRef(false);
+  const outboundQueue = useRef<string[]>([]);
+
+  const [visibility, dispatchVisibility] = useReducer(nextVisibility, initialVisibility);
+  const [publicKey, setPublicKey] = useState<string | null>(null);
+
+  // One bridge for the WebView's lifetime. Outbound messages are queued until the
+  // WebView signals `sys/ready`, then flushed (the connect request often fires first).
+  const { bridge, solana, transport } = useMemo(() => {
+    const t = createPostMessageTransport((raw) => {
+      if (readyRef.current && webRef.current) webRef.current.injectJavaScript(buildInjectScript(raw));
+      else outboundQueue.current.push(raw);
+    });
+    const client = new BridgeClient(t);
+    return { bridge: client, solana: new SolanaBridge(client), transport: t };
+  }, []);
+
+  // React to the WebView's lifecycle + account events.
+  useEffect(() => {
+    const off = bridge.on((ns, method, params) => {
+      if (ns === "sys") {
+        if (method === "ready") {
+          readyRef.current = true;
+          const queued = outboundQueue.current.splice(0);
+          for (const raw of queued) webRef.current?.injectJavaScript(buildInjectScript(raw));
+        } else if (method === "modalOpen" || method === "modalClose") {
+          dispatchVisibility(method);
+        }
+      } else if (ns === "solana" && method === "accountChanged") {
+        setPublicKey((params as { publicKey: string | null } | undefined)?.publicKey ?? null);
+      }
+    });
+    return off;
+  }, [bridge]);
+
+  // On app foreground (e.g. return from a wallet deep link) ask the WebView to
+  // re-report account/chain state.
+  useEffect(() => {
+    const sub = AppState.addEventListener("change", (state) => {
+      if (state === "active" && readyRef.current) {
+        void bridge.request("sys", "resync").catch(() => undefined);
+      }
+    });
+    return () => sub.remove();
+  }, [bridge]);
+
+  // Inbound app-link returns from a wallet app: forward the params into the
+  // WebView (the mock-wallet path consumes address/signature; real WalletConnect
+  // just needs the resync that AppState already triggers).
+  useEffect(() => {
+    const handle = (url: string | null) => {
+      if (!url) return;
+      const params = parseWalletReturn(url);
+      if (params) void bridge.request("sys", "deepLinkReturn", params).catch(() => undefined);
+    };
+    const sub = Linking.addEventListener("url", (event) => handle(event.url));
+    void Linking.getInitialURL()
+      .then(handle)
+      .catch(() => undefined);
+    return () => sub.remove();
+  }, [bridge]);
+
+  const wagmiConfig = useMemo(() => {
+    const transports = Object.fromEntries(defaultChains.map((chain) => [chain.id, http()]));
+    return createConfig({
+      chains: defaultChains,
+      transports,
+      connectors: [createBridgeConnector(bridge)],
+      multiInjectedProviderDiscovery: false,
+    });
+  }, [bridge]);
+
+  const solanaValue = useMemo<SolanaWalletContextValue>(
+    () => ({ bridge: solana, publicKey, connected: publicKey !== null }),
+    [solana, publicKey],
+  );
+
+  const onMessage = (event: WebViewMessageEvent) => transport.receive(event.nativeEvent.data);
+
+  // No inline HTML fallback: the bundle is too large for WKWebView source={{html}}.
+  const resolvedSource = webViewSource ?? (web3Config.webViewUrl ? { uri: web3Config.webViewUrl } : null);
+  if (!resolvedSource) {
+    throw new Error(
+      "WalletProvider (native): set config.webViewUrl (or pass webViewSource) to a served copy of @multiplatform.one/web3/assets/webview.html",
+    );
+  }
+
+  return (
+    <Web3ConfigContext.Provider value={web3Config}>
+      <WagmiProvider config={wagmiConfig}>
+        <QueryClientProvider client={queryClient}>
+          <SolanaWalletContext.Provider value={solanaValue}>
+            {children}
+            <View
+              style={visibility.sheetOpen ? styles.visible : styles.hidden}
+              pointerEvents={visibility.sheetOpen ? "auto" : "none"}
+            >
+              <WebView
+                ref={webRef}
+                source={resolvedSource}
+                originWhitelist={["*"]}
+                javaScriptEnabled
+                domStorageEnabled
+                onMessage={onMessage}
+                onShouldStartLoadWithRequest={(req) => {
+                  // Hand wallet deep links to the OS; keep everything else in the WebView.
+                  if (shouldOpenExternally(req.url)) {
+                    void Linking.openURL(req.url).catch(() => undefined);
+                    return false;
+                  }
+                  return true;
+                }}
+                injectedJavaScriptBeforeContentLoaded={buildConfigInjection({
+                  ...web3Config,
+                  appUrl: web3Config.appUrl ?? "",
+                })}
+                style={styles.webview}
+              />
+            </View>
+          </SolanaWalletContext.Provider>
+        </QueryClientProvider>
+      </WagmiProvider>
+    </Web3ConfigContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Kept mounted but offscreen so the bridge/ConnectKit/wagmi state persists.
+  hidden: { position: "absolute", width: 1, height: 1, top: -1000, left: -1000, opacity: 0 },
+  // Full-screen overlay while the connect modal is showing.
+  visible: { ...StyleSheet.absoluteFillObject, zIndex: 9999 },
+  webview: { flex: 1, backgroundColor: "transparent" },
+});
+
+export { defaultChains } from "./walletConfig";
+export { useWeb3Config, type Web3Config } from "./walletConfig";

package/src/providers/WalletProvider.tsx

@@ -0,0 +1,102 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ConnectKitProvider, getDefaultConfig } from "../connectkit";
+import { isWeb } from "@multiplatform.one/platform";
+import type { PropsWithChildren } from "react";
+import { useMemo } from "react";
+import type { Chain } from "viem";
+import { WagmiProvider, createConfig, http } from "wagmi";
+import { createMockConnector } from "./mockConnector";
+import { type Web3Config, Web3ConfigContext, defaultChains } from "./walletConfig";
+
+export interface WalletProviderProps extends PropsWithChildren {
+  config: Web3Config;
+  queryClient?: QueryClient;
+}
+
+const defaultQueryClient = new QueryClient();
+
+// wagmi/WalletConnect Core must be initialized exactly once per process. useMemo
+// only dedupes within a single component instance, so a provider remount (e.g.
+// React StrictMode double-invoke, or a route transition) rebuilds the config and
+// re-inits WalletConnect ("WalletConnect Core is already initialized" Nx). Cache
+// the created config at module scope keyed by its inputs so it survives remounts.
+type WagmiConfigResult = ReturnType<typeof createConfig>;
+const wagmiConfigCache = new Map<string, WagmiConfigResult>();
+
+export function WalletProvider({
+  children,
+  config: web3Config,
+  queryClient = defaultQueryClient,
+}: WalletProviderProps) {
+  const {
+    walletConnectProjectId,
+    appName,
+    appDescription = "Connect your wallet",
+    appUrl = isWeb && typeof window !== "undefined" ? window.location.origin : "",
+    appIcon,
+    chains = defaultChains,
+    enableTestnets = false,
+    mockWallet = false,
+  } = web3Config;
+
+  const activeChains = useMemo(() => {
+    if (enableTestnets) {
+      return chains;
+    }
+    const filtered = chains.filter((chain) => !chain.testnet);
+    if (filtered.length === 0) {
+      return chains;
+    }
+    return filtered as unknown as readonly [Chain, ...Chain[]];
+  }, [chains, enableTestnets]);
+
+  const wagmiConfig = useMemo(() => {
+    const chainIds = activeChains.map((chain) => chain.id).join(",");
+    const cacheKey = JSON.stringify({
+      appName,
+      appDescription,
+      appUrl,
+      appIcon,
+      walletConnectProjectId,
+      chainIds,
+      mockWallet,
+    });
+    const cached = wagmiConfigCache.get(cacheKey);
+    if (cached) return cached;
+
+    const transports = Object.fromEntries(activeChains.map((chain) => [chain.id, http()]));
+
+    const defaultConfig = getDefaultConfig({
+      appName,
+      appDescription,
+      appUrl,
+      appIcon,
+      walletConnectProjectId,
+      chains: activeChains,
+      transports,
+    });
+
+    // E2E only: make the deterministic mock the first connector so headless
+    // sign-in (connectors[0]) needs no real wallet. Production leaves it off.
+    if (mockWallet) {
+      defaultConfig.connectors = [createMockConnector(), ...(defaultConfig.connectors ?? [])];
+    }
+
+    const created = createConfig(defaultConfig);
+    wagmiConfigCache.set(cacheKey, created);
+    return created;
+  }, [appName, appDescription, appUrl, appIcon, walletConnectProjectId, activeChains, mockWallet]);
+
+  return (
+    <Web3ConfigContext.Provider value={web3Config}>
+      <WagmiProvider config={wagmiConfig}>
+        <QueryClientProvider client={queryClient}>
+          <ConnectKitProvider>{children}</ConnectKitProvider>
+        </QueryClientProvider>
+      </WagmiProvider>
+    </Web3ConfigContext.Provider>
+  );
+}
+
+export { defaultChains } from "./walletConfig";
+export { useWeb3Config, type Web3Config } from "./walletConfig";

package/src/providers/index.ts

@@ -0,0 +1,7 @@
+export {
+  WalletProvider,
+  useWeb3Config,
+  defaultChains,
+  type WalletProviderProps,
+  type Web3Config,
+} from "./WalletProvider";

package/src/providers/mockConnector.ts

@@ -0,0 +1,69 @@
+import { type Address, type Hex, hexToString } from "viem";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { createConnector } from "wagmi";
+
+/**
+ * A self-contained EVM wallet connector for END-TO-END TESTS ONLY, used by the
+ * web WalletProvider when `config.mockWallet === true` (production never sets
+ * that flag). Backed by an ephemeral runtime key (no secret shipped) and
+ * produces REAL, verifiable signatures, so a headless browser can exercise the
+ * whole connect → sign → SIWE → Keycloak round-trip with no MetaMask /
+ * WalletConnect / extension.
+ *
+ * This is the web `src/` analogue of webview/wiring/mockWallet.ts (which serves
+ * the isolated WebView build); kept here so the native import graph stays clean.
+ */
+export function createMockConnector() {
+  const account = privateKeyToAccount(generatePrivateKey());
+
+  const provider = {
+    request: async ({ method, params }: { method: string; params?: unknown }) => {
+      switch (method) {
+        case "eth_chainId":
+          return "0x1";
+        case "eth_accounts":
+        case "eth_requestAccounts":
+          return [account.address];
+        case "personal_sign": {
+          const [data] = (params as [Hex, Address]) ?? [];
+          return account.signMessage({ message: hexToString(data) });
+        }
+        default:
+          return null;
+      }
+    },
+    on: () => undefined,
+    removeListener: () => undefined,
+  };
+
+  return createConnector((config) => {
+    const connector = {
+      id: "mockWallet",
+      name: "Mock Wallet (E2E)",
+      type: "mock" as const,
+      async getProvider() {
+        return provider;
+      },
+      async connect() {
+        config.emitter.emit("change", { accounts: [account.address], chainId: 1 });
+        return { accounts: [account.address] as readonly Address[], chainId: 1 };
+      },
+      async disconnect() {
+        config.emitter.emit("disconnect");
+      },
+      async getAccounts() {
+        return [account.address] as readonly Address[];
+      },
+      async getChainId() {
+        return 1;
+      },
+      async isAuthorized() {
+        return true;
+      },
+      onAccountsChanged() {},
+      onChainChanged() {},
+      onDisconnect() {},
+    };
+    return connector as unknown as ReturnType<Parameters<typeof createConnector>[0]>;
+  });
+}

package/src/providers/native/deepLink.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { parseWalletReturn, shouldOpenExternally } from "./deepLink";
+
+describe("shouldOpenExternally", () => {
+  it("opens wallet custom schemes externally", () => {
+    expect(shouldOpenExternally("wc:7f6e...@2?relay-protocol=irn&symKey=ab")).toBe(true);
+    expect(shouldOpenExternally("metamask://wc?uri=wc%3A...")).toBe(true);
+    expect(shouldOpenExternally("phantom://v1/connect?app_url=...")).toBe(true);
+    expect(shouldOpenExternally("ethereum:0xabc")).toBe(true);
+  });
+
+  it("opens known wallet universal links externally", () => {
+    expect(shouldOpenExternally("https://metamask.app.link/wc?uri=wc%3A...")).toBe(true);
+    expect(shouldOpenExternally("https://link.trustwallet.com/wc?uri=...")).toBe(true);
+    expect(shouldOpenExternally("https://phantom.app/ul/v1/connect")).toBe(true);
+  });
+
+  it("keeps internal / non-wallet navigations in the WebView", () => {
+    expect(shouldOpenExternally("file:///path/webview.html")).toBe(false);
+    expect(shouldOpenExternally("https://fonts.googleapis.com/css2?family=Inter")).toBe(false);
+    expect(shouldOpenExternally("about:blank")).toBe(false);
+    expect(shouldOpenExternally("data:text/html,<p>hi</p>")).toBe(false);
+    expect(shouldOpenExternally("https://api.mainnet-beta.solana.com")).toBe(false);
+  });
+});
+
+describe("parseWalletReturn", () => {
+  it("extracts query params from a return url", () => {
+    expect(parseWalletReturn("mpoapp://wallet-return?address=0x1&signature=0xab")).toEqual({
+      address: "0x1",
+      signature: "0xab",
+    });
+  });
+
+  it("handles a custom-scheme url with no query", () => {
+    expect(parseWalletReturn("mpoapp://wallet-return")).toEqual({});
+  });
+
+  it("returns null for garbage", () => {
+    expect(parseWalletReturn("not a url at all %%%")).toBeNull();
+  });
+});

package/src/providers/native/deepLink.ts

@@ -0,0 +1,62 @@
+/**
+ * Wallet hand-off URL classification for the native WebView. The WebView loads
+ * trusted local content (file://); when its WalletConnect/ConnectKit flow tries to
+ * open a wallet app it navigates to a wallet custom-scheme or universal link —
+ * those must be handed to the OS via Linking.openURL, not loaded in the WebView.
+ */
+
+const WALLET_SCHEMES = new Set([
+  "wc",
+  "ethereum",
+  "metamask",
+  "rainbow",
+  "trust",
+  "phantom",
+  "solana",
+  "cbwallet",
+  "ledgerlive",
+  "zerion",
+  "rabby",
+  "okx",
+  "imtokenv2",
+  "wallet",
+]);
+
+const WALLET_UNIVERSAL_HOSTS = [
+  "metamask.app.link",
+  "link.trustwallet.com",
+  "phantom.app",
+  "rnbwapp.com",
+  "go.cb-w.com",
+  "ledger.com",
+];
+
+/** True when a WebView navigation should be opened in an external wallet app. */
+export function shouldOpenExternally(url: string): boolean {
+  const scheme = url.slice(0, Math.max(0, url.indexOf(":"))).toLowerCase();
+  if (!scheme) return false;
+  if (WALLET_SCHEMES.has(scheme)) return true;
+  if (scheme === "https" || scheme === "http") {
+    try {
+      const host = new URL(url).hostname.toLowerCase();
+      return WALLET_UNIVERSAL_HOSTS.some((h) => host === h || host.endsWith(`.${h}`));
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Parse the query params of an inbound app-link return (e.g. from a wallet redirect). */
+export function parseWalletReturn(url: string): Record<string, string> | null {
+  try {
+    const parsed = new URL(url);
+    const out: Record<string, string> = {};
+    parsed.searchParams.forEach((value, key) => {
+      out[key] = value;
+    });
+    return out;
+  } catch {
+    return null;
+  }
+}

package/src/providers/native/inject.spec.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { buildConfigInjection, buildInjectScript } from "./inject";
+
+interface FakeWindow {
+  __bridgeReceive?: (raw: string) => void;
+  __web3Config?: unknown;
+}
+
+const root = globalThis as { window?: FakeWindow };
+
+function setWindow(win: FakeWindow) {
+  root.window = win;
+}
+
+afterEach(() => {
+  root.window = undefined;
+});
+
+describe("buildInjectScript", () => {
+  it("round-trips a plain message through eval", () => {
+    const received: string[] = [];
+    setWindow({ __bridgeReceive: (s) => received.push(s) });
+    const raw = JSON.stringify({ id: "1", ns: "evm", kind: "req", method: "eth_chainId" });
+    // eslint-disable-next-line no-eval
+    (0, eval)(buildInjectScript(raw));
+    expect(received).toEqual([raw]);
+  });
+
+  it("survives quotes, newlines, backslashes and </script>", () => {
+    const received: string[] = [];
+    setWindow({ __bridgeReceive: (s) => received.push(s) });
+    const raw = 'he said "hi"\nline2\\end </script>';
+    // eslint-disable-next-line no-eval
+    (0, eval)(buildInjectScript(raw));
+    expect(received).toEqual([raw]);
+  });
+
+  it("no-ops safely if the receiver is not installed yet", () => {
+    setWindow({});
+    // eslint-disable-next-line no-eval
+    expect(() => (0, eval)(buildInjectScript("{}"))).not.toThrow();
+  });
+});
+
+describe("buildConfigInjection", () => {
+  it("sets window.__web3Config to the config object", () => {
+    setWindow({});
+    const config = { walletConnectProjectId: "pid", appName: "app", mockWallet: true };
+    // eslint-disable-next-line no-eval
+    (0, eval)(buildConfigInjection(config));
+    expect(root.window?.__web3Config).toEqual(config);
+  });
+});

package/src/providers/native/inject.ts

@@ -0,0 +1,20 @@
+import type { Web3Config } from "../walletConfig";
+
+/**
+ * Build the JS the native side runs inside the WebView (via `injectJavaScript`)
+ * to deliver one inbound bridge message. The raw string is embedded with
+ * JSON.stringify so quotes/newlines/backslashes survive intact. The trailing
+ * `true;` is required by react-native-webview's injectJavaScript contract.
+ */
+export function buildInjectScript(raw: string): string {
+  return `window.__bridgeReceive && window.__bridgeReceive(${JSON.stringify(raw)});true;`;
+}
+
+/**
+ * Build the JS injected *before* the WebView content loads
+ * (`injectedJavaScriptBeforeContentLoaded`) to publish the host config as
+ * `window.__web3Config`, which the bundled app reads at startup.
+ */
+export function buildConfigInjection(config: Web3Config & { mockWallet?: boolean }): string {
+  return `window.__web3Config = ${JSON.stringify(config)};true;`;
+}

package/src/providers/native/visibility.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { initialVisibility, nextVisibility } from "./visibility";
+
+describe("nextVisibility", () => {
+  it("opens the sheet on modalOpen", () => {
+    expect(nextVisibility(initialVisibility, "modalOpen")).toEqual({ sheetOpen: true });
+  });
+
+  it("closes the sheet on modalClose", () => {
+    expect(nextVisibility({ sheetOpen: true }, "modalClose")).toEqual({ sheetOpen: false });
+  });
+
+  it("ignores unrelated sys methods", () => {
+    const state = { sheetOpen: true };
+    expect(nextVisibility(state, "ready")).toBe(state);
+    expect(nextVisibility(state, "resync")).toBe(state);
+  });
+
+  it("returns the same reference when already in the target state (no needless re-render)", () => {
+    const open = { sheetOpen: true };
+    expect(nextVisibility(open, "modalOpen")).toBe(open);
+    const closed = { sheetOpen: false };
+    expect(nextVisibility(closed, "modalClose")).toBe(closed);
+  });
+});

package/src/providers/native/visibility.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure reducer mapping the WebView's `sys` lifecycle events to whether the native
+ * WebView sheet should be visible. The WebView emits `modalOpen` when ConnectKit /
+ * the wallet picker is showing (which the user must see) and `modalClose` when it
+ * dismisses; the rest of the time the WebView is kept mounted but hidden so the
+ * bridge stays alive.
+ */
+export interface WebViewVisibility {
+  sheetOpen: boolean;
+}
+
+export const initialVisibility: WebViewVisibility = { sheetOpen: false };
+
+export function nextVisibility(state: WebViewVisibility, sysMethod: string): WebViewVisibility {
+  switch (sysMethod) {
+    case "modalOpen":
+      return state.sheetOpen ? state : { sheetOpen: true };
+    case "modalClose":
+      return state.sheetOpen ? { sheetOpen: false } : state;
+    default:
+      return state;
+  }
+}