w3wallets 1.0.0-beta.8 → 1.0.0-beta.9

package/dist/index.d.mts

@@ -2,10 +2,16 @@ import * as playwright_test from 'playwright/test';
 import { Page, test, BrowserContext } from '@playwright/test';
 
 interface IWallet {
-    readonly page: Page;
+    page: Page;
     gotoOnboardPage(): Promise<void>;
     approve(): Promise<void>;
     deny(): Promise<void>;
+    /**
+     * Called by the cache builder after setupFn completes, before the browser
+     * context is closed. Wallet implementations can override this to force
+     * persistence of in-memory state (e.g., locking the vault).
+     */
+    beforeCacheClose?(): Promise<void>;
 }
 /**
  * Configuration object for a wallet.
@@ -78,7 +84,7 @@ declare function withWallets<const T extends readonly WalletConfig[]>(test: type
 }, playwright_test.PlaywrightWorkerArgs & playwright_test.PlaywrightWorkerOptions>;
 
 declare abstract class Wallet implements IWallet {
-    readonly page: Page;
+    page: Page;
     readonly extensionId: string;
     constructor(page: Page, extensionId: string);
     abstract gotoOnboardPage(): Promise<void>;
@@ -121,10 +127,22 @@ declare class Metamask extends Wallet {
      * confirmation-cancel-button is available.
      */
     private dismissQueuedNotifications;
+    /**
+     * Close extra MetaMask extension pages that the service worker opened
+     * during onboarding (e.g. home.html#/onboarding/completion).
+     * Keeps only this.page alive.
+     */
+    private closeExtraExtensionPages;
+    /**
+     * Poll the URL until it leaves a confirmation route. Uses polling instead
+     * of waitForURL because MetaMask uses HashRouter and hash-only changes
+     * are not reliably caught by Playwright's navigation events.
+     */
+    private waitForConfirmRouteExit;
     /**
      * 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.
+     * Navigates to sidepanel.html so MetaMask's ConfirmationHandler routes
+     * to the pending approval, then waits for the button to become visible.
      */
     private waitAndClickButton;
     approve(): Promise<void>;
@@ -133,6 +151,12 @@ declare class Metamask extends Wallet {
      * Lock the MetaMask wallet
      */
     lock(): Promise<void>;
+    /**
+     * Force-persist the vault by locking the wallet. Called by the cache builder
+     * before closing the browser context. MetaMask MV3 stores the vault lazily —
+     * locking forces the encrypted vault to be written to chrome.storage.local.
+     */
+    beforeCacheClose(): Promise<void>;
     /**
      * Unlock MetaMask with password.
      * After unlocking, stabilizes the wallet UI by handling post-unlock

package/dist/index.d.ts

@@ -2,10 +2,16 @@ import * as playwright_test from 'playwright/test';
 import { Page, test, BrowserContext } from '@playwright/test';
 
 interface IWallet {
-    readonly page: Page;
+    page: Page;
     gotoOnboardPage(): Promise<void>;
     approve(): Promise<void>;
     deny(): Promise<void>;
+    /**
+     * Called by the cache builder after setupFn completes, before the browser
+     * context is closed. Wallet implementations can override this to force
+     * persistence of in-memory state (e.g., locking the vault).
+     */
+    beforeCacheClose?(): Promise<void>;
 }
 /**
  * Configuration object for a wallet.
@@ -78,7 +84,7 @@ declare function withWallets<const T extends readonly WalletConfig[]>(test: type
 }, playwright_test.PlaywrightWorkerArgs & playwright_test.PlaywrightWorkerOptions>;
 
 declare abstract class Wallet implements IWallet {
-    readonly page: Page;
+    page: Page;
     readonly extensionId: string;
     constructor(page: Page, extensionId: string);
     abstract gotoOnboardPage(): Promise<void>;
@@ -121,10 +127,22 @@ declare class Metamask extends Wallet {
      * confirmation-cancel-button is available.
      */
     private dismissQueuedNotifications;
+    /**
+     * Close extra MetaMask extension pages that the service worker opened
+     * during onboarding (e.g. home.html#/onboarding/completion).
+     * Keeps only this.page alive.
+     */
+    private closeExtraExtensionPages;
+    /**
+     * Poll the URL until it leaves a confirmation route. Uses polling instead
+     * of waitForURL because MetaMask uses HashRouter and hash-only changes
+     * are not reliably caught by Playwright's navigation events.
+     */
+    private waitForConfirmRouteExit;
     /**
      * 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.
+     * Navigates to sidepanel.html so MetaMask's ConfirmationHandler routes
+     * to the pending approval, then waits for the button to become visible.
      */
     private waitAndClickButton;
     approve(): Promise<void>;
@@ -133,6 +151,12 @@ declare class Metamask extends Wallet {
      * Lock the MetaMask wallet
      */
     lock(): Promise<void>;
+    /**
+     * Force-persist the vault by locking the wallet. Called by the cache builder
+     * before closing the browser context. MetaMask MV3 stores the vault lazily —
+     * locking forces the encrypted vault to be written to chrome.storage.local.
+     */
+    beforeCacheClose(): Promise<void>;
     /**
      * Unlock MetaMask with password.
      * After unlocking, stabilizes the wallet UI by handling post-unlock

package/dist/index.js

@@ -104,8 +104,6 @@ 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;
 
@@ -399,9 +397,28 @@ var Metamask = class extends Wallet {
     });
     await openWalletBtn.click();
     await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const lockInput = this.page.getByTestId("unlock-password");
+    const state = await Promise.race([
+      readyIndicator.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "ready"),
+      lockInput.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "locked")
+    ]).catch(() => "timeout");
+    debug(`metamask.onboard: post-navigate state=${state}`);
+    if (state === "locked") {
+      debug("metamask.onboard: vault locked after onboarding, auto-unlocking");
+      await lockInput.fill(password ?? this.defaultPassword);
+      await this.page.getByTestId("unlock-submit").click();
+      await this.page.waitForSelector('[data-testid="unlock-password"]', {
+        state: "hidden",
+        timeout: LOCK_SCREEN_TIMEOUT
+      });
+      await this.stabilizePostUnlock();
+    }
+    await this.closeExtraExtensionPages();
     await this.page.goto(
       `chrome-extension://${this.extensionId}/sidepanel.html`
     );
+    await this.page.waitForLoadState("networkidle");
     debug("metamask.onboard: complete");
   }
   /**
@@ -517,10 +534,37 @@ var Metamask = class extends Wallet {
     }
     await (0, import_test3.expect)(readyIndicator).toBeVisible({ timeout: POST_UNLOCK_TIMEOUT });
   }
+  /**
+   * Close extra MetaMask extension pages that the service worker opened
+   * during onboarding (e.g. home.html#/onboarding/completion).
+   * Keeps only this.page alive.
+   */
+  async closeExtraExtensionPages() {
+    const extOrigin = `chrome-extension://${this.extensionId}`;
+    const context = this.page.context();
+    const extras = context.pages().filter((p) => p !== this.page && p.url().startsWith(extOrigin));
+    if (extras.length > 0) {
+      debug(
+        `metamask.closeExtraExtensionPages: closing ${extras.length} extra page(s)`
+      );
+      await Promise.all(extras.map((p) => p.close()));
+    }
+  }
+  /**
+   * Poll the URL until it leaves a confirmation route. Uses polling instead
+   * of waitForURL because MetaMask uses HashRouter and hash-only changes
+   * are not reliably caught by Playwright's navigation events.
+   */
+  async waitForConfirmRouteExit(routePattern) {
+    const deadline = Date.now() + POST_CLICK_TIMEOUT;
+    while (routePattern.test(this.page.url()) && Date.now() < deadline) {
+      await this.page.waitForTimeout(500);
+    }
+  }
   /**
    * 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.
+   * Navigates to sidepanel.html so MetaMask's ConfirmationHandler routes
+   * to the pending approval, then waits for the button to become visible.
    */
   async waitAndClickButton(btnLocator) {
     debug(`metamask.waitAndClickButton: navigating to sidepanel`);
@@ -531,63 +575,36 @@ var Metamask = class extends Wallet {
       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()}`
+    await this.page.goto(sidepanelUrl);
+    let result = await waitForButtonOrPopup(BUTTON_OR_POPUP_TIMEOUT);
+    if (result === "timeout") {
+      debug(
+        `metamask.waitAndClickButton: first wait timed out, reloading. URL: ${this.page.url()}`
       );
+      await this.page.goto(sidepanelUrl);
+      result = await waitForButtonOrPopup(BUTTON_OR_POPUP_TIMEOUT);
     }
-    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()}`
-        );
-      });
+      await this.waitForConfirmRouteExit(confirmRoutePattern);
       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()}`
-        );
-      });
+      await this.dismissPopups();
+      await btnLocator.first().waitFor({ state: "visible", timeout: BUTTON_OR_POPUP_TIMEOUT });
+      await btnLocator.first().click();
+      await this.waitForConfirmRouteExit(confirmRoutePattern);
       return;
     }
     const isOnConfirmRoute = confirmRoutePattern.test(this.page.url());
     debug(
-      `metamask.waitAndClickButton: timeout after ${BUTTON_OR_POPUP_TIMEOUT}ms. URL: ${this.page.url()}, onConfirmRoute: ${isOnConfirmRoute}`
+      `metamask.waitAndClickButton: timeout. 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()}`
+      `[w3wallets] no button or popup found after waiting. URL: ${this.page.url()}`
     );
     await btnLocator.first().click({ timeout: LAST_RESORT_CLICK_TIMEOUT });
   }
@@ -612,6 +629,46 @@ var Metamask = class extends Wallet {
     await menuBtn.click({ force: true });
     await this.page.locator("text=Log out").click();
   }
+  /**
+   * Force-persist the vault by locking the wallet. Called by the cache builder
+   * before closing the browser context. MetaMask MV3 stores the vault lazily —
+   * locking forces the encrypted vault to be written to chrome.storage.local.
+   */
+  async beforeCacheClose() {
+    debug("metamask.beforeCacheClose: locking wallet to force vault persistence");
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    const menuBtn = this.page.getByTestId("account-options-menu-button");
+    const lockInput = this.page.getByTestId("unlock-password");
+    const state = await Promise.race([
+      menuBtn.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "ready"),
+      lockInput.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "locked")
+    ]).catch(() => "timeout");
+    debug(`metamask.beforeCacheClose: state=${state}`);
+    if (state === "ready") {
+      await this.lock();
+      await lockInput.waitFor({ state: "visible", timeout: LOCK_SCREEN_TIMEOUT }).catch(() => {
+      });
+    } else if (state === "timeout") {
+      debug("metamask.beforeCacheClose: forcing state sync via new UI connection");
+      const syncPage = await this.page.context().newPage();
+      await syncPage.goto(`chrome-extension://${this.extensionId}/home.html`);
+      await syncPage.waitForLoadState("networkidle");
+      const syncMenuBtn = syncPage.getByTestId("account-options-menu-button");
+      const syncLockInput = syncPage.getByTestId("unlock-password");
+      const syncState = await Promise.race([
+        syncMenuBtn.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "ready"),
+        syncLockInput.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "locked")
+      ]).catch(() => "timeout");
+      debug(`metamask.beforeCacheClose: syncPage state=${syncState}`);
+      if (syncState === "ready") {
+        await syncMenuBtn.click({ force: true });
+        await syncPage.locator("text=Log out").click();
+        await syncLockInput.waitFor({ state: "visible", timeout: LOCK_SCREEN_TIMEOUT }).catch(() => {
+        });
+      }
+      await syncPage.close();
+    }
+  }
   /**
    * Unlock MetaMask with password.
    * After unlocking, stabilizes the wallet UI by handling post-unlock
@@ -622,13 +679,21 @@ var Metamask = class extends Wallet {
     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
-    });
+    const lockInput = this.page.getByTestId("unlock-password");
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const state = await Promise.race([
+      lockInput.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "locked"),
+      readyIndicator.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "ready")
+    ]).catch(() => "timeout");
+    debug(`metamask.unlock: state=${state}`);
+    if (state === "locked") {
+      await lockInput.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");
   }

package/dist/index.mjs

@@ -68,8 +68,6 @@ 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;
 
@@ -363,9 +361,28 @@ var Metamask = class extends Wallet {
     });
     await openWalletBtn.click();
     await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const lockInput = this.page.getByTestId("unlock-password");
+    const state = await Promise.race([
+      readyIndicator.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "ready"),
+      lockInput.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "locked")
+    ]).catch(() => "timeout");
+    debug(`metamask.onboard: post-navigate state=${state}`);
+    if (state === "locked") {
+      debug("metamask.onboard: vault locked after onboarding, auto-unlocking");
+      await lockInput.fill(password ?? this.defaultPassword);
+      await this.page.getByTestId("unlock-submit").click();
+      await this.page.waitForSelector('[data-testid="unlock-password"]', {
+        state: "hidden",
+        timeout: LOCK_SCREEN_TIMEOUT
+      });
+      await this.stabilizePostUnlock();
+    }
+    await this.closeExtraExtensionPages();
     await this.page.goto(
       `chrome-extension://${this.extensionId}/sidepanel.html`
     );
+    await this.page.waitForLoadState("networkidle");
     debug("metamask.onboard: complete");
   }
   /**
@@ -481,10 +498,37 @@ var Metamask = class extends Wallet {
     }
     await expect(readyIndicator).toBeVisible({ timeout: POST_UNLOCK_TIMEOUT });
   }
+  /**
+   * Close extra MetaMask extension pages that the service worker opened
+   * during onboarding (e.g. home.html#/onboarding/completion).
+   * Keeps only this.page alive.
+   */
+  async closeExtraExtensionPages() {
+    const extOrigin = `chrome-extension://${this.extensionId}`;
+    const context = this.page.context();
+    const extras = context.pages().filter((p) => p !== this.page && p.url().startsWith(extOrigin));
+    if (extras.length > 0) {
+      debug(
+        `metamask.closeExtraExtensionPages: closing ${extras.length} extra page(s)`
+      );
+      await Promise.all(extras.map((p) => p.close()));
+    }
+  }
+  /**
+   * Poll the URL until it leaves a confirmation route. Uses polling instead
+   * of waitForURL because MetaMask uses HashRouter and hash-only changes
+   * are not reliably caught by Playwright's navigation events.
+   */
+  async waitForConfirmRouteExit(routePattern) {
+    const deadline = Date.now() + POST_CLICK_TIMEOUT;
+    while (routePattern.test(this.page.url()) && Date.now() < deadline) {
+      await this.page.waitForTimeout(500);
+    }
+  }
   /**
    * 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.
+   * Navigates to sidepanel.html so MetaMask's ConfirmationHandler routes
+   * to the pending approval, then waits for the button to become visible.
    */
   async waitAndClickButton(btnLocator) {
     debug(`metamask.waitAndClickButton: navigating to sidepanel`);
@@ -495,63 +539,36 @@ var Metamask = class extends Wallet {
       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()}`
+    await this.page.goto(sidepanelUrl);
+    let result = await waitForButtonOrPopup(BUTTON_OR_POPUP_TIMEOUT);
+    if (result === "timeout") {
+      debug(
+        `metamask.waitAndClickButton: first wait timed out, reloading. URL: ${this.page.url()}`
       );
+      await this.page.goto(sidepanelUrl);
+      result = await waitForButtonOrPopup(BUTTON_OR_POPUP_TIMEOUT);
     }
-    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()}`
-        );
-      });
+      await this.waitForConfirmRouteExit(confirmRoutePattern);
       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()}`
-        );
-      });
+      await this.dismissPopups();
+      await btnLocator.first().waitFor({ state: "visible", timeout: BUTTON_OR_POPUP_TIMEOUT });
+      await btnLocator.first().click();
+      await this.waitForConfirmRouteExit(confirmRoutePattern);
       return;
     }
     const isOnConfirmRoute = confirmRoutePattern.test(this.page.url());
     debug(
-      `metamask.waitAndClickButton: timeout after ${BUTTON_OR_POPUP_TIMEOUT}ms. URL: ${this.page.url()}, onConfirmRoute: ${isOnConfirmRoute}`
+      `metamask.waitAndClickButton: timeout. 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()}`
+      `[w3wallets] no button or popup found after waiting. URL: ${this.page.url()}`
     );
     await btnLocator.first().click({ timeout: LAST_RESORT_CLICK_TIMEOUT });
   }
@@ -576,6 +593,46 @@ var Metamask = class extends Wallet {
     await menuBtn.click({ force: true });
     await this.page.locator("text=Log out").click();
   }
+  /**
+   * Force-persist the vault by locking the wallet. Called by the cache builder
+   * before closing the browser context. MetaMask MV3 stores the vault lazily —
+   * locking forces the encrypted vault to be written to chrome.storage.local.
+   */
+  async beforeCacheClose() {
+    debug("metamask.beforeCacheClose: locking wallet to force vault persistence");
+    await this.page.goto(`chrome-extension://${this.extensionId}/home.html`);
+    const menuBtn = this.page.getByTestId("account-options-menu-button");
+    const lockInput = this.page.getByTestId("unlock-password");
+    const state = await Promise.race([
+      menuBtn.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "ready"),
+      lockInput.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "locked")
+    ]).catch(() => "timeout");
+    debug(`metamask.beforeCacheClose: state=${state}`);
+    if (state === "ready") {
+      await this.lock();
+      await lockInput.waitFor({ state: "visible", timeout: LOCK_SCREEN_TIMEOUT }).catch(() => {
+      });
+    } else if (state === "timeout") {
+      debug("metamask.beforeCacheClose: forcing state sync via new UI connection");
+      const syncPage = await this.page.context().newPage();
+      await syncPage.goto(`chrome-extension://${this.extensionId}/home.html`);
+      await syncPage.waitForLoadState("networkidle");
+      const syncMenuBtn = syncPage.getByTestId("account-options-menu-button");
+      const syncLockInput = syncPage.getByTestId("unlock-password");
+      const syncState = await Promise.race([
+        syncMenuBtn.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "ready"),
+        syncLockInput.waitFor({ state: "visible", timeout: MENU_BUTTON_TIMEOUT }).then(() => "locked")
+      ]).catch(() => "timeout");
+      debug(`metamask.beforeCacheClose: syncPage state=${syncState}`);
+      if (syncState === "ready") {
+        await syncMenuBtn.click({ force: true });
+        await syncPage.locator("text=Log out").click();
+        await syncLockInput.waitFor({ state: "visible", timeout: LOCK_SCREEN_TIMEOUT }).catch(() => {
+        });
+      }
+      await syncPage.close();
+    }
+  }
   /**
    * Unlock MetaMask with password.
    * After unlocking, stabilizes the wallet UI by handling post-unlock
@@ -586,13 +643,21 @@ var Metamask = class extends Wallet {
     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
-    });
+    const lockInput = this.page.getByTestId("unlock-password");
+    const readyIndicator = this.page.getByTestId("account-options-menu-button");
+    const state = await Promise.race([
+      lockInput.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "locked"),
+      readyIndicator.waitFor({ state: "visible", timeout: POST_UNLOCK_TIMEOUT }).then(() => "ready")
+    ]).catch(() => "timeout");
+    debug(`metamask.unlock: state=${state}`);
+    if (state === "locked") {
+      await lockInput.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");
   }

package/dist/scripts/cache.js

@@ -89,7 +89,8 @@ async function waitForStorageStable(helperPage, helperUrl) {
   const POLL_INTERVAL = STORAGE_POLL_INTERVAL;
   const STABLE_CHECKS_REQUIRED = STORAGE_STABLE_CHECKS;
   const start = Date.now();
-  let lastKeyCount = -1;
+  let lastHash = "";
+  let lastKeyCount = 0;
   let stableCount = 0;
   while (Date.now() - start < TIMEOUT) {
     await sleep(POLL_INTERVAL);
@@ -100,16 +101,19 @@ async function waitForStorageStable(helperPage, helperUrl) {
       { timeout: HELPER_PAGE_TIMEOUT }
     );
     const title = await helperPage.title();
-    const keyCount = parseInt(title.split(":")[1], 10);
+    const parts = title.split(":");
+    const keyCount = parseInt(parts[1], 10);
+    const hash = parts[2] ?? "";
     if (keyCount === 0) continue;
-    if (keyCount === lastKeyCount) {
+    if (hash === lastHash) {
       stableCount++;
     } else {
       stableCount = 1;
+      lastHash = hash;
       lastKeyCount = keyCount;
     }
     debug(
-      `Storage poll: ${keyCount} keys (stable ${stableCount}/${STABLE_CHECKS_REQUIRED})`
+      `Storage poll: ${keyCount} keys, hash=${hash.slice(0, 8)} (stable ${stableCount}/${STABLE_CHECKS_REQUIRED})`
     );
     if (stableCount >= STABLE_CHECKS_REQUIRED) {
       console.log(`  Storage stabilized at ${keyCount} keys`);
@@ -176,16 +180,26 @@ async function buildCacheForSetup(compiledFilePath, originalFilePath, options2 =
   await config.setupFn(wallet, page);
   await page.goto(`chrome-extension://${extensionId}/home.html`);
   await page.waitForLoadState("networkidle");
-  await page.goto(`chrome-extension://${extensionId}/home.html`);
-  await page.waitForLoadState("networkidle");
+  if (wallet.beforeCacheClose) {
+    debug("buildCache: calling wallet.beforeCacheClose()");
+    await wallet.beforeCacheClose();
+    await sleep(2e3);
+  }
   try {
     const extDir = import_path2.default.join(process.cwd(), W3WALLETS_DIR, config.extensionDir);
     const helperJs = import_path2.default.join(extDir, "_w3wallets_helper.js");
     const helperHtml = import_path2.default.join(extDir, "_w3wallets_helper.html");
     import_fs2.default.writeFileSync(
       helperJs,
-      `chrome.storage.local.get(null, (data) => {
-        document.title = "done:" + Object.keys(data).length;
+      `chrome.storage.local.get(null, async (data) => {
+        const keys = Object.keys(data);
+        const json = JSON.stringify(data);
+        // Compute a simple hash of all values via SubtleCrypto
+        const buf = new TextEncoder().encode(json);
+        const hashBuf = await crypto.subtle.digest("SHA-256", buf);
+        const hashArr = Array.from(new Uint8Array(hashBuf));
+        const hash = hashArr.map(b => b.toString(16).padStart(2, "0")).join("");
+        document.title = "done:" + keys.length + ":" + hash;
       });`
     );
     import_fs2.default.writeFileSync(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "w3wallets",
   "description": "browser wallets for playwright",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "homepage": "https://github.com/Maksandre/w3wallets",