@multiplatform.one/web3 7.25.0 → 7.28.0

package/src/core/store.spec.ts

@@ -0,0 +1,973 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { deferred, memoryStorage, testDriver } from "../../tests/core/testDriver";
+import { defineWalletFamily } from "./family";
+import { createConnectionStore, defaultConnectionStorageKey } from "./store";
+import type { ChainClient } from "../clients/types";
+import type { ConnectionState, ConnectionStorage, DriverAccount } from "./types";
+
+const evmAccount = { address: "0x1111111111111111111111111111111111111111", chainId: 137 };
+const phantomAccount = {
+  address: "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
+  chainId: "solana:mainnet",
+};
+const solflareAccount = {
+  address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+  chainId: "solana:mainnet",
+};
+
+const message = { header: "wants you to sign in:", statement: null, chainId: null };
+
+function setup(
+  storage: ConnectionStorage | null | "platform" = memoryStorage(),
+  closeTimeout?: number,
+) {
+  const eth = testDriver(
+    "evm",
+    [
+      { id: "metaMask", name: "MetaMask" },
+      { id: "coinbase", name: "Coinbase Wallet" },
+    ],
+    { metaMask: evmAccount, coinbase: evmAccount },
+  );
+  const sol = testDriver(
+    "solana",
+    [
+      { id: "phantom", name: "Phantom" },
+      { id: "solflare", name: "Solflare" },
+    ],
+    { phantom: phantomAccount, solflare: solflareAccount },
+  );
+  const makeEth = vi.fn(() => eth);
+  const makeSol = vi.fn(() => sol);
+  const store = createConnectionStore({
+    storage: storage === "platform" ? undefined : storage,
+    closeTimeout,
+    families: [
+      defineWalletFamily({
+        id: "eth",
+        label: "Ethereum",
+        aliases: ["evm"],
+        message,
+        driver: makeEth,
+      }),
+      defineWalletFamily({
+        id: "sol",
+        label: "Solana",
+        aliases: ["solana"],
+        message,
+        driver: makeSol,
+      }),
+      defineWalletFamily({ id: "gpg", label: "GPG", message, connectionless: true }),
+    ],
+  });
+  const seen: ConnectionState[] = [];
+  store.subscribe(() => seen.push(store.getState()));
+  return { store, eth, sol, makeEth, makeSol, seen };
+}
+
+/**
+ * Stores built on the same wallets, as a remount shares them: the same driver
+ * instances, or with `wrap`, a fresh driver per store over the same wallet.
+ */
+function sharedDrivers(storage: ConnectionStorage = memoryStorage(), wrap = false) {
+  const eth = testDriver("evm", [{ id: "metaMask", name: "MetaMask" }], { metaMask: evmAccount });
+  const sol = testDriver(
+    "solana",
+    [
+      { id: "phantom", name: "Phantom" },
+      { id: "solflare", name: "Solflare" },
+    ],
+    { phantom: phantomAccount, solflare: solflareAccount },
+  );
+  const make = () =>
+    createConnectionStore({
+      storage,
+      families: [
+        defineWalletFamily({
+          id: "eth",
+          label: "Ethereum",
+          message,
+          driver: () => (wrap ? { ...eth } : eth),
+        }),
+        defineWalletFamily({
+          id: "sol",
+          label: "Solana",
+          message,
+          driver: () => (wrap ? { ...sol } : sol),
+        }),
+      ],
+    });
+  return { eth, sol, make };
+}
+
+const saved = (family: string, connectorId: string) => ({
+  [defaultConnectionStorageKey]: JSON.stringify({ family, connectorId }),
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("createConnectionStore", () => {
+  it("starts disconnected and asks no driver", () => {
+    const { store, makeEth, makeSol } = setup();
+    expect(store.getState()).toEqual({
+      status: "disconnected",
+      family: null,
+      connector: null,
+      address: null,
+      chainId: null,
+      client: null,
+    });
+    expect(makeEth).not.toHaveBeenCalled();
+    expect(makeSol).not.toHaveBeenCalled();
+  });
+
+  it("connect goes through connecting to connected and remembers {family, connectorId}", async () => {
+    const storage = memoryStorage();
+    const { store, sol, seen } = setup(storage);
+    const state = await store.connect("sol", "phantom");
+    expect(seen.map((entry) => entry.status)).toEqual(["connecting", "connected"]);
+    expect(seen[0]).toMatchObject({ family: "sol", connector: { id: "phantom", name: "Phantom" } });
+    expect(state).toMatchObject({
+      status: "connected",
+      family: "sol",
+      connector: { id: "phantom", name: "Phantom" },
+      address: phantomAccount.address,
+      chainId: "solana:mainnet",
+    });
+    expect(state.client?.address).toBe(phantomAccount.address);
+    expect(await state.client?.signMessage("hi")).toBe("solana:hi");
+    expect(sol.connect).toHaveBeenCalledWith("phantom", undefined);
+    expect(JSON.parse(storage.map.get(defaultConnectionStorageKey) ?? "")).toEqual({
+      family: "sol",
+      connectorId: "phantom",
+    });
+  });
+
+  it("an alias names the family and the store records the family id", async () => {
+    const storage = memoryStorage();
+    const { store } = setup(storage);
+    expect((await store.connect("evm", "metaMask")).family).toBe("eth");
+    expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+      JSON.stringify({ family: "eth", connectorId: "metaMask" }),
+    );
+  });
+
+  it("passes connect options, such as onDisplayUri, to the driver", async () => {
+    const { store, eth } = setup();
+    const onDisplayUri = vi.fn();
+    await store.connect("eth", "metaMask", { onDisplayUri });
+    expect(eth.connect).toHaveBeenCalledWith("metaMask", { onDisplayUri });
+  });
+
+  it("disconnect closes the driver, clears the state and forgets the connection", async () => {
+    const storage = memoryStorage();
+    const { store, eth } = setup(storage);
+    await store.connect("eth", "metaMask");
+    await store.disconnect();
+    expect(eth.disconnect).toHaveBeenCalledTimes(1);
+    expect(store.getState().status).toBe("disconnected");
+    expect(store.getState().client).toBeNull();
+    expect(storage.map.has(defaultConnectionStorageKey)).toBe(false);
+    expect(eth.listeners.size).toBe(0);
+  });
+
+  it("one active connection: connecting another family closes the first and ignores it after", async () => {
+    const storage = memoryStorage();
+    const { store, eth, sol } = setup(storage);
+    await store.connect("eth", "metaMask");
+    await store.connect("sol", "solflare");
+    expect(eth.disconnect).toHaveBeenCalledTimes(1);
+    expect(store.getState()).toMatchObject({ family: "sol", address: solflareAccount.address });
+    eth.emit({ status: "connected", connectorId: "metaMask", account: evmAccount });
+    expect(store.getState()).toMatchObject({ family: "sol", address: solflareAccount.address });
+    expect(eth.listeners.size).toBe(0);
+    expect(sol.listeners.size).toBe(1);
+    expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+      JSON.stringify({ family: "sol", connectorId: "solflare" }),
+    );
+  });
+
+  it("follows the active driver's account and chain changes", async () => {
+    const { store, eth } = setup();
+    await store.connect("eth", "metaMask");
+    const next = { address: "0x2222222222222222222222222222222222222222", chainId: 8453 };
+    eth.emit({ status: "connected", connectorId: "metaMask", account: next });
+    expect(store.getState()).toMatchObject({ status: "connected", ...next });
+    expect(store.getState().client?.address).toBe(next.address);
+    eth.emit({ status: "connected", connectorId: "coinbase", account: next });
+    expect(store.getState().connector).toEqual({ id: "coinbase", name: "Coinbase Wallet" });
+  });
+
+  it("a disconnect from the wallet side clears the state and keeps the record for a restore", async () => {
+    const storage = memoryStorage();
+    const { store, sol } = setup(storage);
+    await store.connect("sol", "phantom");
+    sol.emit({ status: "reconnecting", connectorId: "phantom", account: null });
+    expect(store.getState().status).toBe("connected");
+    sol.emit({ status: "disconnected", connectorId: null, account: null });
+    expect(store.getState().status).toBe("disconnected");
+    expect(sol.listeners.size).toBe(0);
+    expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+      JSON.stringify({ family: "sol", connectorId: "phantom" }),
+    );
+    expect((await store.reconnect()).family).toBe("sol");
+    expect(sol.reconnect).toHaveBeenCalledWith("phantom");
+  });
+
+  it("a connector switch inside the active driver is remembered", async () => {
+    const storage = memoryStorage();
+    const { store, eth } = setup(storage);
+    await store.connect("eth", "metaMask");
+    eth.emit({ status: "connected", connectorId: "coinbase", account: evmAccount });
+    expect(store.getState().connector?.id).toBe("coinbase");
+    await vi.waitFor(() =>
+      expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+        JSON.stringify({ family: "eth", connectorId: "coinbase" }),
+      ),
+    );
+  });
+
+  it("a repeated driver event changes nothing and builds no new client", async () => {
+    const { store, eth, seen } = setup();
+    await store.connect("eth", "metaMask");
+    const before = store.getState();
+    const calls = eth.client.mock.calls.length;
+    const notified = seen.length;
+    eth.emit({ status: "connected", connectorId: "metaMask", account: evmAccount });
+    expect(store.getState()).toBe(before);
+    expect(eth.client.mock.calls.length).toBe(calls);
+    expect(seen.length).toBe(notified);
+  });
+
+  it("an async client lands once built, and a late one for a closed connection does not", async () => {
+    const { store, eth } = setup();
+    const built = deferred<ChainClient | null>();
+    eth.client.mockReturnValueOnce(built.promise);
+    const state = await store.connect("eth", "metaMask");
+    expect(state).toMatchObject({ status: "connected", client: null });
+    const client = {
+      family: "evm",
+      address: evmAccount.address,
+      capabilities: [],
+      signMessage: async () => "0x",
+    } as ChainClient;
+    built.resolve(client);
+    await vi.waitFor(() => expect(store.getState().client).toBe(client));
+
+    const late = deferred<ChainClient | null>();
+    eth.client.mockReturnValueOnce(late.promise);
+    eth.emit({
+      status: "connected",
+      connectorId: "metaMask",
+      account: { ...evmAccount, chainId: 1 },
+    });
+    expect(store.getState()).toMatchObject({ chainId: 1, client: null });
+    await store.disconnect();
+    late.resolve(client);
+    await Promise.resolve();
+    expect(store.getState()).toMatchObject({ status: "disconnected", client: null });
+  });
+
+  it("a refused connect leaves the store disconnected and remembers nothing", async () => {
+    const storage = memoryStorage();
+    const { store, eth } = setup(storage);
+    eth.connect.mockRejectedValueOnce(new Error("User rejected the request."));
+    await expect(store.connect("eth", "metaMask")).rejects.toThrow("User rejected");
+    expect(store.getState().status).toBe("disconnected");
+    expect(storage.map.size).toBe(0);
+  });
+
+  describe("client()", () => {
+    it("asks the driver again for a client whose build failed, and keeps the one it gets", async () => {
+      const { store, sol } = setup();
+      const real = sol.client.getMockImplementation()!;
+      sol.client.mockImplementationOnce(() => Promise.reject(new Error("transient")) as never);
+      await store.connect("sol", "phantom");
+      await Promise.resolve();
+      expect(store.getState().client).toBeNull();
+
+      const client = await store.client();
+
+      expect(client).toMatchObject({ family: "solana", address: phantomAccount.address });
+      expect(store.getState().client).toBe(client);
+      expect(await store.client()).toBe(client);
+      expect(sol.client).toHaveBeenCalledTimes(2);
+      sol.client.mockImplementation(real);
+    });
+
+    it("is null with nothing connected, and rejects with the driver's error", async () => {
+      const { store, sol } = setup();
+      expect(await store.client()).toBeNull();
+      sol.client.mockImplementation(() => Promise.reject(new Error("wallet busy")) as never);
+      await store.connect("sol", "phantom");
+      await expect(store.client()).rejects.toThrow(/wallet busy/);
+    });
+  });
+
+  describe("a silent connect", () => {
+    it("takes a connection the wallet already granted through reconnect, with no prompt", async () => {
+      const storage = memoryStorage();
+      const { store, eth, sol, seen } = setup(storage);
+      await store.connect("eth", "metaMask");
+      const state = await store.connect("sol", "phantom", { silent: true });
+      expect(sol.reconnect).toHaveBeenCalledWith("phantom");
+      expect(sol.connect).not.toHaveBeenCalled();
+      expect(eth.disconnect).toHaveBeenCalledTimes(1);
+      expect(state).toMatchObject({
+        status: "connected",
+        family: "sol",
+        address: phantomAccount.address,
+      });
+      expect(seen.map((entry) => entry.status)).toContain("connecting");
+      expect(JSON.parse(storage.map.get(defaultConnectionStorageKey) ?? "")).toEqual({
+        family: "sol",
+        connectorId: "phantom",
+      });
+    });
+
+    it("rejects and stays disconnected when the wallet has not granted it, remembering nothing", async () => {
+      const storage = memoryStorage();
+      const { store, sol } = setup(storage);
+      sol.reconnect.mockResolvedValueOnce(null);
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /phantom.*not authorised/,
+      );
+      expect(sol.connect).not.toHaveBeenCalled();
+      expect(store.getState().status).toBe("disconnected");
+      expect(storage.map.size).toBe(0);
+    });
+
+    it("a refused one closes nothing: what the driver holds stays with whoever opened it", async () => {
+      const { store, sol } = setup();
+      sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+      sol.reconnect.mockRejectedValueOnce(new Error("no such connector"));
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /no such connector/,
+      );
+      sol.reconnect.mockResolvedValueOnce(null);
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /not authorised/,
+      );
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      expect(sol.getState().status).toBe("connected");
+    });
+
+    it("never hands the silent flag to the driver", async () => {
+      const { store, eth } = setup();
+      const onDisplayUri = vi.fn();
+      await store.connect("eth", "metaMask", { onDisplayUri, silent: false });
+      expect(eth.connect).toHaveBeenCalledWith("metaMask", { onDisplayUri });
+    });
+  });
+
+  it("refuses a connectionless family and an unregistered one", async () => {
+    const { store } = setup();
+    await expect(store.connect("gpg", "key")).rejects.toThrow(/connectionless/);
+    await expect(store.connect("sui", "slush")).rejects.toThrow(/not registered.*eth, sol, gpg/);
+    expect(store.getState().status).toBe("disconnected");
+  });
+
+  it("lists every connectable family's connectors in family order", () => {
+    const { store } = setup();
+    expect(store.connectors().map((entry) => `${entry.family}:${entry.connector.id}`)).toEqual([
+      "eth:metaMask",
+      "eth:coinbase",
+      "sol:phantom",
+      "sol:solflare",
+    ]);
+  });
+
+  it("keeps one connector list until a driver announces a change", () => {
+    const { store, eth } = setup();
+    const first = store.connectors();
+    expect(store.connectors()).toBe(first);
+    const changed = vi.fn();
+    const unsubscribe = store.subscribeConnectors(changed);
+    eth.announce([
+      { id: "metaMask", name: "MetaMask" },
+      { id: "coinbase", name: "Coinbase Wallet" },
+      { id: "io.rabby", name: "Rabby", installed: true },
+    ]);
+    expect(changed).toHaveBeenCalledTimes(1);
+    const second = store.connectors();
+    expect(second).not.toBe(first);
+    expect(second.map((entry) => entry.connector.id)).toContain("io.rabby");
+    expect(store.connectors()).toBe(second);
+    unsubscribe();
+    expect(eth.connectorListeners.size).toBe(0);
+    eth.announce([]);
+    expect(changed).toHaveBeenCalledTimes(1);
+  });
+
+  describe("reconnect", () => {
+    it("restores the saved connection through the saved family's driver only", async () => {
+      const { store, eth, sol, makeEth, seen } = setup(memoryStorage(saved("sol", "phantom")));
+      const state = await store.reconnect();
+      expect(seen.map((entry) => entry.status)).toEqual(["reconnecting", "connected"]);
+      expect(state).toMatchObject({
+        status: "connected",
+        family: "sol",
+        connector: { id: "phantom", name: "Phantom" },
+        address: phantomAccount.address,
+      });
+      expect(sol.reconnect).toHaveBeenCalledWith("phantom");
+      expect(sol.connect).not.toHaveBeenCalled();
+      expect(makeEth).not.toHaveBeenCalled();
+      expect(eth.reconnect).not.toHaveBeenCalled();
+    });
+
+    it("never restores from two drivers: a second driver's account is ignored", async () => {
+      const { store, eth } = setup(memoryStorage(saved("sol", "phantom")));
+      store.connectors();
+      const restoring = store.reconnect();
+      eth.emit({ status: "connected", connectorId: "metaMask", account: evmAccount });
+      await restoring;
+      eth.emit({ status: "connected", connectorId: "metaMask", account: evmAccount });
+      expect(store.getState()).toMatchObject({ family: "sol", address: phantomAccount.address });
+      expect(eth.reconnect).not.toHaveBeenCalled();
+      expect(eth.listeners.size).toBe(0);
+    });
+
+    it("concurrent calls share one attempt", async () => {
+      const { store, sol } = setup(memoryStorage(saved("sol", "phantom")));
+      const [first, second] = await Promise.all([store.reconnect(), store.reconnect()]);
+      expect(first).toBe(second);
+      expect(sol.reconnect).toHaveBeenCalledTimes(1);
+      expect(await store.reconnect()).toBe(first);
+      expect(sol.reconnect).toHaveBeenCalledTimes(1);
+    });
+
+    it("with nothing saved asks no driver", async () => {
+      const { store, makeEth, makeSol } = setup(memoryStorage());
+      expect((await store.reconnect()).status).toBe("disconnected");
+      expect(makeEth).not.toHaveBeenCalled();
+      expect(makeSol).not.toHaveBeenCalled();
+    });
+
+    it("forgets a connector that is no longer authorised", async () => {
+      const storage = memoryStorage(saved("eth", "metaMask"));
+      const { store, eth } = setup(storage);
+      eth.reconnect.mockResolvedValueOnce(null);
+      expect((await store.reconnect()).status).toBe("disconnected");
+      expect(storage.map.has(defaultConnectionStorageKey)).toBe(false);
+    });
+
+    it("keeps the saved connection when the restore fails transiently", async () => {
+      const storage = memoryStorage(saved("eth", "metaMask"));
+      const { store, eth } = setup(storage);
+      eth.reconnect.mockRejectedValueOnce(new Error("provider not ready"));
+      expect((await store.reconnect()).status).toBe("disconnected");
+      expect(storage.map.has(defaultConnectionStorageKey)).toBe(true);
+    });
+
+    it("leaves alone a saved family this app does not register or cannot connect", async () => {
+      for (const family of ["sui", "gpg"]) {
+        const storage = memoryStorage(saved(family, "whatever"));
+        const { store, makeEth, makeSol } = setup(storage);
+        expect((await store.reconnect()).status).toBe("disconnected");
+        expect(storage.map.has(defaultConnectionStorageKey)).toBe(true);
+        expect(makeEth).not.toHaveBeenCalled();
+        expect(makeSol).not.toHaveBeenCalled();
+      }
+    });
+
+    it("ignores a malformed saved record", async () => {
+      for (const raw of ["not json", "null", '{"family":"sol"}', '["sol","phantom"]']) {
+        const { store, makeSol } = setup(memoryStorage({ [defaultConnectionStorageKey]: raw }));
+        expect((await store.reconnect()).status).toBe("disconnected");
+        expect(makeSol).not.toHaveBeenCalled();
+      }
+    });
+
+    it("a restore whose driver cannot be made rejects once, with no unhandled rejection", async () => {
+      const unhandled: unknown[] = [];
+      const onUnhandled = (reason: unknown) => unhandled.push(reason);
+      process.on("unhandledRejection", onUnhandled);
+      try {
+        const store = createConnectionStore({
+          storage: memoryStorage(saved("eth", "metaMask")),
+          families: [
+            defineWalletFamily({
+              id: "eth",
+              label: "Ethereum",
+              message,
+              driver: () => {
+                throw new Error("no injected provider");
+              },
+            }),
+          ],
+        });
+        await expect(store.reconnect()).rejects.toThrow("no injected provider");
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        expect(unhandled).toEqual([]);
+      } finally {
+        process.off("unhandledRejection", onUnhandled);
+      }
+    });
+
+    it("does nothing while a connection is open", async () => {
+      const { store, sol } = setup(memoryStorage(saved("sol", "phantom")));
+      await store.connect("eth", "metaMask");
+      expect((await store.reconnect()).family).toBe("eth");
+      expect(sol.reconnect).not.toHaveBeenCalled();
+    });
+
+    it("a user connect during the restore wins, and the late restore is closed", async () => {
+      const storage = memoryStorage(saved("sol", "phantom"));
+      const { store, sol } = setup(storage);
+      const late = deferred<DriverAccount | null>();
+      sol.reconnect.mockReturnValueOnce(late.promise);
+      const restoring = store.reconnect();
+      await vi.waitFor(() => expect(sol.reconnect).toHaveBeenCalled());
+      await store.connect("eth", "metaMask");
+      late.resolve(phantomAccount);
+      await restoring;
+      expect(store.getState()).toMatchObject({ family: "eth", address: evmAccount.address });
+      expect(sol.disconnect).toHaveBeenCalledTimes(1);
+      expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+        JSON.stringify({ family: "eth", connectorId: "metaMask" }),
+      );
+    });
+  });
+
+  describe("superseded connects", () => {
+    it("a disconnect while connecting wins, and the late wallet is closed", async () => {
+      const storage = memoryStorage();
+      const { store, eth } = setup(storage);
+      const late = deferred<DriverAccount>();
+      eth.connect.mockReturnValueOnce(late.promise);
+      const connecting = store.connect("eth", "metaMask");
+      await vi.waitFor(() => expect(eth.connect).toHaveBeenCalled());
+      expect(store.getState().status).toBe("connecting");
+      await store.disconnect();
+      late.resolve(evmAccount);
+      await expect(connecting).rejects.toThrow(/superseded/);
+      expect(store.getState().status).toBe("disconnected");
+      expect(eth.disconnect).toHaveBeenCalledTimes(1);
+      expect(storage.map.size).toBe(0);
+    });
+
+    it("the later of two connects on one driver wins, and only the stale connector is closed", async () => {
+      const { store, sol } = setup();
+      const first = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise);
+      const phantom = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      const solflare = store.connect("sol", "solflare");
+      first.resolve(phantomAccount);
+      await expect(phantom).rejects.toThrow(/superseded/);
+      expect((await solflare).connector?.id).toBe("solflare");
+      expect(sol.disconnect).toHaveBeenCalledTimes(1);
+      expect(sol.disconnect).toHaveBeenCalledWith("phantom");
+      expect(store.getState()).toMatchObject({ family: "sol", address: solflareAccount.address });
+      expect(sol.getState().connectorId).toBe("solflare");
+    });
+
+    it("a superseded connect's slow close does not wipe the winner's record", async () => {
+      const storage = memoryStorage();
+      const { store, eth, sol } = setup(storage);
+      await store.connect("eth", "metaMask");
+      const slowClose = deferred<void>();
+      eth.disconnect.mockReturnValueOnce(slowClose.promise);
+      const first = store.connect("sol", "phantom");
+      const second = store.connect("sol", "solflare");
+      expect((await second).connector?.id).toBe("solflare");
+      slowClose.resolve();
+      await expect(first).rejects.toThrow(/superseded/);
+      expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+        JSON.stringify({ family: "sol", connectorId: "solflare" }),
+      );
+      expect(sol.connect).toHaveBeenCalledTimes(1);
+    });
+
+    it("a stale connection left for a winner that is then refused gets closed", async () => {
+      const { store, sol } = setup();
+      const first = deferred<DriverAccount>();
+      const second = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise);
+      const a = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      const b = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(2));
+      sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+      first.resolve(phantomAccount);
+      await expect(a).rejects.toThrow(/superseded/);
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      second.reject(new Error("User rejected the request."));
+      await expect(b).rejects.toThrow(/User rejected/);
+      expect(store.getState().status).toBe("disconnected");
+      expect(sol.disconnect).toHaveBeenCalledTimes(1);
+      expect(sol.getState().account).toBeNull();
+    });
+
+    it("a connect right after a disconnect waits for the close on that driver", async () => {
+      const storage = memoryStorage();
+      const { store, eth } = setup(storage);
+      await store.connect("eth", "metaMask");
+      const slowClose = deferred<void>();
+      eth.disconnect.mockImplementationOnce(async () => {
+        await slowClose.promise;
+        eth.emit({ status: "disconnected", connectorId: null, account: null });
+      });
+      const closing = store.disconnect();
+      const connecting = store.connect("eth", "coinbase");
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      expect(eth.connect).toHaveBeenCalledTimes(1);
+      slowClose.resolve();
+      await closing;
+      const state = await connecting;
+      expect(eth.connect).toHaveBeenCalledTimes(2);
+      expect(state).toMatchObject({ status: "connected", connector: { id: "coinbase" } });
+      expect(store.getState().status).toBe("connected");
+      expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+        JSON.stringify({ family: "eth", connectorId: "coinbase" }),
+      );
+    });
+
+    it.each([
+      ["a disconnect", (store: ReturnType<typeof setup>["store"]) => store.disconnect()],
+      [
+        "a connect on another family",
+        async (store: ReturnType<typeof setup>["store"]) => {
+          await store.connect("eth", "metaMask");
+        },
+      ],
+    ])(
+      "a stale connection left for a winner that loses to %s and is then refused gets closed",
+      async (_, supersede) => {
+        const { store, sol } = setup();
+        const first = deferred<DriverAccount>();
+        const second = deferred<DriverAccount>();
+        sol.connect.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise);
+        const a = store.connect("sol", "phantom");
+        await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+        const b = store.connect("sol", "phantom");
+        await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(2));
+        sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+        first.resolve(phantomAccount);
+        await expect(a).rejects.toThrow(/superseded/);
+        await supersede(store);
+        second.reject(new Error("User rejected the request."));
+        await expect(b).rejects.toThrow(/User rejected/);
+        expect(sol.disconnect).toHaveBeenCalledTimes(1);
+        expect(sol.getState().account).toBeNull();
+      },
+    );
+
+    it("a superseded connect approved late is not taken for a connector switch", async () => {
+      const storage = memoryStorage();
+      const { store, sol } = setup(storage);
+      const first = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise);
+      const a = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      expect((await store.connect("sol", "solflare")).connector?.id).toBe("solflare");
+      sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+      expect(store.getState()).toMatchObject({
+        connector: { id: "solflare" },
+        address: solflareAccount.address,
+      });
+      first.resolve(phantomAccount);
+      await expect(a).rejects.toThrow(/superseded/);
+      expect(sol.disconnect).toHaveBeenCalledWith("phantom");
+      // The test driver holds one connection, so approving phantom dropped solflare.
+      expect(store.getState().status).toBe("disconnected");
+      expect(storage.map.get(defaultConnectionStorageKey)).toBe(
+        JSON.stringify({ family: "sol", connectorId: "solflare" }),
+      );
+    });
+
+    it("a refused attempt leaves alone a connection it cannot tell apart from the winner's", async () => {
+      const { store, sol } = setup();
+      const first = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise);
+      const a = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      await store.connect("sol", "solflare");
+      sol.emit({ status: "connected", connectorId: null, account: solflareAccount });
+      first.reject(new Error("User rejected the request."));
+      await expect(a).rejects.toThrow(/User rejected/);
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      expect(store.getState()).toMatchObject({
+        status: "connected",
+        connector: { id: "solflare" },
+      });
+    });
+
+    it("a close that never settles does not wedge the driver", async () => {
+      const { store, eth } = setup(memoryStorage(), 20);
+      await store.connect("eth", "metaMask");
+      eth.disconnect.mockReturnValueOnce(new Promise<void>(() => {}));
+      await store.disconnect();
+      const state = await store.connect("eth", "coinbase");
+      expect(state).toMatchObject({ status: "connected", connector: { id: "coinbase" } });
+      expect(eth.connect).toHaveBeenCalledTimes(2);
+    });
+
+    it.each([
+      [Number.NaN, false],
+      [-5, true],
+      [Number.POSITIVE_INFINITY, false],
+    ])(
+      "closeTimeout %s: a 50 ms disconnect is awaited unless the timeout is negative",
+      async (closeTimeout, early) => {
+        const { store, eth } = setup(memoryStorage(), closeTimeout);
+        await store.connect("eth", "metaMask");
+        eth.disconnect.mockReturnValueOnce(new Promise<void>((resolve) => setTimeout(resolve, 50)));
+        let done = false;
+        const disconnecting = store.disconnect().then(() => {
+          done = true;
+        });
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        expect(done).toBe(early);
+        await disconnecting;
+      },
+    );
+
+    it("a reconnect call while connecting leaves the connect alone", async () => {
+      const { store, eth, sol } = setup(memoryStorage(saved("sol", "phantom")));
+      const connecting = store.connect("eth", "metaMask");
+      expect((await store.reconnect()).status).toBe("connecting");
+      await connecting;
+      expect(sol.reconnect).not.toHaveBeenCalled();
+      expect(eth.connect).toHaveBeenCalledTimes(1);
+      expect(store.getState().family).toBe("eth");
+    });
+  });
+
+  describe("storage", () => {
+    it("uses localStorage when the platform has one", async () => {
+      const local = memoryStorage();
+      vi.stubGlobal("localStorage", local);
+      const { store } = setup("platform");
+      await store.connect("sol", "phantom");
+      expect(local.setItem).toHaveBeenCalledWith(
+        defaultConnectionStorageKey,
+        JSON.stringify({ family: "sol", connectorId: "phantom" }),
+      );
+    });
+
+    it("null storage keeps nothing and restores nothing", async () => {
+      const { store, makeSol } = setup(null);
+      await store.connect("eth", "metaMask");
+      await store.disconnect();
+      expect((await store.reconnect()).status).toBe("disconnected");
+      expect(makeSol).not.toHaveBeenCalled();
+    });
+
+    it("a storage that throws costs only the restore", async () => {
+      const broken: ConnectionStorage = {
+        getItem: () => {
+          throw new Error("SecurityError");
+        },
+        setItem: () => Promise.reject(new Error("QuotaExceededError")),
+        removeItem: () => {
+          throw new Error("SecurityError");
+        },
+      };
+      const { store } = setup(broken);
+      expect((await store.reconnect()).status).toBe("disconnected");
+      expect((await store.connect("eth", "metaMask")).status).toBe("connected");
+      await store.disconnect();
+      expect(store.getState().status).toBe("disconnected");
+    });
+
+    it("honours a custom storage key", async () => {
+      const storage = memoryStorage();
+      const eth = testDriver("evm", [{ id: "metaMask", name: "MetaMask" }], {
+        metaMask: evmAccount,
+      });
+      const store = createConnectionStore({
+        storage,
+        storageKey: "app.wallet",
+        families: [
+          defineWalletFamily({ id: "eth", label: "Ethereum", message, driver: () => eth }),
+        ],
+      });
+      await store.connect("eth", "metaMask");
+      expect([...storage.map.keys()]).toEqual(["app.wallet"]);
+    });
+  });
+
+  it.each([
+    ["phantom", "rejects"],
+    [null, "rejects"],
+    ["phantom", "resolves"],
+  ] as const)(
+    "a stale attempt that settles after destroy closes nothing (driver reports %s, attempt %s)",
+    async (connectorId, outcome) => {
+      const { store, sol } = setup();
+      const first = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise);
+      const a = store.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      sol.emit({ status: "connected", connectorId, account: phantomAccount });
+      store.destroy();
+      if (outcome === "rejects") first.reject(new Error("User rejected the request."));
+      else first.resolve(phantomAccount);
+      await expect(a).rejects.toThrow(outcome === "rejects" ? /User rejected/ : /superseded/);
+      expect(sol.disconnect).not.toHaveBeenCalled();
+    },
+  );
+
+  it("an attempt disconnect() cancelled before destroy still closes its own connector", async () => {
+    const { store, sol } = setup();
+    const first = deferred<DriverAccount>();
+    sol.connect.mockReturnValueOnce(first.promise);
+    const a = store.connect("sol", "phantom");
+    await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+    await store.disconnect();
+    store.destroy();
+    sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+    first.resolve(phantomAccount);
+    await expect(a).rejects.toThrow(/superseded/);
+    expect(sol.disconnect).toHaveBeenCalledWith("phantom");
+    expect(sol.getState().account).toBeNull();
+  });
+
+  it("an attempt superseded before destroy leaves the connector the live attempt holds", async () => {
+    const { store, sol } = setup();
+    const first = deferred<DriverAccount>();
+    const second = deferred<DriverAccount>();
+    sol.connect.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise);
+    const a = store.connect("sol", "phantom");
+    await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+    const b = store.connect("sol", "phantom");
+    await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(2));
+    store.destroy();
+    sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+    first.resolve(phantomAccount);
+    second.resolve(phantomAccount);
+    await expect(a).rejects.toThrow(/superseded/);
+    await expect(b).rejects.toThrow(/superseded/);
+    expect(sol.disconnect).not.toHaveBeenCalled();
+  });
+
+  it("a store remounted on the same driver keeps its connection when the old restore lands", async () => {
+    const { sol, make } = sharedDrivers(memoryStorage(saved("sol", "phantom")));
+    const first = deferred<DriverAccount | null>();
+    sol.reconnect.mockReturnValueOnce(first.promise);
+    const unmounted = make();
+    const restoring = unmounted.reconnect();
+    await vi.waitFor(() => expect(sol.reconnect).toHaveBeenCalledTimes(1));
+    unmounted.destroy();
+    const remounted = make();
+    expect((await remounted.reconnect()).status).toBe("connected");
+    first.resolve(phantomAccount);
+    await restoring;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(sol.disconnect).not.toHaveBeenCalled();
+    expect(remounted.getState().status).toBe("connected");
+  });
+
+  it("a remounted store's other connector survives the old restore failing", async () => {
+    const { sol, make } = sharedDrivers(memoryStorage(saved("sol", "phantom")));
+    const first = deferred<DriverAccount | null>();
+    sol.reconnect.mockReturnValueOnce(first.promise);
+    const unmounted = make();
+    const restoring = unmounted.reconnect();
+    await vi.waitFor(() => expect(sol.reconnect).toHaveBeenCalledTimes(1));
+    unmounted.destroy();
+    const remounted = make();
+    expect((await remounted.connect("sol", "solflare")).status).toBe("connected");
+    first.reject(new Error("User rejected the request."));
+    await restoring;
+    expect(sol.disconnect).not.toHaveBeenCalled();
+    expect(remounted.getState()).toMatchObject({
+      status: "connected",
+      connector: { id: "solflare" },
+    });
+  });
+
+  describe("a cancelled attempt settling after destroy leaves a remounted store's same connector", () => {
+    it.each([false, true])("when it never reached the driver (wrapped: %s)", async (wrap) => {
+      const { eth, sol, make } = sharedDrivers(memoryStorage(), wrap);
+      const unmounted = make();
+      await unmounted.connect("eth", "metaMask");
+      const slow = deferred<void>();
+      eth.disconnect.mockReturnValueOnce(slow.promise);
+      const a = unmounted.connect("sol", "phantom");
+      await unmounted.disconnect();
+      unmounted.destroy();
+      const remounted = make();
+      expect((await remounted.connect("sol", "phantom")).status).toBe("connected");
+      slow.resolve();
+      await expect(a).rejects.toThrow(/superseded/);
+      expect(sol.connect).toHaveBeenCalledTimes(1);
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      expect(remounted.getState().status).toBe("connected");
+    });
+
+    it.each(["resolves", "rejects"] as const)("when its wallet request %s", async (outcome) => {
+      const { sol, make } = sharedDrivers();
+      const unmounted = make();
+      const first = deferred<DriverAccount>();
+      sol.connect.mockReturnValueOnce(first.promise);
+      const a = unmounted.connect("sol", "phantom");
+      await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+      await unmounted.disconnect();
+      unmounted.destroy();
+      const remounted = make();
+      expect((await remounted.connect("sol", "phantom")).status).toBe("connected");
+      if (outcome === "resolves") first.resolve(phantomAccount);
+      else first.reject(new Error("User rejected the request."));
+      await expect(a).rejects.toThrow(outcome === "resolves" ? /superseded/ : /User rejected/);
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      expect(remounted.getState().status).toBe("connected");
+    });
+  });
+
+  it("a remount on a fresh driver over the same wallet cannot be told from the leftover, so it closes", async () => {
+    const { sol, make } = sharedDrivers(memoryStorage(), true);
+    const unmounted = make();
+    const first = deferred<DriverAccount>();
+    sol.connect.mockReturnValueOnce(first.promise);
+    const a = unmounted.connect("sol", "phantom");
+    await vi.waitFor(() => expect(sol.connect).toHaveBeenCalledTimes(1));
+    await unmounted.disconnect();
+    unmounted.destroy();
+    const remounted = make();
+    expect((await remounted.connect("sol", "phantom")).status).toBe("connected");
+    first.resolve(phantomAccount);
+    await expect(a).rejects.toThrow(/superseded/);
+    expect(sol.disconnect).toHaveBeenCalledWith("phantom");
+  });
+
+  it("a destroyed store refuses connect and restores nothing", async () => {
+    const { store, sol } = setup(memoryStorage(saved("sol", "phantom")));
+    store.destroy();
+    await expect(store.connect("sol", "phantom")).rejects.toThrow(/destroyed/);
+    expect((await store.reconnect()).status).toBe("disconnected");
+    expect(sol.connect).not.toHaveBeenCalled();
+    expect(sol.reconnect).not.toHaveBeenCalled();
+    expect(sol.listeners.size).toBe(0);
+  });
+
+  it("destroy stops following the active driver and notifying listeners", async () => {
+    const { store, eth, seen } = setup();
+    await store.connect("eth", "metaMask");
+    const count = seen.length;
+    store.destroy();
+    eth.emit({ status: "disconnected", connectorId: null, account: null });
+    expect(seen.length).toBe(count);
+    expect(eth.listeners.size).toBe(0);
+  });
+
+  it("a driver whose client throws still connects, with no client", async () => {
+    const { store, eth } = setup();
+    eth.client.mockImplementation(() => {
+      throw new Error("no public client");
+    });
+    const state = await store.connect("eth", "metaMask");
+    expect(state).toMatchObject({ status: "connected", client: null });
+  });
+
+  it("getState keeps its identity between changes", async () => {
+    const { store } = setup();
+    await store.connect("eth", "metaMask");
+    expect(store.getState()).toBe(store.getState());
+    expect(Object.isFrozen(store.getState())).toBe(true);
+  });
+});