w3wallets 0.10.2 → 1.0.0-beta.10

package/dist/index.js

@@ -30,126 +30,697 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Metamask: () => Metamask,
+  PolkadotJS: () => PolkadotJS,
+  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"));
+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;
+}
 
-// tests/utils/sleep.ts
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// 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 import_test4 = require("@playwright/test");
+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_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 };
+  });
+  const extensionPaths = extensionInfo.map((e) => e.path);
+  const fixtures = {
+    context: async ({}, use, testInfo) => {
+      const userDataDir = import_path3.default.join(
+        process.cwd(),
+        W3WALLETS_DIR,
+        ".context",
+        testInfo.testId
+      );
+      cleanUserDataDir(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: [
+          `--disable-extensions-except=${extensionPaths.join(",")}`,
+          `--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) {
+        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)
+        ]);
+      }
+      debug(`All ${extensionPaths.length} service worker(s) detected`);
+      await use(context);
+      await context.close();
+    }
+  };
+  for (let i = 0; i < wallets.length; i++) {
+    const wallet = wallets[i];
+    const info = extensionInfo[i];
+    fixtures[wallet.name] = async ({ context }, use) => {
+      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_fs3.default.existsSync(userDataDir)) {
+    import_fs3.default.rmSync(userDataDir, { recursive: true });
+  }
+}
+function ensureWalletExtensionExists(walletPath, walletName) {
+  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} extension.
+  Checked: ${manifestPath}
+  Download it: npx w3wallets ${cliAlias}
+  Custom dir:  npx w3wallets -o <dir> ${cliAlias}`
+    );
+  }
+}
+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 page = await context.newPage();
+  if (homeUrl) {
+    await page.goto(`chrome-extension://${expectedExtensionId}/${homeUrl}`);
+  }
+  const extension = new ExtensionClass(page, expectedExtensionId);
+  return extension;
+}
+async function initializeExtension(context, ExtensionClass, expectedExtensionId, walletName) {
+  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. Available extension IDs: [${availableIds.join(", ")}]`
+    );
+  }
+  const page = await context.newPage();
+  const extension = new ExtensionClass(page, expectedExtensionId);
+  return extension;
+}
 
-// src/backpack/backpack.ts
-var import_test = require("@playwright/test");
+// src/core/types.ts
+function createWallet(config2) {
+  return config2;
+}
+
+// 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/wallet.ts
+// src/core/wallet.ts
 var Wallet = class {
   constructor(page, extensionId) {
     this.page = page;
     this.extensionId = extensionId;
+    if (config.actionTimeout) {
+      page.setDefaultTimeout(config.actionTimeout);
+    }
   }
 };
 
-// src/backpack/backpack.ts
-var Backpack = class extends Wallet {
-  defaultPassword = "11111111";
-  currentAccountId = 0;
-  maxAccountId = 0;
+// src/wallets/metamask/metamask.ts
+var Metamask = class extends Wallet {
+  defaultPassword = "TestPassword123!";
   async gotoOnboardPage() {
+    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({ timeout: ONBOARD_VISIBLE_TIMEOUT });
+  }
+  /**
+   * Onboard MetaMask with a mnemonic phrase
+   * @param mnemonic - 12 or 24 word recovery phrase
+   * @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 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({ force: true });
+    await this.page.getByRole("button", { name: "Create password" }).click();
+    const metametricsBtn = this.page.getByTestId("metametrics-i-agree");
+    await metametricsBtn.click();
+    const openWalletBtn = this.page.getByRole("button", {
+      name: /open wallet/i
+    });
+    await openWalletBtn.click();
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
     await this.page.goto(
-      `chrome-extension://${this.extensionId}/onboarding.html`
+      `chrome-extension://${this.extensionId}/sidepanel.html`
     );
-    await (0, import_test.expect)(this.page.getByText("Welcome to Backpack")).toBeVisible();
+    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 onboard(network, privateKey) {
-    this.currentAccountId++;
-    this.maxAccountId++;
-    return this._importAccount(network, privateKey, true);
+  async waitForPopupHidden(popup) {
+    try {
+      await popup.first().waitFor({ state: "hidden", timeout: POPUP_HIDDEN_TIMEOUT });
+      return true;
+    } catch {
+      return false;
+    }
   }
-  async addAccount(network, privateKey) {
-    this.maxAccountId++;
-    this.currentAccountId = this.maxAccountId;
-    await this.page.goto(
-      `chrome-extension://${this.extensionId}/onboarding.html?add-user-account=true`
+  /**
+   * 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");
+    const metametricsBtn = this.page.getByTestId("metametrics-i-agree");
+    const openWalletBtn = this.page.getByRole("button", {
+      name: /open wallet/i
+    });
+    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._importAccount(network, privateKey, false);
+    const state = await Promise.race([
+      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: metametrics-i-agree, open-wallet button, Reject all, confirmation-cancel-button, account-options-menu-button`
+      );
+    }
+    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();
+    }
   }
   /**
-   * Switch account
-   * @param id The first added account has id 1, the second – 2, and so on
+   * 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 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 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);
+    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++) {
+      await this.page.goto(sidepanelUrl);
+      try {
+        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.getByText("Approve", { exact: true }).click();
+    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() {
-    await this.page.getByText("Deny", { exact: true }).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);
   }
-  async _clickOnAccount() {
-    return this.page.getByRole("button", { name: `A${this.currentAccountId}`, exact: true }).click();
+  /**
+   * Lock the MetaMask wallet
+   */
+  async lock() {
+    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.locator("text=Log out").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_test.expect)(this.page.getByText("You're all good!")).toBeVisible();
+  /**
+   * 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({ force: true });
     }
-    await this.page.goto(`chrome-extension://${this.extensionId}/popup.html`);
-    await this.page.getByTestId("__CAROUSEL_ITEM_0__").waitFor({ state: "visible" });
+    await this.page.getByText(networkName).click();
+    await (0, import_test3.expect)(this.page.getByTestId("sort-by-networks")).toHaveText(
+      networkName,
+      { timeout: config.expectTimeout }
+    );
+  }
+  async switchAccount(accountName) {
+    await this.page.getByTestId("account-menu-icon").click();
+    await this.page.getByText(accountName, { exact: true }).click();
+  }
+  /**
+   * Add a custom network to MetaMask
+   */
+  async addNetwork(network) {
+    await this.page.goto(
+      `chrome-extension://${this.extensionId}/home.html#settings/networks/add-network`
+    );
+    await this.page.getByTestId("network-form-network-name").fill(network.name);
+    await this.page.getByTestId("network-form-rpc-url").fill(network.rpc);
+    await this.page.getByTestId("network-form-chain-id").fill(network.chainId.toString());
+    await this.page.getByTestId("network-form-ticker-input").fill(network.currencySymbol);
+    await this.page.getByRole("button", { name: /save/i }).click();
+  }
+  async addCustomNetwork(settings) {
+    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);
+    await this.page.getByTestId("network-form-chain-id").fill(settings.chainId.toString());
+    await this.page.getByTestId("network-form-ticker-input").fill(settings.currencySymbol);
+    await this.page.getByTestId("test-add-rpc-drop-down").click();
+    await this.page.getByRole("button", { name: "Add RPC URL" }).click();
+    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({ force: true });
+    await this.page.getByTestId("global-menu-networks").click();
+    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("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.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,
+      { timeout: config.expectTimeout }
+    );
   }
 };
 
-// src/polkadotJS/polkadotJS.ts
-var import_test2 = require("@playwright/test");
+// src/wallets/polkadot-js/polkadot-js.ts
+var import_test4 = require("@playwright/test");
 var PolkadotJS = class extends Wallet {
   defaultPassword = "11111111";
   async gotoOnboardPage() {
     await this.page.goto(`chrome-extension://${this.extensionId}/index.html`);
-    await (0, import_test2.expect)(
+    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();
@@ -166,12 +737,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(
@@ -179,6 +751,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"
@@ -186,6 +759,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();
@@ -197,234 +771,38 @@ var PolkadotJS = class extends Wallet {
   }
 };
 
-// src/metamask/metamask.ts
-var import_test3 = require("@playwright/test");
-var Metamask = class extends Wallet {
-  defaultPassword = "11111111";
-  async gotoOnboardPage() {
-    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
-  }
-  /**
-   *
-   * @param mnemonic 12-word mnemonic seed phrase
-   */
-  async onboard(mnemonic, password = this.defaultPassword) {
-    await this.page.getByTestId("onboarding-import-wallet").click();
-    await this.page.getByTestId("onboarding-import-with-srp-button").click();
-    await this.page.getByTestId("srp-input-import__srp-note").pressSequentially(mnemonic, { delay: 5 });
-    await this.page.getByRole("button", { name: "Continue" }).click();
-    await this.page.getByTestId("create-password-new-input").fill(password);
-    await this.page.getByTestId("create-password-confirm-input").fill(password);
-    await this.page.getByTestId("create-password-terms").click();
-    await this.page.getByTestId("create-password-submit").click();
-    await this.page.getByTestId("metametrics-i-agree").click();
-    await this.page.getByTestId("onboarding-complete-done").click();
-    await this.clickTopRightCornerToCloseAllTheMarketingBullshit();
-  }
-  // async switchAccount(accountAddress: { address: string }): Promise<void>;
-  async switchAccount(accountNameOrAddress) {
-    await this.page.getByTestId("account-menu-icon").click();
-    await this.page.getByText(accountNameOrAddress.name, { exact: true }).click();
-  }
-  async importAccount(privateKey) {
-    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.locator("#private-key-box").fill(privateKey);
-    await this.page.getByTestId("import-account-confirm-button").click();
-    await this.page.getByRole("button", { name: "Back" }).click();
-  }
-  async addAccount(accountName) {
-    await this.page.getByTestId("account-menu-icon").click();
-    await this.page.getByTestId("multichain-account-menu-popover-action-button").click();
-    await this.page.getByTestId("multichain-account-menu-popover-add-account").click();
-    if (accountName) {
-      await this.page.locator("#account-name").fill(accountName);
-    }
-    await this.page.getByTestId("submit-add-account-with-name").click();
-  }
-  async getAccountName() {
-    const accountSelect = this.page.getByTestId("account-menu-icon");
-    await (0, import_test3.expect)(accountSelect).toBeVisible();
-    const text = await accountSelect.textContent();
-    if (!text) throw Error("Cannot get account name");
-    return text;
-  }
-  async connectToNetwork(networkName, networkType = "Popular") {
-    await this.page.getByTestId("sort-by-networks").click();
-    await this.page.getByRole("tab", { name: networkType, exact: true }).click();
-    const additionalNetwork = this.page.getByTestId("additional-network-item").getByText(networkName);
-    await this.page.getByText(networkName).click();
-  }
-  async addCustomNetwork(settings) {
-    await this.page.getByTestId("account-options-menu-button").click();
-    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);
-    await this.page.getByTestId("network-form-chain-id").fill(settings.chainId.toString());
-    await this.page.getByTestId("network-form-ticker-input").fill(settings.currencySymbol);
-    await this.page.getByTestId("test-add-rpc-drop-down").click();
-    await this.page.getByRole("button", { name: "Add RPC URL" }).click();
-    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();
-  }
-  async enableTestNetworks() {
-    await this.page.getByTestId("account-options-menu-button").click();
-    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");
-  }
-  async approve() {
-    const p = await this.page.context().newPage();
-    await p.goto(`chrome-extension://${this.extensionId}/notification.html`);
-    await p.locator(
-      '[data-testid="confirm-footer-button"], [data-testid="confirm-btn"], [data-testid="page-container-footer-next"], [data-testid="confirmation-submit-button"]'
-    ).click();
-    await p.waitForSelector(".multichain-app-header", {
-      timeout: 1e4
-    });
-    await p.close();
-  }
-  async deny() {
-    return this.usingNotificationPage(
-      (p) => p.getByTestId("cancel-btn").click()
-    );
-  }
-  async usingNotificationPage(action) {
-    const p = await this.page.context().newPage();
-    await p.goto(`chrome-extension://${this.extensionId}/notification.html`);
-    await action(p);
-    await p.close();
-  }
-  async clickTopRightCornerToCloseAllTheMarketingBullshit() {
-    await this.page.waitForTimeout(500);
-    await this.page.keyboard.press("Escape");
-    await this.page.mouse.click(1e3, 10);
-  }
-};
+// src/wallets/index.ts
+var metamask = createWallet({
+  name: "metamask",
+  extensionDir: "metamask",
+  WalletClass: Metamask,
+  homeUrl: "home.html"
+});
+var polkadotJS = createWallet({
+  name: "polkadotJS",
+  extensionDir: "polkadotjs",
+  WalletClass: PolkadotJS,
+  homeUrl: "index.html"
+});
 
-// src/withWallets.ts
-var w3walletsDir = ".w3wallets";
-function withWallets(test, ...config) {
-  const withBackpack = config.includes("backpack");
-  const withPolkadotJS = config.includes("polkadotJS");
-  const withMetamask = config.includes("metamask");
-  const backpackPath = import_path.default.join(process.cwd(), w3walletsDir, "backpack");
-  const polkadotJSPath = import_path.default.join(process.cwd(), w3walletsDir, "polkadotJS");
-  const metamaskPath = import_path.default.join(process.cwd(), w3walletsDir, "metamask");
-  return test.extend({
-    /**
-     * Sets up a persistent browser context with the requested extensions loaded.
-     */
-    context: async ({}, use, testInfo) => {
-      const userDataDir = import_path.default.join(
-        process.cwd(),
-        ".w3wallets",
-        ".context",
-        testInfo.testId
-      );
-      cleanUserDataDir(userDataDir);
-      const extensionPaths = [];
-      if (withBackpack) {
-        ensureWalletExtensionExists(backpackPath, "backpack");
-        extensionPaths.push(backpackPath);
-      }
-      if (withPolkadotJS) {
-        ensureWalletExtensionExists(polkadotJSPath, "polkadotJS");
-        extensionPaths.push(polkadotJSPath);
-      }
-      if (withMetamask) {
-        ensureWalletExtensionExists(metamaskPath, "metamask");
-        extensionPaths.push(metamaskPath);
-      }
-      const context = await import_test4.chromium.launchPersistentContext(userDataDir, {
-        headless: testInfo.project.use.headless ?? true,
-        channel: "chromium",
-        args: [
-          `--disable-extensions-except=${extensionPaths.join(",")}`,
-          `--load-extension=${extensionPaths.join(",")}`
-        ]
-      });
-      while (context.serviceWorkers().length < extensionPaths.length) {
-        await sleep(1e3);
-      }
-      await use(context);
-      await context.close();
-    },
-    backpack: async ({ context }, use) => {
-      if (!withBackpack) {
-        throw Error(
-          "The Backpack wallet hasn't been loaded. Add it to the withWallets function."
-        );
-      }
-      const backpack = await initializeExtension(
-        context,
-        Backpack,
-        "Backpack is not initialized"
-      );
-      await use(backpack);
-    },
-    polkadotJS: async ({ context }, use) => {
-      if (!withPolkadotJS) {
-        throw Error(
-          "The Polkadot{.js} wallet hasn't been loaded. Add it to the withWallets function."
-        );
-      }
-      const polkadotJS = await initializeExtension(
-        context,
-        PolkadotJS,
-        "Polkadot{.js} is not initialized"
-      );
-      await use(polkadotJS);
-    },
-    metamask: async ({ context }, use) => {
-      if (!withMetamask) {
-        throw Error(
-          "The Metamask wallet hasn't been loaded. Add it to the withWallets function."
-        );
-      }
-      const metamask = await initializeExtension(
-        context,
-        Metamask,
-        "Metamask is not initialized"
-      );
-      await use(metamask);
-    }
-  });
-}
-function cleanUserDataDir(userDataDir) {
-  if (import_fs.default.existsSync(userDataDir)) {
-    import_fs.default.rmSync(userDataDir, { recursive: true });
-  }
-}
-function ensureWalletExtensionExists(walletPath, walletName) {
-  if (!import_fs.default.existsSync(import_path.default.join(walletPath, "manifest.json"))) {
-    throw new Error(
-      `Cannot find ${walletName}. Please download it via 'npx w3wallets ${walletName}'.`
-    );
-  }
-}
-async function initializeExtension(context, ExtensionClass, notInitializedErrorMessage) {
-  const serviceWorkers = context.serviceWorkers();
-  let page = await context.newPage();
-  for (const worker of serviceWorkers) {
-    const extensionId = worker.url().split("/")[2];
-    if (!extensionId) {
-      continue;
-    }
-    const extension = new ExtensionClass(page, extensionId);
-    try {
-      await extension.gotoOnboardPage();
-      return extension;
-    } catch {
-      await page.close();
-      page = await context.newPage();
-    }
-  }
-  throw new Error(notInitializedErrorMessage);
+// 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 = {
+  Metamask,
+  PolkadotJS,
+  config,
+  createWallet,
+  debug,
+  isCachedConfig,
+  metamask,
+  polkadotJS,
+  prepareWallet,
   withWallets
 });