w3wallets 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/index.js

@@ -30,29 +30,148 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Backpack: () => Backpack,
   Metamask: () => Metamask,
   PolkadotJS: () => PolkadotJS,
-  backpack: () => backpack,
+  config: () => config,
   createWallet: () => createWallet,
+  debug: () => debug,
+  isCachedConfig: () => isCachedConfig,
   metamask: () => metamask,
   polkadotJS: () => polkadotJS,
+  prepareWallet: () => prepareWallet,
   withWallets: () => withWallets
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/withWallets.ts
+var import_path3 = __toESM(require("path"));
+var import_fs3 = __toESM(require("fs"));
+var import_test2 = require("@playwright/test");
+
+// src/cache/types.ts
+function isCachedConfig(config2) {
+  return "__cached" in config2 && config2.__cached === true;
+}
+
+// src/cache/buildCache.ts
+var import_path2 = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+var import_test = require("@playwright/test");
+
+// src/cache/constants.ts
+var CACHE_DIR = ".w3wallets/cache";
+
+// src/core/utils.ts
 var import_path = __toESM(require("path"));
 var import_fs = __toESM(require("fs"));
 var import_crypto = __toESM(require("crypto"));
-var import_test = require("@playwright/test");
-var W3WALLETS_DIR = ".w3wallets";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getExtensionId(extensionPath) {
+  const absolutePath = import_path.default.resolve(extensionPath);
+  const manifestPath = import_path.default.join(absolutePath, "manifest.json");
+  const manifest = JSON.parse(import_fs.default.readFileSync(manifestPath, "utf-8"));
+  let dataToHash;
+  if (manifest.key) {
+    dataToHash = Buffer.from(manifest.key, "base64");
+  } else {
+    dataToHash = Buffer.from(absolutePath);
+  }
+  const hash = import_crypto.default.createHash("sha256").update(dataToHash).digest();
+  const ALPHABET = "abcdefghijklmnop";
+  let extensionId = "";
+  for (let i = 0; i < 16; i++) {
+    const byte = hash[i];
+    extensionId += ALPHABET[byte >> 4 & 15];
+    extensionId += ALPHABET[byte & 15];
+  }
+  return extensionId;
+}
+
+// src/timeouts.ts
+var SERVICE_WORKER_TIMEOUT = 3e4;
+var SERVICE_WORKER_POLL_INTERVAL = 500;
+var POPUP_VISIBILITY_TIMEOUT = 2e3;
+var SHIELD_CLOSE_TIMEOUT = 1e3;
+var ARIA_CLOSE_TIMEOUT = 500;
+var POPUP_HIDDEN_TIMEOUT = 3e3;
+var POST_UNLOCK_TIMEOUT = 3e4;
+var NOTIFICATION_CHECK_TIMEOUT = 5e3;
+var POST_CLICK_TIMEOUT = 1e4;
+var BUTTON_OR_POPUP_TIMEOUT = 3e4;
+var LAST_RESORT_CLICK_TIMEOUT = 1e4;
+var LOCK_SCREEN_TIMEOUT = 3e4;
+var MENU_BUTTON_TIMEOUT = 3e4;
+var ONBOARD_VISIBLE_TIMEOUT = 3e4;
+var ROUTE_RETRY_TIMEOUT = 5e3;
+var MAX_ROUTE_ATTEMPTS = 5;
+var MNEMONIC_KEY_DELAY = 5;
+var MNEMONIC_WORD_DELAY = 100;
+
+// src/debug.ts
+var isDebug = () => process.env.W3WALLETS_DEBUG === "true";
+function debug(message) {
+  if (!isDebug()) return;
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  console.log(`[w3wallets ${ts}] ${message}`);
+}
+
+// src/cache/buildCache.ts
+function findCacheDir(walletName) {
+  const cacheRoot = import_path2.default.join(process.cwd(), CACHE_DIR);
+  if (!import_fs2.default.existsSync(cacheRoot)) return null;
+  const entries = import_fs2.default.readdirSync(cacheRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const metaPath = import_path2.default.join(cacheRoot, entry.name, ".meta.json");
+    if (!import_fs2.default.existsSync(metaPath)) continue;
+    try {
+      const meta = JSON.parse(import_fs2.default.readFileSync(metaPath, "utf-8"));
+      if (meta.name === walletName) {
+        return import_path2.default.join(cacheRoot, entry.name);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/withWallets.ts
+var W3WALLETS_DIR = ".w3wallets";
+var MIN_PLAYWRIGHT_VERSION = "1.57.0";
+function checkPlaywrightVersion() {
+  try {
+    const pkgPath = require.resolve("@playwright/test/package.json");
+    const { version } = require(pkgPath);
+    const [minMajor, minMinor, minPatch] = MIN_PLAYWRIGHT_VERSION.split(".").map(Number);
+    const [curMajor, curMinor, curPatch] = version.split(".").map(Number);
+    const isBelow = curMajor < minMajor || curMajor === minMajor && curMinor < minMinor || curMajor === minMajor && curMinor === minMinor && curPatch < minPatch;
+    if (isBelow) {
+      throw new Error(
+        `w3wallets requires @playwright/test >= ${MIN_PLAYWRIGHT_VERSION}, but found ${version}.
+  Upgrade: npm install -D @playwright/test@latest`
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("w3wallets requires")) {
+      throw err;
+    }
+  }
+}
 function withWallets(test, ...wallets) {
+  checkPlaywrightVersion();
+  const cachedCount = wallets.filter((w) => isCachedConfig(w)).length;
+  if (cachedCount > 0 && cachedCount < wallets.length) {
+    throw new Error(
+      "Mixing cached and non-cached wallet configs is not supported. All wallets must be either cached (via prepareWallet) or non-cached."
+    );
+  }
+  const useCachedContext = cachedCount > 0;
+  debug(`withWallets: ${wallets.length} wallet(s), cached=${useCachedContext}`);
   const extensionInfo = wallets.map((w) => {
-    const extPath = import_path.default.join(process.cwd(), W3WALLETS_DIR, w.extensionDir);
+    const extPath = import_path3.default.join(process.cwd(), W3WALLETS_DIR, w.extensionDir);
     ensureWalletExtensionExists(extPath, w.name);
     const extensionId = w.extensionId ?? getExtensionId(extPath);
     return { path: extPath, id: extensionId, name: w.name };
@@ -60,14 +179,28 @@ function withWallets(test, ...wallets) {
   const extensionPaths = extensionInfo.map((e) => e.path);
   const fixtures = {
     context: async ({}, use, testInfo) => {
-      const userDataDir = import_path.default.join(
+      const userDataDir = import_path3.default.join(
         process.cwd(),
         W3WALLETS_DIR,
         ".context",
         testInfo.testId
       );
       cleanUserDataDir(userDataDir);
-      const context = await import_test.chromium.launchPersistentContext(userDataDir, {
+      if (useCachedContext) {
+        const wallet = wallets[0];
+        const cacheDir = findCacheDir(wallet.name);
+        if (!cacheDir) {
+          throw new Error(
+            `Cache not found for wallet "${wallet.name}".
+  Searched: ${import_path3.default.join(process.cwd(), CACHE_DIR)}/
+  Rebuild:  npx w3wallets cache --force <your-cache-dir>
+  Ensure your *.cache.ts setup file exports prepareWallet(...).`
+          );
+        }
+        import_fs3.default.cpSync(cacheDir, userDataDir, { recursive: true });
+      }
+      debug(`Launching persistent context: ${userDataDir}`);
+      const context = await import_test2.chromium.launchPersistentContext(userDataDir, {
         headless: testInfo.project.use.headless ?? true,
         channel: "chromium",
         args: [
@@ -75,10 +208,29 @@ function withWallets(test, ...wallets) {
           `--load-extension=${extensionPaths.join(",")}`
         ]
       });
+      debug(`Waiting for ${extensionPaths.length} service worker(s)...`);
+      const swDeadline = Date.now() + SERVICE_WORKER_TIMEOUT;
       while (context.serviceWorkers().length < extensionPaths.length) {
-        await sleep(1e3);
+        if (Date.now() > swDeadline) {
+          const found = context.serviceWorkers().length;
+          throw new Error(
+            `Service worker initialization timed out after ${SERVICE_WORKER_TIMEOUT / 1e3}s.
+  Expected: ${extensionPaths.length} extension(s), found: ${found} service worker(s).
+  Extension paths: ${extensionPaths.map((p) => import_path3.default.relative(process.cwd(), p)).join(", ")}
+  Suggestions:
+    - Check extension path exists and contains manifest.json
+    - Try headed mode to see what's happening: headless: false
+    - Ensure extension is compatible with the installed Chromium version`
+          );
+        }
+        await Promise.race([
+          context.waitForEvent("serviceworker", {
+            timeout: SERVICE_WORKER_TIMEOUT
+          }),
+          sleep(SERVICE_WORKER_POLL_INTERVAL)
+        ]);
       }
-      await Promise.all(context.pages().map((page) => page.close()));
+      debug(`All ${extensionPaths.length} service worker(s) detected`);
       await use(context);
       await context.close();
     }
@@ -87,49 +239,65 @@ function withWallets(test, ...wallets) {
     const wallet = wallets[i];
     const info = extensionInfo[i];
     fixtures[wallet.name] = async ({ context }, use) => {
-      const instance = await initializeExtension(
-        context,
-        wallet.WalletClass,
-        info.id,
-        wallet.name
-      );
-      await use(instance);
+      if (isCachedConfig(wallet)) {
+        debug(`Initializing cached wallet: ${wallet.name} (ID: ${info.id})`);
+        const instance = await findCachedExtension(
+          context,
+          wallet.WalletClass,
+          info.id,
+          wallet.name,
+          wallet.homeUrl
+        );
+        await use(instance);
+      } else {
+        debug(`Initializing fresh wallet: ${wallet.name} (ID: ${info.id})`);
+        const instance = await initializeExtension(
+          context,
+          wallet.WalletClass,
+          info.id,
+          wallet.name
+        );
+        await use(instance);
+      }
     };
   }
   return test.extend(fixtures);
 }
 function cleanUserDataDir(userDataDir) {
-  if (import_fs.default.existsSync(userDataDir)) {
-    import_fs.default.rmSync(userDataDir, { recursive: true });
+  if (import_fs3.default.existsSync(userDataDir)) {
+    import_fs3.default.rmSync(userDataDir, { recursive: true });
   }
 }
 function ensureWalletExtensionExists(walletPath, walletName) {
-  if (!import_fs.default.existsSync(import_path.default.join(walletPath, "manifest.json"))) {
+  const manifestPath = import_path3.default.join(walletPath, "manifest.json");
+  if (!import_fs3.default.existsSync(manifestPath)) {
     const cliAlias = walletName.toLowerCase();
     throw new Error(
-      `Cannot find ${walletName}. Please download it via 'npx w3wallets ${cliAlias}'.`
+      `Cannot find ${walletName} extension.
+  Checked: ${manifestPath}
+  Download it: npx w3wallets ${cliAlias}
+  Custom dir:  npx w3wallets -o <dir> ${cliAlias}`
     );
   }
 }
-function getExtensionId(extensionPath) {
-  const absolutePath = import_path.default.resolve(extensionPath);
-  const manifestPath = import_path.default.join(absolutePath, "manifest.json");
-  const manifest = JSON.parse(import_fs.default.readFileSync(manifestPath, "utf-8"));
-  let dataToHash;
-  if (manifest.key) {
-    dataToHash = Buffer.from(manifest.key, "base64");
-  } else {
-    dataToHash = Buffer.from(absolutePath);
+async function findCachedExtension(context, ExtensionClass, expectedExtensionId, walletName, homeUrl) {
+  const expectedUrl = `chrome-extension://${expectedExtensionId}/`;
+  const worker = context.serviceWorkers().find((w) => w.url().startsWith(expectedUrl));
+  if (!worker) {
+    const availableIds = context.serviceWorkers().map((w) => w.url().split("/")[2]).filter(Boolean);
+    throw new Error(
+      `Service worker for ${walletName} (ID: ${expectedExtensionId}) not found in cached context.
+  Available IDs: [${availableIds.join(", ")}]
+  The cache may be stale. Rebuild: npx w3wallets cache --force
+  Also check extension path: ${W3WALLETS_DIR}/${walletName}/`
+    );
   }
-  const hash = import_crypto.default.createHash("sha256").update(dataToHash).digest();
-  const ALPHABET = "abcdefghijklmnop";
-  let extensionId = "";
-  for (let i = 0; i < 16; i++) {
-    const byte = hash[i];
-    extensionId += ALPHABET[byte >> 4 & 15];
-    extensionId += ALPHABET[byte & 15];
+  const page = await context.newPage();
+  if (homeUrl) {
+    await page.goto(`chrome-extension://${expectedExtensionId}/${homeUrl}`);
   }
-  return extensionId;
+  const extension = new ExtensionClass(page, expectedExtensionId);
+  return extension;
 }
 async function initializeExtension(context, ExtensionClass, expectedExtensionId, walletName) {
   const expectedUrl = `chrome-extension://${expectedExtensionId}/`;
@@ -142,121 +310,58 @@ async function initializeExtension(context, ExtensionClass, expectedExtensionId,
   }
   const page = await context.newPage();
   const extension = new ExtensionClass(page, expectedExtensionId);
-  await extension.gotoOnboardPage();
   return extension;
 }
 
 // src/core/types.ts
-function createWallet(config) {
-  return config;
+function createWallet(config2) {
+  return config2;
 }
 
-// src/wallets/backpack/backpack.ts
-var import_test2 = require("@playwright/test");
+// src/wallets/metamask/metamask.ts
+var import_test3 = require("@playwright/test");
+
+// src/config.ts
+var config = {
+  /**
+   * Timeout for actions like click, fill, waitFor, goto.
+   * Set via W3WALLETS_ACTION_TIMEOUT env variable.
+   * @default 30000 (30 seconds)
+   */
+  get actionTimeout() {
+    const value = process.env.W3WALLETS_ACTION_TIMEOUT;
+    return value ? parseInt(value, 10) : void 0;
+  },
+  /**
+   * Timeout for expect assertions like toBeVisible, toContainText.
+   * Set via W3WALLETS_EXPECT_TIMEOUT env variable.
+   * @default undefined (uses Playwright's default of 5000ms)
+   */
+  get expectTimeout() {
+    const value = process.env.W3WALLETS_EXPECT_TIMEOUT;
+    return value ? parseInt(value, 10) : void 0;
+  }
+};
 
 // src/core/wallet.ts
 var Wallet = class {
   constructor(page, extensionId) {
     this.page = page;
     this.extensionId = extensionId;
-  }
-};
-
-// src/wallets/backpack/backpack.ts
-var Backpack = class extends Wallet {
-  defaultPassword = "11111111";
-  currentAccountId = 0;
-  maxAccountId = 0;
-  async gotoOnboardPage() {
-    await this.page.goto(
-      `chrome-extension://${this.extensionId}/onboarding.html`
-    );
-    await (0, import_test2.expect)(this.page.getByText("Welcome to Backpack")).toBeVisible();
-  }
-  async onboard(network, privateKey) {
-    this.currentAccountId++;
-    this.maxAccountId++;
-    return this._importAccount(network, privateKey, true);
-  }
-  async addAccount(network, privateKey) {
-    this.maxAccountId++;
-    this.currentAccountId = this.maxAccountId;
-    await this.page.goto(
-      `chrome-extension://${this.extensionId}/onboarding.html?add-user-account=true`
-    );
-    await this._importAccount(network, privateKey, false);
-  }
-  /**
-   * Switch account
-   * @param id The first added account has id 1, the second – 2, and so on
-   */
-  async switchAccount(id) {
-    await this.page.getByRole("button", { name: `A${this.currentAccountId}` }).click();
-    await this.page.getByRole("button", { name: `Account ${id}` }).click();
-    this.currentAccountId = id;
-  }
-  async unlock() {
-    await this.page.getByPlaceholder("Password").fill(this.defaultPassword);
-    await this.page.getByRole("button", { name: "Unlock" }).click();
-  }
-  async setRPC(network, rpc) {
-    await this._clickOnAccount();
-    await this.page.getByRole("button", { name: "Settings" }).click();
-    await this.page.getByRole("button", { name: network }).click();
-    await this.page.getByRole("button", { name: "RPC Connection" }).click();
-    await this.page.getByRole("button", { name: "Custom" }).click();
-    await this.page.getByPlaceholder("RPC URL").fill(rpc);
-    await this.page.keyboard.press("Enter");
-  }
-  async ignoreAndProceed() {
-    const ignoreButton = this.page.getByText("Ignore and proceed anyway.");
-    await ignoreButton.click();
-  }
-  async approve() {
-    await this.page.getByText("Approve", { exact: true }).click();
-  }
-  async deny() {
-    await this.page.getByText("Deny", { exact: true }).click();
-  }
-  async _clickOnAccount() {
-    return this.page.getByRole("button", { name: `A${this.currentAccountId}`, exact: true }).click();
-  }
-  async _importAccount(network, privateKey, isOnboard) {
-    {
-      await this.page.waitForTimeout(2e3);
-      if (await this.page.getByText("You're all good!").isVisible()) {
-        await this.page.getByLabel("Go back").click();
-      }
-    }
-    await this.page.getByTestId("terms-of-service-checkbox").click();
-    await this.page.getByText("I already have a wallet").click();
-    await this.page.getByText(network).click();
-    await this.page.getByText("Private key").click();
-    await this.page.getByPlaceholder("Private key").fill(privateKey);
-    await this.page.waitForTimeout(1e3);
-    await this.page.getByText("Import", { exact: true }).click();
-    if (isOnboard) {
-      await this.page.getByRole("textbox").nth(0).fill(this.defaultPassword);
-      await this.page.getByRole("textbox").nth(1).fill(this.defaultPassword);
-      await this.page.getByText("Next", { exact: true }).click();
-      await (0, import_test2.expect)(this.page.getByText("You're all good!")).toBeVisible();
+    if (config.actionTimeout) {
+      page.setDefaultTimeout(config.actionTimeout);
     }
-    await this.page.goto(`chrome-extension://${this.extensionId}/popup.html`);
-    await this.page.getByTestId("__CAROUSEL_ITEM_0__").waitFor({ state: "visible" });
   }
 };
 
 // src/wallets/metamask/metamask.ts
-var import_test3 = require("@playwright/test");
 var Metamask = class extends Wallet {
   defaultPassword = "TestPassword123!";
   async gotoOnboardPage() {
-    await this.page.goto(
-      `chrome-extension://${this.extensionId}/home.html#onboarding/welcome`
-    );
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
     await (0, import_test3.expect)(
       this.page.getByRole("button", { name: "I have an existing wallet" })
-    ).toBeVisible();
+    ).toBeVisible({ timeout: ONBOARD_VISIBLE_TIMEOUT });
   }
   /**
    * Onboard MetaMask with a mnemonic phrase
@@ -264,68 +369,328 @@ var Metamask = class extends Wallet {
    * @param password - Optional password (defaults to TestPassword123!)
    */
   async onboard(mnemonic, password) {
+    debug("metamask.onboard: starting");
     const pwd = password ?? this.defaultPassword;
+    await this.gotoOnboardPage();
     await this.page.getByRole("button", { name: "I have an existing wallet" }).click();
     await this.page.getByRole("button", { name: "Import using Secret Recovery Phrase" }).click();
-    const textbox = this.page.getByRole("textbox");
-    await textbox.click();
-    await this.page.keyboard.type(mnemonic, { delay: 5 });
+    const srpTextarea = this.page.getByTestId("srp-input-import__srp-note");
+    await srpTextarea.click();
+    const words = mnemonic.split(" ");
+    for (let i = 0; i < words.length; i++) {
+      await this.page.keyboard.type(words[i], { delay: MNEMONIC_KEY_DELAY });
+      if (i < words.length - 1) {
+        await this.page.keyboard.press("Space");
+        await this.page.waitForTimeout(MNEMONIC_WORD_DELAY);
+      }
+    }
     const continueBtn = this.page.getByTestId("import-srp-confirm");
+    await (0, import_test3.expect)(continueBtn).toBeEnabled({ timeout: config.expectTimeout });
     await continueBtn.click();
     const passwordInputs = this.page.locator('input[type="password"]');
     await passwordInputs.nth(0).fill(pwd);
     await passwordInputs.nth(1).fill(pwd);
-    await this.page.getByRole("checkbox").click();
+    await this.page.getByRole("checkbox").click({ force: true });
     await this.page.getByRole("button", { name: "Create password" }).click();
+    const passkeyMaybeLater = this.page.getByTestId(
+      "passkey-maybe-later-button"
+    );
     const metametricsBtn = this.page.getByTestId("metametrics-i-agree");
-    await metametricsBtn.waitFor({ state: "visible", timeout: 3e4 });
-    await metametricsBtn.click();
-    const openWalletBtn = this.page.getByRole("button", {
-      name: /open wallet/i
+    const postPasswordState = await Promise.race([
+      passkeyMaybeLater.waitFor({ state: "visible", timeout: ONBOARD_VISIBLE_TIMEOUT }).then(() => "passkey"),
+      metametricsBtn.waitFor({ state: "visible", timeout: ONBOARD_VISIBLE_TIMEOUT }).then(() => "metametrics")
+    ]);
+    if (postPasswordState === "passkey") {
+      await passkeyMaybeLater.click();
+    }
+    await metametricsBtn.waitFor({
+      state: "visible",
+      timeout: ONBOARD_VISIBLE_TIMEOUT
     });
-    await openWalletBtn.waitFor({ state: "visible", timeout: 3e4 });
+    await metametricsBtn.click();
+    const openWalletBtn = this.page.getByTestId("onboarding-complete-done");
     await openWalletBtn.click();
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
     await this.page.goto(
       `chrome-extension://${this.extensionId}/sidepanel.html`
     );
-    await this.page.getByTestId("account-options-menu-button").waitFor({ state: "visible", timeout: 3e4 });
+    debug("metamask.onboard: complete");
+  }
+  /**
+   * Dismiss MetaMask promotional popups (e.g., "Transaction Shield")
+   * that may overlay the confirmation UI.
+   */
+  async dismissPopups() {
+    debug("metamask.dismissPopups: checking for popups");
+    const popup = this.page.getByText(/Transaction Shield|free trial/i);
+    if (!await popup.first().isVisible({ timeout: POPUP_VISIBILITY_TIMEOUT }).catch(() => false)) {
+      return;
+    }
+    const shieldClose = this.page.getByTestId(
+      "shield-entry-modal-close-button"
+    );
+    if (await shieldClose.isVisible({ timeout: SHIELD_CLOSE_TIMEOUT }).catch(() => false)) {
+      await shieldClose.click();
+      if (await this.waitForPopupHidden(popup)) return;
+    }
+    const closeByAria = this.page.locator('button[aria-label="close"]').first();
+    if (await closeByAria.isVisible({ timeout: ARIA_CLOSE_TIMEOUT }).catch(() => false)) {
+      await closeByAria.click();
+      if (await this.waitForPopupHidden(popup)) return;
+    }
+    await this.page.keyboard.press("Escape");
+    await this.waitForPopupHidden(popup);
+  }
+  async waitForPopupHidden(popup) {
+    try {
+      await popup.first().waitFor({ state: "hidden", timeout: POPUP_HIDDEN_TIMEOUT });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * MetaMask's MV3 service worker can fail to come up on cold-start
+   * (especially in fresh-extension CI runs), showing an error screen
+   * with a "Restart MetaMask" button. Detect and click it so the
+   * normal post-unlock flow can proceed.
+   */
+  async recoverFromStartupError() {
+    const restartBtn = this.page.getByRole("button", {
+      name: "Restart MetaMask"
+    });
+    if (!await restartBtn.isVisible({ timeout: POPUP_VISIBILITY_TIMEOUT }).catch(() => false)) {
+      return;
+    }
+    debug("metamask.recoverFromStartupError: clicking Restart MetaMask");
+    await restartBtn.click();
+    await restartBtn.waitFor({
+      state: "hidden",
+      timeout: POST_UNLOCK_TIMEOUT
+    });
+  }
+  /**
+   * After unlock, MetaMask may show onboarding screens, queued
+   * notifications, or go straight to the wallet UI. Race all possible
+   * states in a single wait to avoid sequential timeout penalties.
+   */
+  async stabilizePostUnlock() {
+    debug("metamask.stabilizePostUnlock: racing post-unlock states");
+    await this.recoverFromStartupError();
+    const passkeyMaybeLater = this.page.getByTestId(
+      "passkey-maybe-later-button"
+    );
+    const metametricsBtn = this.page.getByTestId("metametrics-i-agree");
+    const openWalletBtn = this.page.getByTestId("onboarding-complete-done");
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const rejectAllBtn = this.page.getByText("Reject all");
+    const notificationCancelBtn = this.page.getByTestId(
+      "confirmation-cancel-button"
+    );
+    const state = await Promise.race([
+      passkeyMaybeLater.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "passkey"),
+      metametricsBtn.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "metametrics"),
+      openWalletBtn.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "openWallet"),
+      rejectAllBtn.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "rejectAll"),
+      notificationCancelBtn.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "notification"),
+      readyIndicator.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "ready")
+    ]).catch(() => "timeout");
+    debug(`metamask.stabilizePostUnlock: state=${state}`);
+    if (state === "timeout") {
+      debug(
+        `metamask.stabilizePostUnlock: timeout after ${POST_UNLOCK_TIMEOUT}ms. URL: ${this.page.url()}. Checked: passkey-maybe-later-button, metametrics-i-agree, onboarding-complete-done, Reject all, confirmation-cancel-button, account-options-menu-button`
+      );
+    }
+    if (state === "passkey") {
+      await passkeyMaybeLater.click();
+      if (await metametricsBtn.isVisible({ timeout: POST_UNLOCK_TIMEOUT }).catch(() => false)) {
+        await metametricsBtn.click();
+      }
+      if (await openWalletBtn.isVisible({ timeout: POPUP_HIDDEN_TIMEOUT }).catch(() => false)) {
+        await openWalletBtn.click();
+      }
+    }
+    if (state === "metametrics") {
+      await metametricsBtn.click();
+      if (await openWalletBtn.isVisible({ timeout: POPUP_HIDDEN_TIMEOUT }).catch(() => false)) {
+        await openWalletBtn.click();
+      }
+    }
+    if (state === "openWallet") {
+      await openWalletBtn.click();
+    }
+    if (state !== "ready") {
+      await this.dismissQueuedNotifications();
+    }
+  }
+  /**
+   * Dismiss all queued MetaMask notifications (e.g., Solana/Tron account
+   * removal). These use the templated confirmation flow at #/confirmation/...
+   * If multiple are queued, "Reject all" appears; if only one, just
+   * confirmation-cancel-button is available.
+   */
+  async dismissQueuedNotifications() {
+    const homeUrl = `chrome-extension://${this.extensionId}/home.html`;
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const rejectAllBtn = this.page.getByText("Reject all");
+    const notificationCancelBtn = this.page.getByTestId(
+      "confirmation-cancel-button"
+    );
+    await this.page.goto(homeUrl);
+    await this.recoverFromStartupError();
+    for (let i = 0; i < 10; i++) {
+      const state = await Promise.race([
+        readyIndicator.waitFor({ state: "visible", timeout: NOTIFICATION_CHECK_TIMEOUT }).then(() => "ready"),
+        rejectAllBtn.waitFor({ state: "visible", timeout: NOTIFICATION_CHECK_TIMEOUT }).then(() => "rejectAll"),
+        notificationCancelBtn.waitFor({ state: "visible", timeout: NOTIFICATION_CHECK_TIMEOUT }).then(() => "notification")
+      ]).catch(() => "timeout");
+      if (state === "ready") return;
+      if (state === "rejectAll") {
+        await rejectAllBtn.click();
+        await this.page.goto(homeUrl);
+        continue;
+      }
+      if (state === "notification") {
+        await notificationCancelBtn.click();
+        await this.page.goto(homeUrl);
+        continue;
+      }
+      debug(
+        `metamask.dismissQueuedNotifications: timeout at iteration ${i}. URL: ${this.page.url()}`
+      );
+      break;
+    }
+    await (0, import_test3.expect)(readyIndicator).toBeVisible({ timeout: POST_UNLOCK_TIMEOUT });
+  }
+  /**
+   * Wait for a target button while handling the Transaction Shield popup.
+   * Always navigates to sidepanel.html fresh so MetaMask's
+   * ConfirmationHandler can route to the pending approval.
+   */
+  async waitAndClickButton(btnLocator) {
+    debug(`metamask.waitAndClickButton: navigating to sidepanel`);
+    const popup = this.page.getByText(/Transaction Shield|free trial/i);
+    const sidepanelUrl = `chrome-extension://${this.extensionId}/sidepanel.html`;
+    const confirmRoutePattern = /#\/(confirm-transaction|connect|confirmation)\b/;
+    const waitForButtonOrPopup = (timeout) => Promise.race([
+      btnLocator.first().waitFor({ state: "visible", timeout }).then(() => "button"),
+      popup.first().waitFor({ state: "visible", timeout }).then(() => "popup")
+    ]).catch(() => "timeout");
+    const handlePopupAndClick = async () => {
+      await this.dismissPopups();
+      await btnLocator.first().waitFor({ state: "visible", timeout: BUTTON_OR_POPUP_TIMEOUT });
+      await btnLocator.first().click();
+    };
+    let routeFound = false;
+    for (let attempt = 0; attempt < MAX_ROUTE_ATTEMPTS; attempt++) {
+      try {
+        await this.page.goto(sidepanelUrl, { timeout: ROUTE_RETRY_TIMEOUT });
+        await this.page.waitForURL(confirmRoutePattern, {
+          timeout: ROUTE_RETRY_TIMEOUT
+        });
+        routeFound = true;
+        break;
+      } catch {
+        debug(
+          `metamask.waitAndClickButton: route attempt ${attempt + 1}/${MAX_ROUTE_ATTEMPTS} failed. URL: ${this.page.url()}`
+        );
+      }
+    }
+    if (!routeFound) {
+      console.warn(
+        `[w3wallets] confirmation route not found after ${MAX_ROUTE_ATTEMPTS} attempts. URL: ${this.page.url()}`
+      );
+    }
+    const result = await waitForButtonOrPopup(BUTTON_OR_POPUP_TIMEOUT);
+    debug(
+      `metamask.waitAndClickButton: result=${result}, URL=${this.page.url()}`
+    );
+    if (result === "button") {
+      await btnLocator.first().click();
+      await this.page.waitForURL((url) => !confirmRoutePattern.test(url.toString()), {
+        timeout: POST_CLICK_TIMEOUT
+      }).catch(() => {
+        console.warn(
+          `[w3wallets] still on confirmation route after click. URL: ${this.page.url()}`
+        );
+      });
+      return;
+    }
+    if (result === "popup") {
+      await handlePopupAndClick();
+      await this.page.waitForURL((url) => !confirmRoutePattern.test(url.toString()), {
+        timeout: POST_CLICK_TIMEOUT
+      }).catch(() => {
+        console.warn(
+          `[w3wallets] still on confirmation route after popup dismiss. URL: ${this.page.url()}`
+        );
+      });
+      return;
+    }
+    const isOnConfirmRoute = confirmRoutePattern.test(this.page.url());
+    debug(
+      `metamask.waitAndClickButton: timeout after ${BUTTON_OR_POPUP_TIMEOUT}ms. URL: ${this.page.url()}, onConfirmRoute: ${isOnConfirmRoute}`
+    );
+    console.warn(
+      `[w3wallets] no button or popup found after ${BUTTON_OR_POPUP_TIMEOUT / 1e3}s. URL: ${this.page.url()}`
+    );
+    await btnLocator.first().click({ timeout: LAST_RESORT_CLICK_TIMEOUT });
   }
   async approve() {
-    await this.page.getByTestId("confirm-btn").or(this.page.getByTestId("confirm-footer-button")).or(this.page.getByTestId("page-container-footer-next")).or(this.page.getByRole("button", { name: /confirm/i })).click();
-    await this.page.getByTestId("account-options-menu-button").waitFor({ state: "visible", timeout: 3e4 });
+    debug("metamask.approve: starting");
+    const confirmBtn = this.page.getByTestId("confirm-btn").or(this.page.getByTestId("confirm-footer-button")).or(this.page.getByTestId("page-container-footer-next")).or(this.page.getByRole("button", { name: /^confirm$/i }));
+    await this.waitAndClickButton(confirmBtn);
   }
   async deny() {
-    const cancelBtn = this.page.getByTestId("cancel-btn").or(this.page.getByTestId("confirm-footer-cancel-button")).or(this.page.getByTestId("page-container-footer-cancel")).or(this.page.getByRole("button", { name: /cancel|reject/i }));
-    await cancelBtn.first().click();
+    debug("metamask.deny: starting");
+    const cancelBtn = this.page.getByTestId("cancel-btn").or(this.page.getByTestId("confirm-footer-cancel-button")).or(this.page.getByTestId("page-container-footer-cancel")).or(this.page.getByRole("button", { name: /^cancel$/i })).or(this.page.getByRole("button", { name: /^reject$/i }));
+    await this.waitAndClickButton(cancelBtn);
   }
   /**
    * Lock the MetaMask wallet
    */
   async lock() {
-    await this.page.getByTestId("account-options-menu-button").click();
-    await this.page.locator("text=Lock MetaMask").click();
+    debug("metamask.lock: starting");
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    const menuBtn = this.page.getByTestId("account-options-menu-button");
+    await menuBtn.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT });
+    await menuBtn.click({ force: true });
+    await this.page.getByTestId("global-menu-lock").click();
   }
   /**
-   * Unlock MetaMask with password
+   * Unlock MetaMask with password.
+   * After unlocking, stabilizes the wallet UI by handling post-unlock
+   * screens (metametrics, onboarding completion) and dismissing queued
+   * notifications. Ends on home.html with the wallet UI ready.
    */
   async unlock(password) {
+    debug("metamask.unlock: starting");
     const pwd = password ?? this.defaultPassword;
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
     const passwordInput = this.page.getByTestId("unlock-password");
     await passwordInput.fill(pwd);
     await this.page.getByTestId("unlock-submit").click();
+    await this.page.waitForSelector('[data-testid="unlock-password"]', {
+      state: "hidden",
+      timeout: LOCK_SCREEN_TIMEOUT
+    });
+    await this.stabilizePostUnlock();
+    debug("metamask.unlock: complete");
   }
   /**
    * Switch to an existing network in MetaMask
    * @param networkName - Name of the network to switch to (e.g., "Ethereum Mainnet", "Sepolia")
    */
   async switchNetwork(networkName, networkType = "Popular") {
+    debug(`metamask.switchNetwork: ${networkName} (${networkType})`);
     await this.page.getByTestId("sort-by-networks").click();
     if (networkType === "Custom") {
-      await this.page.getByRole("tab", { name: "Custom" }).click();
+      await this.page.getByRole("tab", { name: "Custom" }).click({ force: true });
     }
     await this.page.getByText(networkName).click();
     await (0, import_test3.expect)(this.page.getByTestId("sort-by-networks")).toHaveText(
-      networkName
+      networkName,
+      { timeout: config.expectTimeout }
     );
   }
   async switchAccount(accountName) {
@@ -346,7 +711,7 @@ var Metamask = class extends Wallet {
     await this.page.getByRole("button", { name: /save/i }).click();
   }
   async addCustomNetwork(settings) {
-    await this.page.getByTestId("account-options-menu-button").click();
+    await this.page.getByTestId("account-options-menu-button").click({ force: true });
     await this.page.getByTestId("global-menu-networks").click();
     await this.page.getByRole("button", { name: "Add a custom network" }).click();
     await this.page.getByTestId("network-form-network-name").fill(settings.name);
@@ -357,24 +722,33 @@ var Metamask = class extends Wallet {
     await this.page.getByTestId("rpc-url-input-test").fill(settings.rpc);
     await this.page.getByRole("button", { name: "Add URL" }).click();
     await this.page.getByRole("button", { name: "Save" }).click();
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    await this.page.waitForLoadState("domcontentloaded");
   }
   async enableTestNetworks() {
-    await this.page.getByTestId("account-options-menu-button").click();
+    await this.page.getByTestId("account-options-menu-button").click({ force: true });
     await this.page.getByTestId("global-menu-networks").click();
-    await this.page.locator("text=Show test networks >> xpath=following-sibling::label").click();
-    await this.page.keyboard.press("Escape");
+    const toggle = this.page.locator(
+      "text=Show test networks >> xpath=following-sibling::label"
+    );
+    await (0, import_test3.expect)(toggle).toBeVisible({ timeout: config.expectTimeout });
+    await toggle.click();
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
   }
   async importAccount(privateKey) {
+    debug("metamask.importAccount: starting");
     await this.page.getByTestId("account-menu-icon").click();
     await this.page.getByTestId("account-list-add-wallet-button").click();
-    await this.page.getByTestId("add-wallet-modal-import-account").click();
+    await this.page.getByTestId("choose-wallet-type-import-account").click();
     await this.page.locator("#private-key-box").fill(privateKey);
     await this.page.getByTestId("import-account-confirm-button").click();
-    await this.page.getByRole("button", { name: "Back" }).click();
+    await this.page.getByTestId("back-button").click();
+    await this.page.locator('[data-testid^="multichain-account-cell-keyring:"]').first().click();
   }
   async accountNameIs(accountName) {
     await (0, import_test3.expect)(this.page.getByTestId("account-menu-icon")).toContainText(
-      accountName
+      accountName,
+      { timeout: config.expectTimeout }
     );
   }
 };
@@ -387,9 +761,11 @@ var PolkadotJS = class extends Wallet {
     await this.page.goto(`chrome-extension://${this.extensionId}/index.html`);
     await (0, import_test4.expect)(
       this.page.getByText("Before we start, just a couple of notes")
-    ).toBeVisible();
+    ).toBeVisible({ timeout: config.expectTimeout });
   }
   async onboard(seed, password, name) {
+    debug("polkadotJS.onboard: starting");
+    await this.gotoOnboardPage();
     await this.page.getByRole("button", { name: "Understood, let me continue" }).click();
     await this.page.getByRole("button", { name: "I Understand" }).click();
     await this.page.locator(".popupToggle").first().click();
@@ -406,12 +782,13 @@ var PolkadotJS = class extends Wallet {
       password ?? this.defaultPassword
     );
     await this.page.getByRole("button", { name: "Add the account with the supplied seed" }).click();
+    debug("polkadotJS.onboard: complete");
   }
   async selectAllAccounts() {
     await this.page.getByText("Select all").click();
   }
   async selectAccount(accountId) {
-    await this.page.locator(".accountWichCheckbox").filter({ hasText: accountId }).locator(".accountTree-checkbox").locator("span").check();
+    await this.page.locator(".accountWichCheckbox").filter({ hasText: accountId }).locator(".accountTree-checkbox").click();
   }
   async enterPassword(password) {
     await this._getLabeledInput("Password for this account").fill(
@@ -419,6 +796,7 @@ var PolkadotJS = class extends Wallet {
     );
   }
   async approve() {
+    debug("polkadotJS.approve: starting");
     const connect = this.page.getByRole("button", { name: "Connect" });
     const signTransaction = this.page.getByRole("button", {
       name: "Sign the transaction"
@@ -426,6 +804,7 @@ var PolkadotJS = class extends Wallet {
     await connect.or(signTransaction).click();
   }
   async deny() {
+    debug("polkadotJS.deny: starting");
     const reject = this.page.getByRole("button", { name: "Reject" });
     const cancel = this.page.getByRole("link", { name: "Cancel" });
     await reject.or(cancel).click();
@@ -438,29 +817,37 @@ var PolkadotJS = class extends Wallet {
 };
 
 // src/wallets/index.ts
-var backpack = createWallet({
-  name: "backpack",
-  extensionDir: "backpack",
-  WalletClass: Backpack
-});
 var metamask = createWallet({
   name: "metamask",
   extensionDir: "metamask",
-  WalletClass: Metamask
+  WalletClass: Metamask,
+  homeUrl: "home.html"
 });
 var polkadotJS = createWallet({
   name: "polkadotJS",
   extensionDir: "polkadotjs",
-  WalletClass: PolkadotJS
+  WalletClass: PolkadotJS,
+  homeUrl: "index.html"
 });
+
+// src/cache/prepareWallet.ts
+function prepareWallet(walletConfig, setupFn) {
+  return {
+    ...walletConfig,
+    setupFn,
+    __cached: true
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Backpack,
   Metamask,
   PolkadotJS,
-  backpack,
+  config,
   createWallet,
+  debug,
+  isCachedConfig,
   metamask,
   polkadotJS,
+  prepareWallet,
   withWallets
 });