@marigoldlabs/web3-tester 0.1.2 → 0.4.2

package/dist/real-wallet.js

@@ -1,27 +1,51 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { chromium } from '@playwright/test';
+import { extensionManifestVersion } from './metamask-extension.js';
+import { extensionPageUrl, launchRealWalletExtension, } from './real-wallet-extension.js';
 import { passwordForSetup } from './real-wallet-setup.js';
+export { resolveRealWalletHeadless, resolveRealWalletProfile } from './real-wallet-extension.js';
 const DEFAULT_EXTENSION_NAME = 'MetaMask';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const SHORT_TIMEOUT_MS = 2_000;
-const LOCATOR_PROBE_MS = 250;
+const LOCATOR_PROBE_MS = 100;
+// A short settle before 13.x account creation. The retry loop handles the
+// pathological public-SRP account-tree sync case; do not tax normal wallets
+// with the old multi-second fixed dwell.
+const ACCOUNT_TREE_SETTLE_MS = 250;
+const FULL_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
 const testId = (id) => `[data-testid="${id}"]`;
-function extensionUrl(extensionId, page = 'home.html') {
-    return `chrome-extension://${extensionId}/${page}`;
+/**
+ * @internal Resolves a generation-annotated selector stack against the
+ * configured generation: tagged entries of the other generation are dropped,
+ * bare entries pass through, and relative order is preserved.
+ */
+export function resolveGenLocators(locators, generation) {
+    const resolved = [];
+    for (const entry of locators) {
+        if ('gen' in entry) {
+            if (entry.gen === generation)
+                resolved.push(entry.loc);
+        }
+        else {
+            resolved.push(entry);
+        }
+    }
+    return resolved;
 }
-function extensionIdFromUrl(url) {
-    return /^chrome-extension:\/\/([^/]+)\//.exec(url)?.[1];
+/** @internal Maps an extension manifest version to the UI generation it ships. */
+export function walletGenerationForVersion(version) {
+    const major = Number.parseInt(version, 10);
+    return Number.isNaN(major) || major >= 13 ? '13x' : '12x';
 }
-export function resolveRealWalletProfile(profileDir) {
-    const resolved = path.resolve(profileDir);
-    const profileDirectory = path.basename(resolved);
-    const userDataDir = path.dirname(resolved);
-    const looksLikeChromeProfile = /^(?:Default|Profile \d+)$/.test(profileDirectory);
-    if (looksLikeChromeProfile && fs.existsSync(path.join(userDataDir, 'Local State'))) {
-        return { profileDirectory, userDataDir };
+function detectWalletGeneration(extensionPath) {
+    try {
+        return walletGenerationForVersion(extensionManifestVersion(extensionPath));
     }
-    return { userDataDir: resolved };
+    catch {
+        // No readable manifest version: assume the pinned default generation.
+        return '13x';
+    }
+}
+function extensionUrl(extensionId, page = 'home.html') {
+    return extensionPageUrl(extensionId, page);
 }
 async function isVisible(locator, timeout = SHORT_TIMEOUT_MS) {
     await locator.first().waitFor({ state: 'visible', timeout });
@@ -36,6 +60,24 @@ function wait(ms) {
         setTimeout(resolve, ms);
     });
 }
+async function realWalletTiming(label, action) {
+    if (process.env.WEB3_TESTER_REAL_WALLET_TIMING !== 'true')
+        return action();
+    const startedAt = Date.now();
+    try {
+        const result = await action();
+        process.stderr.write(`[web3-tester real-wallet timing] ${label} ${Date.now() - startedAt}ms\n`);
+        return result;
+    }
+    catch (error) {
+        process.stderr.write(`[web3-tester real-wallet timing] ${label} failed ${Date.now() - startedAt}ms\n`);
+        throw error;
+    }
+}
+function isRecoverablePageNavigationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /page crashed|target page, context or browser has been closed|browser has disconnected/i.test(message);
+}
 async function findVisibleLocator(locators, timeout = SHORT_TIMEOUT_MS, options = {}) {
     const deadline = Date.now() + timeout;
     do {
@@ -60,9 +102,9 @@ async function clickFirstVisible(locators, timeout = SHORT_TIMEOUT_MS, options =
         requireEnabled: options.requireEnabled ?? true,
     });
     if (!target)
-        return false;
+        return undefined;
     await target.click({ force: options.force, timeout });
-    return true;
+    return target;
 }
 async function fillFirstVisible(locators, value, timeout = DEFAULT_TIMEOUT_MS) {
     const target = await findVisibleLocator(locators, timeout);
@@ -71,13 +113,37 @@ async function fillFirstVisible(locators, value, timeout = DEFAULT_TIMEOUT_MS) {
     await target.fill(value);
     return true;
 }
+async function fillFirstVisibleStableValue(locators, value, timeout = DEFAULT_TIMEOUT_MS) {
+    const deadline = Date.now() + timeout;
+    do {
+        const remaining = Math.max(deadline - Date.now(), 1);
+        const target = await findVisibleLocator(locators, Math.min(DEFAULT_TIMEOUT_MS, remaining));
+        if (!target)
+            continue;
+        await target.fill(value, { timeout: Math.min(DEFAULT_TIMEOUT_MS, remaining) });
+        await wait(250);
+        const actual = await target
+            .inputValue({ timeout: 0 })
+            .catch(() => target.locator('input').first().inputValue({ timeout: 0 }).catch(() => undefined));
+        if (actual === value)
+            return true;
+        const delay = Math.min(LOCATOR_PROBE_MS, Math.max(deadline - Date.now(), 0));
+        if (delay > 0)
+            await wait(delay);
+    } while (Date.now() < deadline);
+    return false;
+}
 async function startSeedPhraseWordGrid(target, firstWord) {
     await target.fill(firstWord);
     await wait(250);
     await target.press('Space');
 }
+// MetaMask 12.x routes are home.html#onboarding/..., 13.x uses #/onboarding/...
+const isOnboardingRoute = (url) => /home\.html#\/?onboarding/.test(url);
 function metaMaskOnboardingLocators(page) {
     return [
+        page.locator(testId('onboarding-get-started-button')),
+        page.locator(testId('onboarding-welcome-banner-title')),
         page.locator(testId('onboarding-import-wallet')),
         page.locator(testId('onboarding-import-with-srp-button')),
         page.locator(testId('onboarding-create-wallet')),
@@ -86,6 +152,7 @@ function metaMaskOnboardingLocators(page) {
         page.locator(testId('import-srp-confirm')),
         page.locator(testId('create-password-new-input')),
         page.locator(testId('create-password-confirm-input')),
+        page.getByRole('button', { name: 'Get started' }),
         page.getByRole('button', { name: 'I have an existing wallet' }),
         page.getByRole('button', { name: 'Create a new wallet' }),
         page.getByRole('button', { name: 'Import using Secret Recovery Phrase' }),
@@ -93,7 +160,7 @@ function metaMaskOnboardingLocators(page) {
     ];
 }
 async function isMetaMaskOnboardingVisible(page) {
-    return page.url().includes('/home.html#/onboarding') || Boolean(await findVisibleLocator(metaMaskOnboardingLocators(page), SHORT_TIMEOUT_MS));
+    return isOnboardingRoute(page.url()) || Boolean(await findVisibleLocator(metaMaskOnboardingLocators(page), SHORT_TIMEOUT_MS));
 }
 function metaMaskSeedPhraseInputLocators(page) {
     return [
@@ -130,11 +197,11 @@ async function fillMetaMaskSeedPhraseWordGrid(page, words, startIndex = 0) {
     }
 }
 async function isMetaMaskSeedPhraseImportVisible(page) {
-    return (page.url().includes('/onboarding/import-with-recovery-phrase') ||
+    return (/#\/?onboarding\/import-with-recovery-phrase/.test(page.url()) ||
         Boolean(await findVisibleLocator(metaMaskSeedPhraseImportLocators(page), SHORT_TIMEOUT_MS)));
 }
 async function isMetaMaskCreatePasswordVisible(page) {
-    return (page.url().includes('/onboarding/create-password') ||
+    return (/#\/?onboarding\/create-password/.test(page.url()) ||
         Boolean(await findVisibleLocator([page.locator(testId('create-password-new-input')), page.locator('input[type="password"]').nth(0)], SHORT_TIMEOUT_MS)));
 }
 async function waitForMetaMaskReady(page) {
@@ -147,14 +214,50 @@ function metaMaskUnlockPasswordLocators(page) {
 function metaMaskUnlockSubmitLocators(page) {
     return [page.locator(testId('unlock-submit')), page.getByRole('button', { name: 'Unlock' })];
 }
-async function isMetaMaskUnlockVisible(page) {
-    return Boolean(await findVisibleLocator(metaMaskUnlockPasswordLocators(page), SHORT_TIMEOUT_MS));
+async function isMetaMaskUnlockVisible(page, timeout = LOCATOR_PROBE_MS) {
+    const routeLooksLocked = /#\/(?:unlock|locked)/i.test(page.url());
+    return Boolean(await findVisibleLocator(metaMaskUnlockPasswordLocators(page), routeLooksLocked ? Math.max(timeout, SHORT_TIMEOUT_MS) : timeout));
+}
+async function closeMetaMaskOverlay(page, timeout = LOCATOR_PROBE_MS) {
+    // Dismiss stacked overlays ("what's new" modals, popovers) that intercept
+    // pointer events over the whole home screen.
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const overlay = await findVisibleLocator([
+            page.locator(`${testId('whats-new-modal')}, .mm-modal-content, [role="dialog"]`),
+        ], timeout, { requireEnabled: false });
+        if (!overlay)
+            return;
+        const closed = await clickFirstVisible([
+            overlay.locator(testId('popover-close')),
+            overlay.locator(testId('not-now-button')),
+            overlay.locator('button[aria-label="Close"]'),
+            overlay.getByRole('button', { name: /^(Close|Got it|Done|Skip|Maybe later|Not now)$/i }),
+            overlay.locator('button').filter({ hasText: /^(Close|Got it|Done|Skip|Maybe later|Not now)$/i }),
+            page.locator('.mm-modal-content button[aria-label="Close"]'),
+            page.locator('.mm-modal-content .mm-modal-header button').first(),
+        ], timeout, { force: true }).catch(() => undefined);
+        if (!closed)
+            return;
+        await wait(250);
+    }
+}
+function metaMaskNetworkPickerLocators(page) {
+    return [
+        page.locator(testId('network-display')),
+        page.locator(testId('sort-by-networks')),
+        page.getByRole('button', { name: /select a network|network menu/i }),
+    ];
 }
-async function closeMetaMaskOverlay(page) {
-    await clickFirstVisible([
-        page.locator(testId('popover-close')),
-        page.locator('.mm-modal-content .mm-modal-header button').first(),
-    ], SHORT_TIMEOUT_MS).catch(() => false);
+function metaMaskResetAccountControlLocators(page) {
+    return [
+        page.locator(testId('developer-options-delete-activity-and-nonce-data')),
+        page.locator(testId('developer-options-delete-activity-and-nonce-data')).getByRole('button'),
+        page.locator(testId('advanced-setting-reset-account')).getByRole('button'),
+        page.getByRole('button', {
+            name: /Clear activity( and nonce data| tab data)?|Delete activity and nonce data/i,
+        }),
+        page.getByText(/Clear activity( and nonce data| tab data)?|Delete activity and nonce data/i),
+    ];
 }
 function metaMaskAccountMenuLocators(page) {
     return [
@@ -163,6 +266,13 @@ function metaMaskAccountMenuLocators(page) {
         page.getByRole('button', { name: /Account options|Account menu/i }),
     ];
 }
+function metaMaskAccountPickerTriggerLocators(page) {
+    return [
+        page.locator(`button:has(${testId('account-menu-icon')})`),
+        page.locator(testId('account-menu-icon')),
+        page.getByRole('button', { name: /Account menu/i }),
+    ];
+}
 function metaMaskPromptActions(page) {
     return [
         page.locator(testId('onboarding-complete-done')),
@@ -194,67 +304,34 @@ async function waitForMetaMaskHome(page, timeout = DEFAULT_TIMEOUT_MS) {
             return true;
         if (await clickMetaMaskPromptAction(page, SHORT_TIMEOUT_MS))
             continue;
+        if (isOnboardingRoute(page.url())) {
+            await routeMetaMaskTabToHome(page);
+            continue;
+        }
         const delay = Math.min(LOCATOR_PROBE_MS, Math.max(deadline - Date.now(), 0));
         if (delay > 0)
             await wait(delay);
     } while (Date.now() < deadline);
     return Boolean(await findVisibleLocator(metaMaskAccountMenuLocators(page), SHORT_TIMEOUT_MS));
 }
-async function discoverExtensionIdFromRuntime(context) {
-    const workerId = context.serviceWorkers().map((worker) => extensionIdFromUrl(worker.url())).find(Boolean);
-    if (workerId)
-        return workerId;
-    const pageId = context.pages().map((page) => extensionIdFromUrl(page.url())).find(Boolean);
-    if (pageId)
-        return pageId;
-    const worker = await context.waitForEvent('serviceworker', { timeout: 10_000 }).catch(() => undefined);
-    if (worker) {
-        const extensionId = extensionIdFromUrl(worker.url());
-        if (extensionId)
-            return extensionId;
-    }
-    return undefined;
-}
-async function discoverExtensionIdFromManagementApi(context, extensionName) {
-    const page = await context.newPage();
-    try {
-        await page.goto('chrome://extensions', { waitUntil: 'domcontentloaded' });
-        const extensions = await page.evaluate(() => {
-            const chromeApi = globalThis;
-            return new Promise((resolve, reject) => {
-                if (!chromeApi.chrome?.management?.getAll) {
-                    reject(new Error('chrome.management.getAll is not available on chrome://extensions.'));
-                    return;
-                }
-                chromeApi.chrome.management.getAll((items) => {
-                    const error = chromeApi.chrome?.runtime?.lastError;
-                    if (error)
-                        reject(new Error(error.message ?? 'Unable to enumerate Chrome extensions.'));
-                    else
-                        resolve(items);
-                });
-            });
-        });
-        const exact = extensions.find((extension) => extension.name.toLowerCase() === extensionName.toLowerCase());
-        if (exact)
-            return exact.id;
-        const available = extensions.map((extension) => extension.name).sort().join(', ');
-        throw new Error(`Unable to find extension "${extensionName}". Installed extensions: ${available || 'none'}.`);
-    }
-    finally {
-        await page.close().catch(() => undefined);
-    }
-}
-async function getExtensionId(context, extensionName) {
-    return ((await discoverExtensionIdFromRuntime(context)) ??
-        (await discoverExtensionIdFromManagementApi(context, extensionName)));
+async function routeMetaMaskTabToHome(page) {
+    const homeUrl = page.url().split('#')[0];
+    await page.goto(`${homeUrl}#/`).catch(() => undefined);
+    await waitForMetaMaskReady(page);
 }
 async function openExtensionHome(context, extensionId) {
-    const homeUrl = extensionUrl(extensionId);
-    const existing = context.pages().find((page) => page.url().startsWith(homeUrl));
-    const page = existing ?? (await context.newPage());
-    if (page.url() !== homeUrl)
-        await page.goto(homeUrl);
+    const homeUrl = extensionUrl(extensionId, 'home.html');
+    const page = context
+        .pages()
+        .find((candidate) => {
+        if (candidate.isClosed())
+            return false;
+        const url = candidate.url();
+        return url === homeUrl || url.startsWith(`${homeUrl}#`);
+    }) ?? (await context.newPage());
+    if (page.url() !== `${homeUrl}#/`) {
+        await page.goto(`${homeUrl}#/`, { waitUntil: 'domcontentloaded' });
+    }
     await waitForMetaMaskReady(page);
     return page;
 }
@@ -267,9 +344,9 @@ function extensionPageUrlPrefix(extensionId) {
 function metaMaskActionContentLocators(page) {
     return [
         page.getByRole('heading', {
-            name: /Spending cap request|Transaction request|Signature request|Sign-in request|Permission request/i,
+            name: /Spending cap request|Transaction request|Signature request|Sign-in request|Permission request|Add suggested tokens?/i,
         }),
-        page.getByText(/Spending cap request|Transaction request|Signature request|Sign-in request|Permission request|This site wants permission/i),
+        page.getByText(/Spending cap request|Transaction request|Signature request|Sign-in request|Permission request|This site wants permission|Add suggested tokens?/i),
     ];
 }
 function metaMaskActionControlLocators(page) {
@@ -325,24 +402,44 @@ async function getNotificationPage(context, extensionId, timeout = DEFAULT_TIMEO
     const prefix = notificationUrlPrefix(extensionId);
     const extensionPrefix = extensionPageUrlPrefix(extensionId);
     const startedAt = Date.now();
+    // MetaMask suppresses its popup window when extension tabs are already
+    // open; after a short grace period for a spontaneous popup, open
+    // notification.html ourselves — pending confirmations render there.
+    const forceAt = startedAt;
+    let forcedPage;
     let page = await findMetaMaskActionPage(context, extensionId);
-    let notificationPage = findMetaMaskNotificationPage(context, extensionId);
     while (!page && Date.now() - startedAt < timeout) {
         const remaining = Math.max(timeout - (Date.now() - startedAt), 1_000);
-        const candidate = await context.waitForEvent('page', { timeout: Math.min(remaining, 1_000) }).catch(() => undefined);
-        if (candidate) {
-            await candidate
-                .waitForURL((url) => url.href.startsWith(prefix) || url.href.startsWith(extensionPrefix), {
-                timeout: Math.min(remaining, 5_000),
-            })
+        if (!forcedPage && Date.now() >= forceAt) {
+            forcedPage = await context.newPage();
+            await forcedPage.goto(extensionUrl(extensionId, 'notification.html')).catch(() => undefined);
+            await waitForMetaMaskReady(forcedPage);
+        }
+        else {
+            const waitForPopupMs = forcedPage ? 1_000 : Math.max(forceAt - Date.now(), 1);
+            const candidate = await context
+                .waitForEvent('page', { timeout: Math.min(remaining, waitForPopupMs, 1_000) })
                 .catch(() => undefined);
+            if (candidate) {
+                await candidate
+                    .waitForURL((url) => url.href.startsWith(prefix) || url.href.startsWith(extensionPrefix), {
+                    timeout: Math.min(remaining, 5_000),
+                })
+                    .catch(() => undefined);
+            }
         }
         page = await findMetaMaskActionPage(context, extensionId);
-        notificationPage = findMetaMaskNotificationPage(context, extensionId) ?? notificationPage;
     }
-    page ??= notificationPage;
-    if (!page)
+    // Last resort: any notification.html page (including the forced one) even
+    // if the action-content matchers did not recognize the confirmation copy.
+    page ??= findMetaMaskNotificationPage(context, extensionId);
+    if (!page) {
+        await forcedPage?.close().catch(() => undefined);
         throw new Error('Timed out waiting for MetaMask notification window.');
+    }
+    if (forcedPage && forcedPage !== page && !forcedPage.isClosed()) {
+        await forcedPage.close().catch(() => undefined);
+    }
     await waitForMetaMaskReady(page);
     await page.bringToFront().catch(() => undefined);
     return page;
@@ -350,6 +447,42 @@ async function getNotificationPage(context, extensionId, timeout = DEFAULT_TIMEO
 function shortAddress(address) {
     return `${address.slice(0, 6)}...${address.slice(-4)}`.toLowerCase();
 }
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** @internal Validates and trims a 32-byte hex private key (0x optional). */
+export function normalizePrivateKey(privateKey) {
+    const trimmed = privateKey.trim();
+    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(trimmed)) {
+        throw new Error('importWalletFromPrivateKey requires a 32-byte hex private key (with or without 0x).');
+    }
+    return trimmed;
+}
+/** @internal */
+export function isFullTxHash(value) {
+    return typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value);
+}
+/**
+ * @internal Matches an account picker row by display name, or by full /
+ * shortened address when the identifier is an address.
+ */
+export function accountRowMatcher(identifier) {
+    if (FULL_ADDRESS_PATTERN.test(identifier)) {
+        return new RegExp(`${escapeRegExp(identifier)}|${escapeRegExp(shortAddress(identifier))}`, 'i');
+    }
+    return new RegExp(escapeRegExp(identifier), 'i');
+}
+// Account picker rows across UI generations: 12.x popover items, 13.x
+// multichain account cells.
+function accountRowLocator(page) {
+    return page.locator('.multichain-account-menu-popover__list--menu-item, .multichain-account-cell, .multichain-account-list-item');
+}
+function accountPickerContentLocators(page) {
+    return [
+        accountRowLocator(page).first(),
+        page.locator(testId('account-list-add-wallet-button')),
+        page.locator(testId('multichain-account-list-search')),
+        page.locator(testId('multichain-account-menu-popover-action-button')),
+    ];
+}
 async function pageContainsAddress(page, address) {
     const normalizedAddress = address.toLowerCase();
     const text = ((await page.locator('body').textContent({ timeout: SHORT_TIMEOUT_MS }).catch(() => '')) ?? '')
@@ -393,6 +526,18 @@ async function importMetaMaskWallet(page, setup) {
         throw new Error('MetaMask is on onboarding. Provide setup.seedPhrase to import a wallet through web3-tester, or use a preconfigured persistent profile.');
     }
     await page.bringToFront().catch(() => undefined);
+    // 12.23+ shows a welcome interstitial followed by a Terms of Use dialog
+    // (scroll to bottom, check, agree) before the create/import choice.
+    await clickFirstVisible([page.locator(testId('onboarding-get-started-button'))], SHORT_TIMEOUT_MS);
+    const termsOfUseCheckbox = page.locator(testId('terms-of-use-checkbox'));
+    if (await isVisible(termsOfUseCheckbox, SHORT_TIMEOUT_MS).catch(() => false)) {
+        await clickFirstVisible([page.locator(testId('terms-of-use-scroll-button'))], SHORT_TIMEOUT_MS);
+        await termsOfUseCheckbox.click();
+        const agreed = await clickFirstVisible([page.locator(testId('terms-of-use-agree-button'))], DEFAULT_TIMEOUT_MS);
+        if (!agreed)
+            throw new Error('Unable to accept the MetaMask Terms of Use.');
+        await waitForMetaMaskReady(page);
+    }
     const terms = page.locator(testId('onboarding-terms-checkbox'));
     if (await isVisible(terms, SHORT_TIMEOUT_MS).catch(() => false)) {
         await terms.check();
@@ -442,7 +587,7 @@ async function importMetaMaskWallet(page, setup) {
     const passwordSubmitted = await clickFirstVisible([page.locator(testId('create-password-submit')), page.getByRole('button', { name: 'Import my wallet' })], DEFAULT_TIMEOUT_MS);
     if (!passwordSubmitted)
         throw new Error('Unable to submit MetaMask import password.');
-    await finishMetaMaskOnboarding(page);
+    await finishMetaMaskOnboarding(page, password);
 }
 async function unlockMetaMask(page, password) {
     const passwordFilled = await fillFirstVisible(metaMaskUnlockPasswordLocators(page), password, DEFAULT_TIMEOUT_MS);
@@ -463,24 +608,38 @@ async function unlockMetaMaskIfNeeded(page, password) {
     await unlockMetaMask(page, password);
     return true;
 }
-async function finishMetaMaskOnboarding(page) {
+async function finishMetaMaskOnboarding(page, password) {
     for (let attempt = 0; attempt < 6; attempt += 1) {
         await waitForMetaMaskReady(page);
         const actions = [...metaMaskPromptActions(page), ...metaMaskTextPromptActions(page)];
-        const onSetupScreen = page.url().includes('/home.html#/onboarding') ||
+        const onSetupScreen = isOnboardingRoute(page.url()) ||
             Boolean(await findVisibleLocator(actions, SHORT_TIMEOUT_MS));
         if (!onSetupScreen)
-            return;
+            break;
         const advanced = await clickMetaMaskPromptAction(page, 5_000);
         if (!advanced)
             break;
     }
-    if (await waitForMetaMaskHome(page, 10_000))
-        return;
-    if (page.url().includes('/home.html#/onboarding') ||
-        (await findVisibleLocator([...metaMaskPromptActions(page), ...metaMaskTextPromptActions(page)], SHORT_TIMEOUT_MS))) {
+    // MetaMask 13.x defaults to opening the wallet in Chrome's side panel, so
+    // clicking "Open wallet" disables the button and leaves the onboarding tab
+    // parked on #/onboarding/completion (Playwright can't drive the side
+    // panel). Route the tab to the wallet home ourselves.
+    if (isOnboardingRoute(page.url())) {
+        await routeMetaMaskTabToHome(page);
+        // Navigating away from completion can re-lock the freshly created vault.
+        await unlockMetaMaskIfNeeded(page, password);
+    }
+    if (!(await waitForMetaMaskHome(page, DEFAULT_TIMEOUT_MS))) {
         throw new Error('MetaMask wallet import did not complete onboarding.');
     }
+    // MetaMask 13.x persists extension state through a debounced write
+    // (app/scripts/lib/safe-reload.ts OperationSafener — a lodash
+    // trailing-edge debounce, wait 1000ms, no maxWait — wrapping
+    // persistenceManager.set()). Give the UI a short beat to enqueue the
+    // post-onboarding write; the real flush guarantee lives in
+    // buildWalletProfile, which polls the profile's storage until the write
+    // lands and goes quiet before closing.
+    await page.waitForTimeout(500);
 }
 class MetaMaskRealWallet {
     context;
@@ -488,20 +647,44 @@ class MetaMaskRealWallet {
     extensionId;
     expectedAddress;
     walletPassword;
-    constructor(context, homePage, extensionId, expectedAddress, walletPassword) {
+    generation;
+    // Set only after web3-tester has actively selected an account by full
+    // address in this browser session. Do not seed it from launch options:
+    // launch-time expectedAddress is a validation target, not proof of selection.
+    trustedSelectedAddress;
+    constructor(context, homePage, extensionId, 
+    // Mutable: account mutations (switchAccount, imports, new accounts) must
+    // invalidate it, or later address checks may target stale UI text.
+    expectedAddress, walletPassword, generation = '13x') {
         this.context = context;
         this.homePage = homePage;
         this.extensionId = extensionId;
         this.expectedAddress = expectedAddress;
         this.walletPassword = walletPassword;
+        this.generation = generation;
+    }
+    // Generation-aware variant of clickFirstVisible: the annotated stack is
+    // resolved against the configured generation first, and an empty resolution
+    // short-circuits without probing the page at all.
+    async clickFirst(locators, timeout, options) {
+        const resolved = resolveGenLocators(locators, this.generation);
+        if (!resolved.length)
+            return undefined;
+        return clickFirstVisible(resolved, timeout, options);
     }
     async approveTokenPermission(options) {
         const page = await this.notificationPage();
         if (options?.spendLimit === 'max') {
-            await clickFirstVisible([page.locator(testId('custom-spending-cap-max-button'))], SHORT_TIMEOUT_MS);
+            const clicked = await clickFirstVisible([page.locator(testId('custom-spending-cap-max-button'))], SHORT_TIMEOUT_MS);
+            if (!clicked) {
+                throw new Error('A max spendLimit was requested but the MetaMask spending-cap "Max" control was not found.');
+            }
         }
         else if (typeof options?.spendLimit === 'number') {
-            await fillFirstVisible([page.locator(testId('custom-spending-cap-input'))], String(options.spendLimit), SHORT_TIMEOUT_MS);
+            const filled = await fillFirstVisible([page.locator(testId('custom-spending-cap-input'))], String(options.spendLimit), SHORT_TIMEOUT_MS);
+            if (!filled) {
+                throw new Error('A numeric spendLimit was requested but the MetaMask spending-cap input was not found.');
+            }
         }
         await this.confirmFooterAction(page);
         if (!page.isClosed()) {
@@ -533,19 +716,56 @@ class MetaMaskRealWallet {
         if (!signed)
             throw new Error('Unable to confirm MetaMask signature request.');
         await clickFirstVisible([page.locator(testId('signature-warning-sign-button'))], SHORT_TIMEOUT_MS);
+        await Promise.race([
+            page.waitForEvent('close', { timeout: 5_000 }).catch(() => undefined),
+            signed.waitFor({ state: 'hidden', timeout: 5_000 }).catch(() => undefined),
+        ]);
+        if (!page.isClosed())
+            await page.close().catch(() => undefined);
     }
     async confirmTransaction(options) {
-        let page = await this.notificationPage();
+        let page = await realWalletTiming('confirmTransaction.notificationPage', () => this.notificationPage());
         for (let attempt = 0; attempt < 3; attempt += 1) {
-            await this.applyGasSetting(page, options?.gasSetting);
-            await clickFirstVisible([page.locator('.set-approval-for-all-warning__footer__approve-button')], SHORT_TIMEOUT_MS);
-            await this.confirmFooterAction(page);
-            await wait(1_000);
-            const nextPage = await findMetaMaskActionPage(this.context, this.extensionId);
+            await realWalletTiming(`confirmTransaction.applyGasSetting.attempt${attempt + 1}`, () => this.applyGasSetting(page, options?.gasSetting));
+            await realWalletTiming(`confirmTransaction.warningApproval.attempt${attempt + 1}`, () => clickFirstVisible([page.locator('.set-approval-for-all-warning__footer__approve-button')], LOCATOR_PROBE_MS));
+            const clicked = await realWalletTiming(`confirmTransaction.confirmFooter.attempt${attempt + 1}`, () => this.confirmFooterAction(page));
+            // The click registered once the confirmed control leaves the view or
+            // the popup closes — no fixed sleep deciding "settled".
+            await realWalletTiming(`confirmTransaction.waitClickSettled.attempt${attempt + 1}`, () => Promise.race([
+                clicked.waitFor({ state: 'hidden', timeout: 10_000 }).catch(() => undefined),
+                page.waitForEvent('close', { timeout: 10_000 }).catch(() => undefined),
+            ]));
+            if (!page.isClosed()) {
+                // Same window advanced to another confirmation step.
+                const nextStep = await realWalletTiming(`confirmTransaction.findNextStep.attempt${attempt + 1}`, () => findVisibleLocator([
+                    page.locator([
+                        testId('confirm-footer-button'),
+                        testId('confirmation-submit-button'),
+                        testId('page-container-footer-next'),
+                        testId('request-signature__sign'),
+                        testId('signature-sign-button'),
+                    ].join(', ')),
+                ], LOCATOR_PROBE_MS, { requireEnabled: false }));
+                if (!nextStep)
+                    return;
+                await realWalletTiming(`confirmTransaction.waitNextStepReady.attempt${attempt + 1}`, () => waitForMetaMaskReady(page));
+                continue;
+            }
+            // Popup closed: give a follow-up notification window (approve + action
+            // flows) a moment to appear.
+            const deadline = Date.now() + 1_500;
+            let nextPage;
+            await realWalletTiming(`confirmTransaction.findFollowupPage.attempt${attempt + 1}`, async () => {
+                while (Date.now() < deadline && !nextPage) {
+                    nextPage = await findMetaMaskActionPage(this.context, this.extensionId);
+                    if (!nextPage)
+                        await wait(LOCATOR_PROBE_MS);
+                }
+            });
             if (!nextPage)
                 return;
             page = nextPage;
-            await waitForMetaMaskReady(page);
+            await realWalletTiming(`confirmTransaction.waitFollowupReady.attempt${attempt + 1}`, () => waitForMetaMaskReady(page));
             await page.bringToFront().catch(() => undefined);
         }
         throw new Error('MetaMask transaction confirmation did not settle after multiple confirmation steps.');
@@ -560,25 +780,293 @@ class MetaMaskRealWallet {
         }
     }
     async getAccountAddress() {
+        if (this.generation === '13x' && this.trustedSelectedAddress) {
+            return this.trustedSelectedAddress;
+        }
         const page = await this.home();
         await waitForMetaMaskHome(page);
         await closeMetaMaskOverlay(page);
         if (this.expectedAddress && await pageContainsAddress(page, this.expectedAddress)) {
             return this.expectedAddress;
         }
-        const openedMenu = await clickFirstVisible(metaMaskAccountMenuLocators(page), DEFAULT_TIMEOUT_MS);
-        if (!openedMenu)
-            throw new Error('Unable to open MetaMask account options menu.');
-        const openedDetails = await clickFirstVisible([page.locator(testId('account-list-menu-details'))], DEFAULT_TIMEOUT_MS);
-        if (!openedDetails)
-            throw new Error('Unable to open MetaMask account details.');
-        const addressText = page.locator(testId('address-copy-button-text')).first();
-        await addressText.waitFor({ state: 'visible', timeout: DEFAULT_TIMEOUT_MS });
-        const address = (await addressText.textContent())?.trim();
+        // 12.x exposes a header copy button (an extension copy control that uses
+        // document.execCommand('copy')) that puts the full address on the
+        // clipboard; reading it via a synthetic paste avoids the account-details
+        // modal entirely (extension pages block evaluate via LavaMoat, normal
+        // pages do not). 13.x has no header copy control — the tag skips it.
+        const headerCopied = await this.clickFirst([{ gen: '12x', loc: page.locator(testId('app-header-copy-button')) }], SHORT_TIMEOUT_MS);
+        if (headerCopied) {
+            const pasted = await this.readClipboardViaPaste();
+            if (pasted && FULL_ADDRESS_PATTERN.test(pasted))
+                return pasted;
+        }
+        await this.openAccountDetailsModal(page, 90_000);
+        // Read the full address from whichever copy affordance the modal exposes
+        // (12.x: address-copy-button-text; 13.x addresses view:
+        // multichain-address-row-copy-button). The visible text may be shortened,
+        // so prefer clicking the copy control and reading the clipboard.
+        const addressCopy = await findVisibleLocator([
+            page.locator(testId('address-copy-button-text')),
+            page.locator(testId('multichain-address-row-copy-button')),
+            page.locator(testId('address-qr-code-modal-copy-button')),
+        ], DEFAULT_TIMEOUT_MS, { requireEnabled: false });
+        if (!addressCopy) {
+            throw new Error('Unable to find the MetaMask account address in the details view.');
+        }
+        const elementText = (await addressCopy.textContent())?.trim();
+        if (elementText && FULL_ADDRESS_PATTERN.test(elementText)) {
+            await this.closeAccountDetailsAfterRead(page);
+            return elementText;
+        }
+        await addressCopy.click().catch(() => undefined);
+        const pasted = await this.readClipboardViaPaste();
+        await this.closeAccountDetailsAfterRead(page);
+        if (pasted && FULL_ADDRESS_PATTERN.test(pasted)) {
+            return pasted;
+        }
+        throw new Error('Unable to read the selected MetaMask account address from the UI.');
+    }
+    // Opens the account address view. 12.x: account-options (3-dot) menu ->
+    // "Account details". 13.x multichain UI: account picker -> the selected
+    // account row's address menu -> "Addresses" (the "Account details" item
+    // there is the export-keys view, not the address).
+    async openAccountDetailsModal(page, timeout = 90_000) {
+        const deadline = Date.now() + timeout;
+        const remaining = (max = DEFAULT_TIMEOUT_MS) => Math.max(Math.min(max, deadline - Date.now()), 1);
+        if (this.generation === '12x') {
+            const menuOpened = await clickFirstVisible([page.locator(testId('account-options-menu-button'))], remaining(SHORT_TIMEOUT_MS));
+            const detailsOpened = menuOpened &&
+                (await clickFirstVisible([page.locator(testId('account-list-menu-details'))], remaining()));
+            if (!detailsOpened)
+                throw new Error('Unable to open the MetaMask account details view.');
+            return;
+        }
+        // 13.x multichain path. Prefer the home header's active-account address
+        // menu (default-address-menu-button) so we read the *selected* account
+        // rather than an arbitrary cell — a single SRP import derives many
+        // accounts whose picker order does not start at the active one. The menu
+        // render can race account-tree refreshes after imports; retry from a clean
+        // home render before declaring the address view unavailable.
+        const home = page.url().split('#')[0];
+        let addressMenuOpened = false;
+        for (let attempt = 0; attempt < 3 && Date.now() < deadline; attempt += 1) {
+            if (attempt > 0) {
+                await page.keyboard.press('Escape').catch(() => undefined);
+                await closeMetaMaskOverlay(page);
+                await page.goto(`${home}#/`);
+                await waitForMetaMaskHome(page, remaining());
+            }
+            addressMenuOpened = Boolean(await clickFirstVisible([page.locator(testId('default-address-menu-button'))], remaining(attempt === 0 ? SHORT_TIMEOUT_MS : DEFAULT_TIMEOUT_MS), { requireEnabled: false }));
+            if (!addressMenuOpened) {
+                await this.openAccountPicker(page, remaining(60_000));
+                const expected = this.expectedAddress?.toLowerCase();
+                const selectedRow = expected
+                    ? page
+                        .locator('[data-testid^="multichain-account-cell"]')
+                        .filter({ hasText: new RegExp(`${expected.slice(0, 6)}|${shortAddress(expected)}`, 'i') })
+                        .first()
+                    : page.locator('[data-testid^="multichain-account-cell"]').first();
+                addressMenuOpened = Boolean((await clickFirstVisible([selectedRow.locator(testId('multichain-account-cell-end-accessory'))], remaining(), { requireEnabled: false })) ??
+                    (await clickFirstVisible([page.getByRole('button', { name: 'Open multichain account address menu' }).first()], remaining(SHORT_TIMEOUT_MS), { requireEnabled: false })));
+            }
+            if (!addressMenuOpened)
+                continue;
+            const detailsOpened = await clickFirstVisible([
+                page.locator(testId('multichain-account-menu-item-addresses')),
+                page.getByRole('menuitem', { name: /^Addresses$/i }),
+                page.getByText('Addresses', { exact: true }),
+                page.locator(testId('multichain-account-menu-item-accountDetails')),
+            ], remaining(attempt === 0 ? DEFAULT_TIMEOUT_MS : SHORT_TIMEOUT_MS), { requireEnabled: false });
+            if (detailsOpened)
+                return;
+        }
+        if (!addressMenuOpened)
+            throw new Error('Unable to open the MetaMask account address menu.');
+        throw new Error('Unable to open the MetaMask account address view.');
+    }
+    async closeAccountDetailsAfterRead(page) {
+        if (this.generation === '13x') {
+            await page.close().catch(() => undefined);
+            return;
+        }
         await closeMetaMaskOverlay(page);
-        if (!address?.startsWith('0x'))
-            throw new Error('Unable to read selected MetaMask account address.');
-        return address;
+    }
+    async readClipboardViaPaste() {
+        const page = await this.context.newPage();
+        try {
+            await page.goto('data:text/html,<input id="paste-target" autofocus>');
+            const input = page.locator('#paste-target');
+            await input.click();
+            await page.keyboard.press('ControlOrMeta+v');
+            const value = (await input.inputValue()).trim();
+            return value || undefined;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+    }
+    async addNetwork(network) {
+        let page = await this.home();
+        const addOnce = async () => {
+            const home = page.url().split('#')[0];
+            await waitForMetaMaskHome(page);
+            await closeMetaMaskOverlay(page);
+            const pickerOpened = await clickFirstVisible(metaMaskNetworkPickerLocators(page), DEFAULT_TIMEOUT_MS);
+            if (!pickerOpened)
+                throw new Error('Unable to open the MetaMask network picker.');
+            // 13.x splits the picker into "Default"/popular and "Custom" tabs; the
+            // custom RPC form lives behind the Custom tab. Force the tab click because
+            // its underline animation can keep the element "unstable" long after it
+            // is visibly clickable.
+            if (this.generation === '13x') {
+                const customTab = await clickFirstVisible([page.getByRole('tab', { name: /^Custom$/i })], DEFAULT_TIMEOUT_MS, { force: true });
+                if (!customTab)
+                    throw new Error('Unable to open the MetaMask custom-network tab.');
+                await wait(250);
+            }
+            const addStarted = await clickFirstVisible([
+                page.locator(testId('network-list-menu-add-button')),
+                page.getByRole('button', { name: /Add a custom network|Add custom network/i }),
+                page.getByText(/Add a custom network/i),
+                page.getByRole('button', { name: /^Add network$/i }),
+            ], DEFAULT_TIMEOUT_MS);
+            if (!addStarted)
+                throw new Error('Unable to start the MetaMask add-network flow.');
+            // Versions that list popular networks first need one more hop.
+            await clickFirstVisible([page.locator(testId('add-network-manually')), page.getByText(/Add a network manually/i)], SHORT_TIMEOUT_MS);
+            const nameFilled = await fillFirstVisible([page.locator(testId('network-form-network-name')), page.locator('input[name="networkName"]')], network.name);
+            if (!nameFilled)
+                throw new Error('Unable to fill the MetaMask network name field.');
+            // RPC URL: newer MetaMask uses a dropdown with a dedicated add-RPC form;
+            // older versions render a plain input.
+            const rpcDirect = await fillFirstVisible([page.locator(testId('network-form-rpc-url')), page.locator('input[name="rpcUrl"]')], network.rpcUrl, SHORT_TIMEOUT_MS);
+            if (!rpcDirect) {
+                const dropdownOpened = await clickFirstVisible([page.locator(testId('test-add-rpc-drop-down')), page.getByText(/Add RPC URL/i)], SHORT_TIMEOUT_MS);
+                if (!dropdownOpened)
+                    throw new Error('Unable to find the MetaMask RPC URL input.');
+                await clickFirstVisible([page.getByRole('button', { name: /Add RPC URL/i })], SHORT_TIMEOUT_MS);
+                const rpcFilled = await fillFirstVisible([page.locator(testId('rpc-url-input-test')), page.locator('input[name="rpcUrl"]')], network.rpcUrl);
+                if (!rpcFilled)
+                    throw new Error('Unable to fill the MetaMask RPC URL field.');
+                const rpcConfirmed = await clickFirstVisible([page.getByRole('button', { name: /^Add URL$/i })], SHORT_TIMEOUT_MS);
+                if (!rpcConfirmed)
+                    throw new Error('Unable to confirm the MetaMask RPC URL.');
+            }
+            const chainFilled = await fillFirstVisible([page.locator(testId('network-form-chain-id')), page.locator('input[name="chainId"]')], String(network.chainId));
+            if (!chainFilled)
+                throw new Error('Unable to fill the MetaMask chain id field.');
+            const symbolFilled = await fillFirstVisible([page.locator(testId('network-form-ticker-input')), page.locator('input[name="symbol"]')], network.symbol);
+            if (!symbolFilled)
+                throw new Error('Unable to fill the MetaMask currency symbol field.');
+            if (network.blockExplorerUrl) {
+                await fillFirstVisible([
+                    page.locator(testId('network-form-block-explorer-url')),
+                    page.locator('input[name="blockExplorerUrl"]'),
+                ], network.blockExplorerUrl, SHORT_TIMEOUT_MS);
+            }
+            const saved = await clickFirstVisible([page.locator(testId('network-form-save')), page.getByRole('button', { name: /^Save$/i })], DEFAULT_TIMEOUT_MS);
+            if (!saved) {
+                throw new Error('Unable to save the MetaMask network. Note that 13.x refuses custom networks under a ' +
+                    'known chain id ("edit the original network") — add those via a dapp ' +
+                    'wallet_addEthereumChain request plus approveNewNetwork() instead.');
+            }
+            await waitForMetaMaskReady(page);
+            await clickMetaMaskPromptAction(page, SHORT_TIMEOUT_MS);
+            await closeMetaMaskOverlay(page);
+        };
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                await addOnce();
+                return;
+            }
+            catch (error) {
+                if (attempt === 2)
+                    throw error;
+                if (!page.isClosed() && !isRecoverablePageNavigationError(error)) {
+                    await page.keyboard.press('Escape').catch(() => undefined);
+                    await closeMetaMaskOverlay(page);
+                }
+                if (!page.isClosed()) {
+                    await page.goto(`${page.url().split('#')[0]}#/`, { waitUntil: 'domcontentloaded' }).catch(() => undefined);
+                    await waitForMetaMaskReady(page);
+                }
+                else {
+                    page = await this.home();
+                }
+                await wait(1_000 + attempt * 1_000);
+            }
+        }
+    }
+    async switchNetwork(name, options = {}) {
+        const page = await this.home();
+        const home = page.url().split('#')[0];
+        const candidates = () => [
+            // 13.x multichain rows are keyed by CAIP-2 chain id.
+            ...(options.chainId !== undefined
+                ? [page.locator(testId(`network-list-item-eip155:${options.chainId}`))]
+                : []),
+            // 12.x rows have historically used the network name as test id.
+            page.locator(testId(name)),
+            page.locator('[data-testid="network-list-item"]').filter({ hasText: name }),
+            page.locator('[data-testid^="network-list-item"]').filter({ hasText: name }),
+            page.locator('.multichain-network-list-item').filter({ hasText: name }),
+            page.getByText(name, { exact: true }),
+        ];
+        // Custom RPC networks live under the 13.x "Custom" tab; try the current
+        // (default) tab first, then the Custom tab. The 13.x list can lag just
+        // after addNetwork(), so retry from a clean home render before failing.
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            if (attempt > 0) {
+                await page.keyboard.press('Escape').catch(() => undefined);
+                await closeMetaMaskOverlay(page);
+                await page.goto(`${home}#/`).catch(() => undefined);
+                await wait(1_000 + attempt * 1_000);
+            }
+            await waitForMetaMaskHome(page);
+            await closeMetaMaskOverlay(page);
+            const pickerOpened = await clickFirstVisible(metaMaskNetworkPickerLocators(page), DEFAULT_TIMEOUT_MS);
+            if (!pickerOpened)
+                continue;
+            let selected = await clickFirstVisible(candidates(), SHORT_TIMEOUT_MS);
+            if (!selected) {
+                if (this.generation === '13x') {
+                    await clickFirstVisible([page.getByRole('tab', { name: /^Custom$/i })], SHORT_TIMEOUT_MS);
+                }
+                selected = await clickFirstVisible(candidates(), DEFAULT_TIMEOUT_MS);
+            }
+            if (selected) {
+                await waitForMetaMaskReady(page);
+                await closeMetaMaskOverlay(page);
+                return;
+            }
+            await page.keyboard.press('Escape').catch(() => undefined);
+            await closeMetaMaskOverlay(page);
+        }
+        throw new Error(`Unable to select MetaMask network "${name}". Add it first with addNetwork(), and check "Show test networks" if it is a testnet.`);
+    }
+    async approveNewNetwork() {
+        const page = await this.notificationPage();
+        await this.confirmFooterAction(page);
+        // MetaMask follows up with a "switch to this network" step.
+        if (!page.isClosed()) {
+            await waitForMetaMaskReady(page);
+            await this.confirmFooterAction(page, SHORT_TIMEOUT_MS).catch(() => undefined);
+        }
+    }
+    async rejectNewNetwork() {
+        const page = await this.notificationPage();
+        await this.rejectFooterAction(page);
+    }
+    async approveSwitchNetwork() {
+        const page = await this.notificationPage();
+        await this.confirmFooterAction(page);
+    }
+    async rejectSwitchNetwork() {
+        const page = await this.notificationPage();
+        await this.rejectFooterAction(page);
     }
     async rejectSignature() {
         const page = await this.notificationPage();
@@ -591,6 +1079,985 @@ class MetaMaskRealWallet {
         const page = await this.notificationPage();
         await this.rejectFooterAction(page);
     }
+    async rejectTokenPermission() {
+        const page = await this.notificationPage();
+        await this.rejectFooterAction(page);
+    }
+    async approveAddToken() {
+        const page = await this.notificationPage();
+        await this.confirmFooterAction(page);
+    }
+    async addNewToken() {
+        await this.approveAddToken();
+    }
+    async rejectAddToken() {
+        const page = await this.notificationPage();
+        await this.rejectFooterAction(page);
+    }
+    async importWalletFromPrivateKey(privateKey) {
+        const methodDeadline = Date.now() + 220_000;
+        const remaining = () => Math.max(methodDeadline - Date.now(), 1);
+        const timeoutFor = (max = DEFAULT_TIMEOUT_MS) => Math.min(max, remaining());
+        const normalized = normalizePrivateKey(privateKey);
+        const page = await this.preparedHome();
+        await this.openAccountPicker(page, Math.min(90_000, remaining()));
+        let importOpened = false;
+        if (this.generation === '12x') {
+            // 12.x: action button → "Import account".
+            if (await clickFirstVisible([page.locator(testId('multichain-account-menu-popover-action-button'))], SHORT_TIMEOUT_MS)) {
+                importOpened = Boolean(await clickFirstVisible([page.locator(testId('multichain-account-menu-popover-add-imported-account'))], SHORT_TIMEOUT_MS));
+            }
+        }
+        else {
+            // 13.x: the add-wallet button sits below the (possibly long) account
+            // list, so scroll it into view first, then pick "Import an account"
+            // (runtime testid choose-wallet-type-import-account). The import page
+            // defaults to the Private key tab, so no further wallet-type choice is
+            // needed. Retry the picker → add-wallet → choose-type hop (it can race
+            // the account-list render under load).
+            for (let attempt = 0; attempt < 3 && !importOpened; attempt += 1) {
+                if (attempt > 0) {
+                    await page.keyboard.press('Escape').catch(() => undefined);
+                    await this.openAccountPicker(page, Math.min(60_000, remaining()));
+                }
+                const addWallet = page.locator(testId('account-list-add-wallet-button')).first();
+                await addWallet.scrollIntoViewIfNeeded({ timeout: timeoutFor(SHORT_TIMEOUT_MS) }).catch(() => undefined);
+                if (await clickFirstVisible([addWallet], timeoutFor())) {
+                    importOpened = Boolean(await clickFirstVisible([
+                        page.locator(testId('choose-wallet-type-import-account')),
+                        page.getByText('Import an account', { exact: true }),
+                    ], timeoutFor()));
+                }
+            }
+        }
+        if (!importOpened) {
+            throw new Error('Unable to open the MetaMask import-account flow — update web3-tester for this MetaMask version.');
+        }
+        const keyFilled = await fillFirstVisible([page.locator('#private-key-box')], normalized, timeoutFor());
+        if (!keyFilled)
+            throw new Error('Unable to find the MetaMask private key input.');
+        const confirmed = await clickFirstVisible([page.locator(testId('import-account-confirm-button'))], timeoutFor());
+        if (!confirmed)
+            throw new Error('Unable to confirm the MetaMask private key import.');
+        // Success closes the dialog (the keyring import can take a moment);
+        // failure keeps it open with inline help text.
+        const dialogClosed = await isHidden(page.locator('#private-key-box'), timeoutFor()).catch(() => false);
+        if (!dialogClosed) {
+            const helpText = (await page.locator('.mm-help-text').first().textContent({ timeout: SHORT_TIMEOUT_MS }).catch(() => null))?.trim();
+            throw new Error(`MetaMask rejected the private key import${helpText ? `: ${helpText}` : '.'}`);
+        }
+        // The imported account becomes active. 13.x leaves the SPA parked on
+        // #/choose-new-wallet-type, so route back to the wallet home or later
+        // home-screen lookups (account-menu-icon, etc.) time out.
+        if (this.generation === '13x') {
+            await page.goto(`${page.url().split('#')[0]}#/`).catch(() => undefined);
+            await waitForMetaMaskReady(page);
+        }
+        this.expectedAddress = undefined;
+        this.trustedSelectedAddress = undefined;
+        await closeMetaMaskOverlay(page);
+    }
+    async addNewAccount(name) {
+        const methodDeadline = Date.now() + 220_000;
+        const remaining = () => Math.max(methodDeadline - Date.now(), 1);
+        let page = await realWalletTiming('addNewAccount.home', () => this.home());
+        if (this.generation === '12x') {
+            await this.openAccountPicker(page, Math.min(90_000, remaining()));
+            // 12.x: action button → Add account → submit. The creation dialog's
+            // optional name field can mark valid custom names as duplicates; create
+            // the derived account first, then rename the newly active account by
+            // address through account details.
+            const actionOpened = await clickFirstVisible([page.locator(testId('multichain-account-menu-popover-action-button'))], SHORT_TIMEOUT_MS);
+            const addOpened = actionOpened &&
+                (await clickFirstVisible([page.locator(testId('multichain-account-menu-popover-add-account'))], SHORT_TIMEOUT_MS));
+            if (!addOpened) {
+                throw new Error('Unable to find the MetaMask add-account control — update web3-tester for this MetaMask version.');
+            }
+            const submitted = await clickFirstVisible([
+                page.locator(testId('submit-add-account-with-name')),
+                page.getByRole('button', { name: /^(Add account|Create)$/i }),
+            ], DEFAULT_TIMEOUT_MS);
+            if (!submitted)
+                throw new Error('Unable to submit the MetaMask add-account dialog.');
+            this.expectedAddress = undefined;
+            this.trustedSelectedAddress = undefined;
+            await closeMetaMaskOverlay(page);
+            if (name) {
+                await this.renameActiveAccountFromDetails(page, name);
+            }
+            return;
+        }
+        // 13.x multichain: the "add account" control is NOT in the account picker
+        // (its only add affordance, account-list-add-wallet-button, opens the
+        // import/hardware "Add a wallet" flow). Adding a derived account lives on
+        // the SRP wallet's details page. The create is a background dispatch that
+        // the account-tree sync silently drops ~1/3 of the time (no toast, the new
+        // account is not auto-selected), so the reliable approach is: settle the
+        // tree, gate on a non-syncing button, click, then wait for the specific
+        // new cell (the wallet's max index + 1) to attach — retrying across fresh
+        // navigations. LavaMoat blocks bulk text reads, so everything is
+        // count()/getAttribute()/testid based.
+        const home = page.url().split('#')[0];
+        await realWalletTiming('addNewAccount.openAccountPicker', () => this.openAccountPicker(page, Math.min(90_000, remaining())));
+        const walletId = await realWalletTiming('addNewAccount.activeSrpWalletId', () => this.activeSrpWalletId(page));
+        await page.keyboard.press('Escape').catch(() => undefined);
+        await realWalletTiming('addNewAccount.initialTreeSettle', () => wait(ACCOUNT_TREE_SETTLE_MS));
+        const walletCellPrefix = `[data-testid^="multichain-account-cell-${walletId}/"]`;
+        const createAttempts = 5;
+        const createDeadline = methodDeadline;
+        let newIndex = -1;
+        for (let attempt = 0; attempt < createAttempts && newIndex < 0 && Date.now() < createDeadline; attempt += 1) {
+            // Between attempts, let the account-tree backup-and-sync (which drops
+            // the create when it overlaps, and retries on its own backoff) calm
+            // before re-navigating — back off a little further each time.
+            if (attempt > 0)
+                await wait(2_000 + attempt * 1_500);
+            const remaining = () => Math.max(createDeadline - Date.now(), 1);
+            try {
+                await realWalletTiming(`addNewAccount.gotoWalletDetails.attempt${attempt + 1}`, async () => {
+                    await page.goto(`${home}#/multichain-wallet-details-page?id=${encodeURIComponent(walletId)}`, {
+                        waitUntil: 'domcontentloaded',
+                    });
+                    await waitForMetaMaskReady(page);
+                });
+                const addButton = page.locator(testId('add-multichain-account-button')).first();
+                const addButtonVisible = await realWalletTiming(`addNewAccount.waitAddButtonVisible.attempt${attempt + 1}`, () => addButton
+                    .waitFor({ state: 'visible', timeout: Math.min(DEFAULT_TIMEOUT_MS, remaining()) })
+                    .then(() => true)
+                    .catch(() => false));
+                if (!addButtonVisible) {
+                    throw new Error('Unable to find the MetaMask add-account control on the wallet details page — update web3-tester for this MetaMask version.');
+                }
+                await realWalletTiming(`addNewAccount.waitAddAccountReady.attempt${attempt + 1}`, () => this.waitForAddAccountReady(addButton, Math.min(DEFAULT_TIMEOUT_MS, remaining())));
+                // The wallet's cells are index-ordered and contiguous; the new account
+                // is one past the current maximum. Read the last cell's id with a single
+                // call (enumerating all cells perturbs timing and flakes detection).
+                const lastTestId = await realWalletTiming(`addNewAccount.readLastIndex.attempt${attempt + 1}`, () => page.locator(walletCellPrefix).last().getAttribute('data-testid').catch(() => null));
+                const maxIndex = Number.parseInt(lastTestId?.split('/').pop() ?? '', 10);
+                if (Number.isNaN(maxIndex)) {
+                    throw new Error('Unable to read the MetaMask wallet account indices to add an account.');
+                }
+                const candidate = maxIndex + 1;
+                const created = await realWalletTiming(`addNewAccount.clickAndWaitCreated.attempt${attempt + 1}`, async () => {
+                    await addButton.click();
+                    return page
+                        .locator(testId(`multichain-account-cell-${walletId}/${candidate}`))
+                        .waitFor({ state: 'attached', timeout: Math.min(15_000, remaining()) })
+                        .then(() => true)
+                        .catch(() => false);
+                });
+                if (created)
+                    newIndex = candidate;
+            }
+            catch (error) {
+                if (!isRecoverablePageNavigationError(error))
+                    throw error;
+                page = await this.home();
+            }
+        }
+        if (newIndex < 0) {
+            throw new Error(`MetaMask did not create a new account after ${createAttempts} attempts (account-tree sync ` +
+                'race) — retry the operation.');
+        }
+        this.expectedAddress = undefined;
+        this.trustedSelectedAddress = undefined;
+        if (name) {
+            // Rename via the account-details route: the new high-index cell's row
+            // menu is unclickable at the foot of a long (un-virtualized) wallet list.
+            await realWalletTiming('addNewAccount.gotoNewAccountDetails', () => page
+                .goto(`${home}#/multichain-account-details?accountGroupId=${encodeURIComponent(`${walletId}/${newIndex}`)}`, { waitUntil: 'domcontentloaded' })
+                .catch(async (error) => {
+                if (!isRecoverablePageNavigationError(error))
+                    throw error;
+                page = await this.home();
+                await page.goto(`${home}#/multichain-account-details?accountGroupId=${encodeURIComponent(`${walletId}/${newIndex}`)}`, { waitUntil: 'domcontentloaded' });
+            }));
+            await realWalletTiming('addNewAccount.waitNewAccountDetailsReady', () => waitForMetaMaskReady(page));
+            const editOpened = await clickFirstVisible([page.locator(testId('account-name-action'))], DEFAULT_TIMEOUT_MS);
+            if (!editOpened)
+                throw new Error('Unable to open the MetaMask account name editor.');
+            await realWalletTiming('addNewAccount.renameNewAccount', () => this.fillAccountNameAndSave(page, name));
+        }
+        await realWalletTiming('addNewAccount.returnHome', async () => {
+            await page.goto(`${home}#/`);
+            await waitForMetaMaskReady(page);
+            await closeMetaMaskOverlay(page);
+        });
+    }
+    // The SRP (entropy) wallet id, parsed from the first multichain account
+    // cell's test id (form: multichain-account-cell-<entropy:UID>/<index>).
+    // Needed to address the wallet details page where account creation lives.
+    async activeSrpWalletId(page) {
+        const testIdAttr = await page
+            .locator('[data-testid^="multichain-account-cell-entropy:"]')
+            .first()
+            .getAttribute('data-testid')
+            .catch(() => null);
+        const match = testIdAttr?.match(/^multichain-account-cell-(entropy:[^/]+)/);
+        if (!match) {
+            throw new Error('Unable to determine the MetaMask SRP wallet id from the account list — update web3-tester for this MetaMask version.');
+        }
+        return match[1];
+    }
+    async switchAccount(nameOrAddress) {
+        const page = await realWalletTiming('switchAccount.home', () => this.home());
+        await realWalletTiming('switchAccount.openAccountPicker', () => this.openAccountPicker(page));
+        if (this.generation === '13x') {
+            const cell = await realWalletTiming('switchAccount.find13xAccountCell', () => this.find13xAccountCell(page, nameOrAddress));
+            if (!cell) {
+                throw new Error(`Unable to find MetaMask account "${nameOrAddress}" in the picker (searched the ` +
+                    'virtualized account list by name/address).');
+            }
+            await realWalletTiming('switchAccount.clickCell', async () => {
+                await cell.click();
+                await waitForMetaMaskReady(page);
+            });
+            this.expectedAddress = FULL_ADDRESS_PATTERN.test(nameOrAddress) ? nameOrAddress : undefined;
+            this.trustedSelectedAddress = this.expectedAddress;
+            await realWalletTiming('switchAccount.closeOverlay', () => closeMetaMaskOverlay(page));
+            return;
+        }
+        const row = accountRowLocator(page).filter({ hasText: accountRowMatcher(nameOrAddress) }).first();
+        const clicked = await clickFirstVisible([row], DEFAULT_TIMEOUT_MS, { requireEnabled: false });
+        if (!clicked) {
+            throw new Error(`Unable to find MetaMask account "${nameOrAddress}" in the picker. On 13.x the rows show ` +
+                'names, so address matching is best-effort — prefer account names.');
+        }
+        await waitForMetaMaskReady(page);
+        this.expectedAddress = FULL_ADDRESS_PATTERN.test(nameOrAddress) ? nameOrAddress : undefined;
+        this.trustedSelectedAddress = undefined;
+        await closeMetaMaskOverlay(page);
+    }
+    async renameAccount(currentName, newName) {
+        const page = await this.preparedHome();
+        await this.openAccountPicker(page);
+        if (this.generation === '13x') {
+            const cell = await this.findAccountCellByName(page, currentName);
+            if (!cell)
+                throw new Error(`Unable to find MetaMask account "${currentName}" to rename.`);
+            await this.rename13xCellViaMenu(page, cell, newName);
+            await page.keyboard.press('Escape').catch(() => undefined);
+            await closeMetaMaskOverlay(page);
+            return;
+        }
+        const row = accountRowLocator(page).filter({ hasText: accountRowMatcher(currentName) }).first();
+        if (!(await isVisible(row, DEFAULT_TIMEOUT_MS).catch(() => false))) {
+            throw new Error(`Unable to find MetaMask account "${currentName}" to rename.`);
+        }
+        await this.renameAccountRow(page, row, newName, currentName);
+        await page.keyboard.press('Escape').catch(() => undefined);
+        await closeMetaMaskOverlay(page);
+    }
+    async lock() {
+        let lastError;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const page = await this.preparedHome();
+            await this.openGlobalMenu(page);
+            const locked = await clickFirstVisible([page.locator(testId('global-menu-lock')), page.getByText(/^Lock( MetaMask)?$/i)], DEFAULT_TIMEOUT_MS, { force: attempt > 0 });
+            if (!locked)
+                throw new Error('Unable to find the MetaMask lock action in the global menu.');
+            const lockScreen = await this.waitForLockedState(page, DEFAULT_TIMEOUT_MS);
+            if (lockScreen)
+                return;
+            lastError = new Error('MetaMask did not show the unlock screen after locking.');
+            await page.keyboard.press('Escape').catch(() => undefined);
+            await wait(1_000 + attempt * 1_000);
+        }
+        throw lastError instanceof Error ? lastError : new Error('MetaMask did not show the unlock screen after locking.');
+    }
+    async unlock(password) {
+        const target = password ?? this.walletPassword;
+        if (!target) {
+            throw new Error('unlock() needs a password — pass one or provide setup.password at launch.');
+        }
+        const page = await openExtensionHome(this.context, this.extensionId);
+        if (!(await isMetaMaskUnlockVisible(page)))
+            return;
+        await unlockMetaMask(page, target);
+    }
+    async waitForUnlocked() {
+        const page = await openExtensionHome(this.context, this.extensionId);
+        await unlockMetaMaskIfNeeded(page, this.walletPassword);
+        await waitForMetaMaskReady(page);
+        if (await isMetaMaskUnlockVisible(page)) {
+            throw new Error('MetaMask did not leave the locked screen.');
+        }
+        await closeMetaMaskOverlay(page);
+    }
+    async resetAccount() {
+        const page = await this.preparedHome();
+        await this.openGlobalMenu(page);
+        const settingsOpened = await clickFirstVisible([page.locator(testId('global-menu-settings')), page.getByText(/^Settings$/i)], DEFAULT_TIMEOUT_MS);
+        if (!settingsOpened)
+            throw new Error('Unable to open MetaMask settings.');
+        await waitForMetaMaskReady(page);
+        if (this.generation === '12x') {
+            // 12.x: "Clear activity tab data" lives on the Advanced tab (or is
+            // already visible when settings opens straight onto it).
+            if (await clickFirstVisible([page.locator(testId('advanced-setting-reset-account')).getByRole('button')], SHORT_TIMEOUT_MS)) {
+                await this.confirmResetModal(page);
+                await this.leaveSettings(page);
+                return;
+            }
+            if (await clickFirstVisible([
+                page.getByRole('tab', { name: /^Advanced$/i }),
+                page.locator('.tab-bar__tab').filter({ hasText: /^Advanced$/ }),
+            ], SHORT_TIMEOUT_MS)) {
+                if (await clickFirstVisible([
+                    page.locator(testId('advanced-setting-reset-account')).getByRole('button'),
+                    page.getByRole('button', { name: /Clear activity( tab)? data/i }),
+                ], SHORT_TIMEOUT_MS)) {
+                    await this.confirmResetModal(page);
+                    await this.leaveSettings(page);
+                    return;
+                }
+            }
+        }
+        else {
+            // 13.x: Settings -> Developer tools -> "Delete activity and nonce data".
+            // Route directly because the grouped settings sidebar can be slow to
+            // render/click under long smoke-suite load.
+            const home = page.url().split('#')[0];
+            const openedDeveloperTools = (await this.open13xSettingsRoute(page, home, '/settings/developer-tools')) ||
+                (await clickFirstVisible([
+                    page.locator(testId('settings-tab-item-developer-tools')),
+                    page.getByText(/^Developer tools$/i),
+                ], SHORT_TIMEOUT_MS, { requireEnabled: false }));
+            if (openedDeveloperTools && (await this.clickResetAccountControl(page, DEFAULT_TIMEOUT_MS))) {
+                await this.confirmResetModal(page);
+                await this.leaveSettings(page);
+                return;
+            }
+        }
+        // Fallback: the settings search (the Developer tools tab can be
+        // feature-flag hidden in production profiles).
+        if (await clickFirstVisible([page.locator(testId('settings-header-search-button'))], SHORT_TIMEOUT_MS)) {
+            await fillFirstVisible([page.locator(testId('settings-header-search-input')), page.locator('input[type="search"]')], this.generation === '13x' ? 'Delete activity' : 'Clear activity', SHORT_TIMEOUT_MS);
+            if (await clickFirstVisible([page.locator(testId('settings-search-result-item')).first()], SHORT_TIMEOUT_MS)) {
+                const cleared = await clickFirstVisible(metaMaskResetAccountControlLocators(page), DEFAULT_TIMEOUT_MS);
+                if (cleared) {
+                    await this.confirmResetModal(page);
+                    await this.leaveSettings(page);
+                    return;
+                }
+            }
+        }
+        throw new Error('Unable to find the MetaMask reset-account control (Clear activity / Delete activity and ' +
+            'nonce data) — update web3-tester for this MetaMask version.');
+    }
+    async toggleShowTestNetworks(on) {
+        let page = await this.preparedHome();
+        if (this.generation === '13x') {
+            // 13.x hosts the toggle on the standalone #/networks page (the network
+            // picker popover only renders it once non-default testnets already
+            // exist). It is a hidden <input type=checkbox> under a styled overlay.
+            // react-toggle-button binds its `value` attribute (not the `checked`
+            // property), so Playwright's check()/uncheck() — which assert the
+            // never-updated `checked` — throw "did not change its state"; instead
+            // force-click and confirm the `value` attribute flipped.
+            // The first navigation to #/networks can race the React render; renavigate
+            // until the toggle attaches.
+            let toggleReady = false;
+            let toggle = page.locator(testId('networks-page-show-test-networks')).first();
+            for (let attempt = 0; attempt < 5 && !toggleReady; attempt += 1) {
+                try {
+                    const home = page.url().split('#')[0];
+                    await page.goto(`${home}#/networks`);
+                    // Reaching #/networks as a hash-only change from the home route leaves
+                    // the toggle rendered but non-interactive (its click never fires);
+                    // force a full document load so its handlers bind.
+                    await page.reload().catch(() => undefined);
+                    await waitForMetaMaskReady(page);
+                    toggle = page.locator(testId('networks-page-show-test-networks')).first();
+                    toggleReady = await toggle
+                        .waitFor({ state: 'attached', timeout: 10_000 })
+                        .then(() => true)
+                        .catch(() => false);
+                }
+                catch (error) {
+                    if (!isRecoverablePageNavigationError(error) || attempt === 4)
+                        throw error;
+                    page = await this.home();
+                    toggle = page.locator(testId('networks-page-show-test-networks')).first();
+                }
+            }
+            if (!toggleReady) {
+                throw new Error('Unable to find the MetaMask "Show test networks" toggle on the networks page.');
+            }
+            // The testid sits on a hidden 1×1 screen-reader <input> bound by `value`
+            // (not `checked`); force-clicking that tiny input is unreliable. Click the
+            // wrapping label.toggle-button instead — the visible, hit-testable control
+            // — and confirm the input's `value` attribute flipped (give the
+            // controlled re-render a beat so a re-click can't flip it back).
+            const toggleLabel = toggle.locator('xpath=ancestor-or-self::label[contains(@class,"toggle-button")][1]');
+            const readOn = async () => (await toggle.getAttribute('value').catch(() => null)) === 'true';
+            const target = on ?? !(await readOn());
+            for (let attempt = 0; attempt < 5 && (await readOn()) !== target; attempt += 1) {
+                await toggleLabel.click({ force: true }).catch(() => undefined);
+                await wait(1_000);
+            }
+            if ((await readOn()) !== target) {
+                throw new Error('Unable to flip the MetaMask "Show test networks" toggle on the networks page.');
+            }
+            await waitForMetaMaskReady(page);
+            await page.goto(page.url().split('#')[0]).catch(() => undefined);
+            await waitForMetaMaskReady(page);
+            await closeMetaMaskOverlay(page);
+            return;
+        }
+        const pickerOpened = await clickFirstVisible(metaMaskNetworkPickerLocators(page), DEFAULT_TIMEOUT_MS);
+        if (!pickerOpened)
+            throw new Error('Unable to open the MetaMask network picker.');
+        await waitForMetaMaskReady(page);
+        // react-toggle-button renders the data-testid onto a 1×1 screen-reader
+        // <input>; clicking that fails Playwright's hit-target check. Click the
+        // wrapping label.toggle-button (the hit-testable track) instead.
+        const toggle = await findVisibleLocator([
+            page
+                .getByText(/Show test networks/i)
+                .locator('xpath=following::label[contains(@class,"toggle-button")][1]'),
+            page.locator('label.toggle-button').first(),
+        ], DEFAULT_TIMEOUT_MS, { requireEnabled: false });
+        if (!toggle) {
+            throw new Error('Unable to find the MetaMask "Show test networks" toggle.');
+        }
+        if (on === undefined) {
+            await toggle.click();
+        }
+        else {
+            const current = await this.readToggleState(toggle);
+            if (current !== on) {
+                await toggle.click();
+            }
+        }
+        await waitForMetaMaskReady(page);
+        await page.keyboard.press('Escape').catch(() => undefined);
+        await closeMetaMaskOverlay(page);
+    }
+    async importToken(token) {
+        if (!FULL_ADDRESS_PATTERN.test(token.address)) {
+            throw new Error('importToken requires a 20-byte 0x token address.');
+        }
+        const page = await this.preparedHome();
+        // The token list (and its control bar) lives on the Tokens tab.
+        await clickFirstVisible([
+            page.locator(testId('account-overview__asset-tab')),
+            page.getByRole('button', { name: /^Tokens$/i }),
+        ], SHORT_TIMEOUT_MS);
+        const menuOpened = await clickFirstVisible([page.locator(testId('asset-list-control-bar-action-button'))], DEFAULT_TIMEOUT_MS);
+        if (!menuOpened)
+            throw new Error('Unable to open the MetaMask token list menu.');
+        if (this.generation === '13x') {
+            await this.importTokenViaTokenManagement(page, token);
+        }
+        else {
+            await this.importTokenViaModal(page, token);
+        }
+        await closeMetaMaskOverlay(page);
+    }
+    // 13.x: control-bar menu → "Manage tokens" → token-management page → "Add a
+    // custom token" → the custom-token-import page (address, then auto-loaded
+    // symbol/decimals, then "Add token"). Replaces the 12.x import-tokens modal.
+    async importTokenViaTokenManagement(page, token) {
+        const manageOpened = await clickFirstVisible([page.locator(testId('manageTokens')), page.getByRole('button', { name: /^Manage tokens$/i })], DEFAULT_TIMEOUT_MS);
+        if (!manageOpened)
+            throw new Error('Unable to open the MetaMask "Manage tokens" page.');
+        const addCustomOpened = await clickFirstVisible([
+            page.locator(testId('token-management-add-custom-token-button')),
+            page.getByRole('button', { name: /Add a custom token/i }),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!addCustomOpened)
+            throw new Error('Unable to open the MetaMask custom-token import form.');
+        if (token.networkName) {
+            const selectorOpened = await clickFirstVisible([page.locator(testId('network-selector')), page.getByRole('button', { name: /^Network$/i })], SHORT_TIMEOUT_MS);
+            if (selectorOpened) {
+                const picked = await clickFirstVisible([page.getByText(token.networkName, { exact: true })], DEFAULT_TIMEOUT_MS);
+                if (!picked) {
+                    throw new Error(`Unable to select network "${token.networkName}" in the token import page.`);
+                }
+            }
+        }
+        const addressFilled = await fillFirstVisible([page.locator(testId('custom-token-import-address-input'))], token.address);
+        if (!addressFilled)
+            throw new Error('Unable to fill the token contract address.');
+        // MetaMask auto-loads symbol/decimals from the contract and enables "Add
+        // token". Only fill the fields if they stay EMPTY (the RPC read failed) —
+        // re-filling an auto-populated field on every tick re-triggers validation
+        // and keeps the submit button from ever settling enabled.
+        const submit = page.locator(testId('custom-token-import-submit-button')).first();
+        const deadline = Date.now() + DEFAULT_TIMEOUT_MS;
+        while (Date.now() < deadline && !(await submit.isEnabled().catch(() => false))) {
+            if (token.symbol) {
+                await this.fillIfEmpty(page.locator(testId('custom-token-import-symbol-input')).first(), token.symbol);
+            }
+            if (token.decimals !== undefined) {
+                await this.fillIfEmpty(page.locator(testId('custom-token-import-decimal-input')).first(), String(token.decimals));
+            }
+            await wait(LOCATOR_PROBE_MS);
+        }
+        const added = await clickFirstVisible([submit, page.getByRole('button', { name: /^Add token$/i })], DEFAULT_TIMEOUT_MS);
+        if (!added) {
+            throw new Error('MetaMask never enabled the custom-token "Add token" button — check the token address, ' +
+                'network, and (for contracts the RPC cannot read) pass symbol/decimals explicitly.');
+        }
+        // The import is confirmed by the success toast (and the form unmounting);
+        // a regression that dismisses the form without importing fails here.
+        const confirmed = await findVisibleLocator([
+            page.locator(testId('token-management-custom-token-success-toast')),
+            page.getByText(/was successfully added/i),
+        ], DEFAULT_TIMEOUT_MS, { requireEnabled: false });
+        if (!confirmed) {
+            await isHidden(page.locator(testId('custom-token-import-address-input')), DEFAULT_TIMEOUT_MS).catch(() => undefined);
+        }
+    }
+    // Fills a metadata field only when it is currently empty, so an
+    // auto-populated value (MetaMask reading the contract) is left intact. A
+    // tight loop that unconditionally re-fills an auto-filled field re-triggers
+    // validation and prevents the submit/Next button from settling enabled.
+    async fillIfEmpty(field, value) {
+        const current = await field.inputValue({ timeout: LOCATOR_PROBE_MS }).catch(() => null);
+        if (current === '')
+            await field.fill(value).catch(() => undefined);
+    }
+    // 12.x: control-bar menu → "Import tokens" → Custom token tab → modal form.
+    async importTokenViaModal(page, token) {
+        const importClicked = await clickFirstVisible([page.locator(testId('importTokens')), page.getByText(/^Import tokens$/i)], DEFAULT_TIMEOUT_MS);
+        if (!importClicked)
+            throw new Error('Unable to open the MetaMask Import tokens dialog.');
+        await clickFirstVisible([
+            page.locator(testId('import-tokens-modal-custom-token-tab')),
+            page.getByRole('tab', { name: /Custom token/i }),
+            page.getByText('Custom token', { exact: true }),
+        ], SHORT_TIMEOUT_MS);
+        if (token.networkName) {
+            const dropdownOpened = await clickFirstVisible([
+                page.locator(testId('import-tokens-drop-down-custom-import')),
+                page.locator(testId('test-import-tokens-drop-down-custom-import')),
+            ], SHORT_TIMEOUT_MS);
+            if (dropdownOpened) {
+                const picked = await clickFirstVisible([page.getByText(token.networkName, { exact: true })], DEFAULT_TIMEOUT_MS);
+                if (!picked) {
+                    throw new Error(`Unable to select network "${token.networkName}" in the token import dialog.`);
+                }
+            }
+        }
+        const addressFilled = await fillFirstVisible([page.locator(testId('import-tokens-modal-custom-address'))], token.address);
+        if (!addressFilled)
+            throw new Error('Unable to fill the token contract address.');
+        // MetaMask auto-loads symbol/decimals from the contract and enables Next.
+        // Only fill the fields if they stay EMPTY (the RPC read failed) — re-filling
+        // an auto-populated field on every tick re-triggers validation and keeps
+        // Next from ever settling enabled (observed on 12.23.1).
+        const nextButton = page.locator(testId('import-tokens-button-next')).first();
+        const deadline = Date.now() + DEFAULT_TIMEOUT_MS;
+        while (Date.now() < deadline && !(await nextButton.isEnabled().catch(() => false))) {
+            if (token.symbol) {
+                await this.fillIfEmpty(page.locator(testId('import-tokens-modal-custom-symbol')).first(), token.symbol);
+            }
+            if (token.decimals !== undefined) {
+                await this.fillIfEmpty(page.locator(testId('import-tokens-modal-custom-decimals')).first(), String(token.decimals));
+            }
+            await wait(LOCATOR_PROBE_MS);
+        }
+        const next = await clickFirstVisible([nextButton], SHORT_TIMEOUT_MS);
+        if (!next) {
+            throw new Error('MetaMask never enabled the Import Tokens "Next" button — check the token address, ' +
+                'network, and (for contracts the RPC cannot read) pass symbol/decimals explicitly.');
+        }
+        const imported = await clickFirstVisible([
+            page.locator(testId('import-tokens-modal-import-button')),
+            page.getByRole('button', { name: /^Import( tokens)?$/i }),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!imported)
+            throw new Error('Unable to confirm the MetaMask token import.');
+        await isHidden(page.locator(testId('import-tokens-modal-custom-address')), DEFAULT_TIMEOUT_MS).catch(() => undefined);
+    }
+    async confirmTransactionAndWaitForMining(options = {}) {
+        await realWalletTiming('confirmTransactionAndWaitForMining.confirmTransaction', () => this.confirmTransaction({ gasSetting: options.gasSetting }));
+        const timeoutMs = options.timeoutMs ?? 60_000;
+        const page = await realWalletTiming('confirmTransactionAndWaitForMining.preparedHome', () => this.preparedHome());
+        const activityOpened = await realWalletTiming('confirmTransactionAndWaitForMining.openActivity', () => clickFirstVisible([
+            page.locator(testId('account-overview__activity-tab')),
+            page.getByRole('button', { name: /^Activity$/i }),
+        ], DEFAULT_TIMEOUT_MS));
+        if (!activityOpened)
+            throw new Error('Unable to open the MetaMask activity tab.');
+        const row = page
+            .locator('[data-testid="transaction-list-item"], [data-testid="activity-list-item"], .transaction-list-item, .activity-list-item')
+            .first();
+        const statusVisible = (status) => isVisible(page.locator(testId(`transaction-status-label--${status}`)).first(), LOCATOR_PROBE_MS).catch(() => false);
+        const deadline = Date.now() + timeoutMs;
+        let confirmed = false;
+        await realWalletTiming('confirmTransactionAndWaitForMining.waitActivityConfirmed', async () => {
+            while (Date.now() < deadline) {
+                if ((await statusVisible('failed')) || (await statusVisible('dropped'))) {
+                    throw new Error('The newest MetaMask activity entry failed or was dropped.');
+                }
+                if (await statusVisible('confirmed')) {
+                    confirmed = true;
+                    break;
+                }
+                // Instant-mining nodes may never render a pending state: a visible row
+                // with no pending/queued label counts as confirmed.
+                if ((await isVisible(row, LOCATOR_PROBE_MS).catch(() => false)) &&
+                    !(await statusVisible('pending')) &&
+                    !(await statusVisible('queued'))) {
+                    confirmed = true;
+                    break;
+                }
+                await wait(LOCATOR_PROBE_MS);
+            }
+        });
+        if (!confirmed) {
+            throw new Error(`Timed out after ${timeoutMs}ms waiting for the transaction to confirm in the activity tab.`);
+        }
+        // Best-effort hash read — never throws; the mining wait already passed.
+        let txHash;
+        try {
+            await realWalletTiming('confirmTransactionAndWaitForMining.readTxHash', async () => {
+                if (await clickFirstVisible([row], SHORT_TIMEOUT_MS, { requireEnabled: false })) {
+                    await waitForMetaMaskReady(page);
+                    const copied = await clickFirstVisible([
+                        page.getByRole('button', { name: /Copy transaction ID/i }),
+                        page.getByText(/Copy transaction ID/i),
+                    ], SHORT_TIMEOUT_MS, { requireEnabled: false });
+                    if (copied) {
+                        const pasted = await this.readClipboardViaPaste();
+                        if (isFullTxHash(pasted))
+                            txHash = pasted;
+                    }
+                    await closeMetaMaskOverlay(page);
+                    await page.keyboard.press('Escape').catch(() => undefined);
+                }
+            });
+        }
+        catch {
+            // txHash stays undefined.
+        }
+        return { txHash };
+    }
+    // ── shared private helpers for the account/settings surface ─────────────
+    async waitForLockedState(page, timeout = DEFAULT_TIMEOUT_MS) {
+        const startedAt = Date.now();
+        const deadline = startedAt + timeout;
+        let openedHome = false;
+        while (Date.now() < deadline) {
+            if (!page.isClosed() && (await isMetaMaskUnlockVisible(page)))
+                return page;
+            const lockedPage = await findMetaMaskLockedPage(this.context, this.extensionId);
+            if (lockedPage)
+                return lockedPage;
+            if (!openedHome && Date.now() - startedAt >= 1_500) {
+                openedHome = true;
+                const homePage = await openExtensionHome(this.context, this.extensionId).catch(() => undefined);
+                if (homePage && (await isMetaMaskUnlockVisible(homePage)))
+                    return homePage;
+            }
+            await wait(Math.min(LOCATOR_PROBE_MS, Math.max(deadline - Date.now(), 0)));
+        }
+        return undefined;
+    }
+    async open13xSettingsRoute(page, home, route) {
+        await page.goto(`${home}#${route}`);
+        await waitForMetaMaskReady(page);
+        return Boolean(await findVisibleLocator([
+            page.locator(testId('settings-tab-bar-grouped')),
+            page.getByText(/^Developer tools$/i),
+            page.locator(testId('developer-options-delete-activity-and-nonce-data')),
+        ], DEFAULT_TIMEOUT_MS, { requireEnabled: false }));
+    }
+    async open13xNetworkFormRoute(page, home) {
+        const form = page.locator(testId('network-form-network-name')).first();
+        for (const route of ['#/networks/form', '#/networks/add-network']) {
+            await page.goto(`${home}${route}`);
+            await waitForMetaMaskReady(page);
+            if (await isVisible(form, SHORT_TIMEOUT_MS).catch(() => false))
+                return true;
+            await clickFirstVisible([
+                page.locator(testId('add-network-manually')),
+                page.locator(testId('network-list-menu-add-button')),
+                page.getByRole('button', { name: /Add a custom network|Add custom network|Add a network manually/i }),
+                page.getByText(/Add a custom network|Add a network manually/i),
+            ], SHORT_TIMEOUT_MS);
+            await waitForMetaMaskReady(page);
+            if (await isVisible(form, SHORT_TIMEOUT_MS).catch(() => false))
+                return true;
+        }
+        return false;
+    }
+    async clickResetAccountControl(page, timeout = DEFAULT_TIMEOUT_MS) {
+        const clicked = await clickFirstVisible(metaMaskResetAccountControlLocators(page), timeout);
+        if (!clicked)
+            return false;
+        await waitForMetaMaskReady(page);
+        return true;
+    }
+    async preparedHome() {
+        const page = await this.home();
+        await waitForMetaMaskHome(page);
+        await closeMetaMaskOverlay(page);
+        return page;
+    }
+    async openAccountPicker(page, timeout = 90_000) {
+        // 13.x exposes the account list as a route. Prefer it over the header click
+        // because the header can disappear briefly during account-tree refreshes.
+        // Older UIs still use the popover trigger.
+        const deadline = Date.now() + timeout;
+        const remaining = (max = DEFAULT_TIMEOUT_MS) => Math.max(Math.min(max, deadline - Date.now()), 1);
+        const home = page.url().split('#')[0];
+        for (let attempt = 0; attempt < 5 && Date.now() < deadline; attempt += 1) {
+            await realWalletTiming('openAccountPicker.escape', () => page.keyboard.press('Escape').catch(() => undefined));
+            await realWalletTiming('openAccountPicker.closeOverlay', () => closeMetaMaskOverlay(page));
+            if (this.generation === '13x') {
+                await realWalletTiming('openAccountPicker.gotoAccountList', async () => {
+                    await page.goto(`${home}#/account-list`);
+                    await waitForMetaMaskReady(page);
+                });
+                if (await realWalletTiming('openAccountPicker.findContent', () => findVisibleLocator(accountPickerContentLocators(page), remaining(), {
+                    requireEnabled: false,
+                }))) {
+                    await realWalletTiming('openAccountPicker.settleAccountList', () => this.settleAccountList(page));
+                    return;
+                }
+            }
+            await realWalletTiming('openAccountPicker.gotoHome', async () => {
+                await page.goto(`${home}#/`);
+                await waitForMetaMaskHome(page, remaining());
+            });
+            await realWalletTiming('openAccountPicker.closeOverlayAfterHome', () => closeMetaMaskOverlay(page));
+            const clicked = await realWalletTiming('openAccountPicker.clickTrigger', () => clickFirstVisible(metaMaskAccountPickerTriggerLocators(page), remaining(), {
+                requireEnabled: false,
+            }));
+            if (!clicked)
+                continue;
+            if (await realWalletTiming('openAccountPicker.findPopoverContent', () => findVisibleLocator(accountPickerContentLocators(page), remaining(SHORT_TIMEOUT_MS), {
+                requireEnabled: false,
+            }))) {
+                await realWalletTiming('openAccountPicker.settlePopoverAccountList', () => this.settleAccountList(page));
+                return;
+            }
+        }
+        throw new Error('Unable to open the MetaMask account picker.');
+    }
+    // Let the (virtualized) account list settle: wait for the first row, then
+    // for the row count to stop growing across two probe ticks.
+    async settleAccountList(page) {
+        await waitForMetaMaskReady(page);
+        await isVisible(accountRowLocator(page).first(), DEFAULT_TIMEOUT_MS).catch(() => undefined);
+        const rows = accountRowLocator(page);
+        const deadline = Date.now() + SHORT_TIMEOUT_MS;
+        let lastCount = -1;
+        while (Date.now() < deadline) {
+            const count = await rows.count().catch(() => lastCount);
+            if (count === lastCount)
+                break;
+            lastCount = count;
+            await wait(LOCATOR_PROBE_MS);
+        }
+    }
+    // ── 13.x virtualized-picker account helpers ─────────────────────────────
+    // The 13.x picker renders only a small window of a (potentially huge)
+    // account tree, so name/address lookups must narrow it via the search box
+    // first. Entropy (SRP-derived) and keyring (imported) accounts both render
+    // as multichain-account-cell-<groupId> cells.
+    accountGroupCells(page) {
+        return page.locator('[data-testid^="multichain-account-cell-entropy:"], [data-testid^="multichain-account-cell-keyring:"]');
+    }
+    // Fill the picker search box to narrow the list to `term`. The testid is on
+    // a wrapper; the editable input is nested. No-op (returns false) when absent.
+    async searchAccountPicker(page, term) {
+        return realWalletTiming('searchAccountPicker', async () => {
+            const input = page.locator(`${testId('multichain-account-list-search')} input`).first();
+            if (!(await isVisible(input, SHORT_TIMEOUT_MS).catch(() => false)))
+                return false;
+            await input.fill('');
+            await input.fill(term);
+            return true;
+        });
+    }
+    // The account cell whose display name (its first <p>) exactly equals `name`,
+    // after narrowing by search. Search is a contains filter, so the exact
+    // match is enforced client-side (cell.textContent concatenates
+    // name+address+balance, so an anchored full-text regex cannot be used).
+    async findAccountCellByName(page, name) {
+        await this.searchAccountPicker(page, name);
+        const cells = this.accountGroupCells(page);
+        const deadline = Date.now() + 1_500;
+        do {
+            const count = await cells.count();
+            for (let index = 0; index < count; index += 1) {
+                const cell = cells.nth(index);
+                const cellName = (await cell.locator('p').first().textContent({ timeout: LOCATOR_PROBE_MS }).catch(() => null))?.trim();
+                if (cellName === name)
+                    return cell;
+            }
+            await wait(LOCATOR_PROBE_MS);
+        } while (Date.now() < deadline);
+        return undefined;
+    }
+    // Resolves a 13.x account cell by exact display name, or — for an address —
+    // the derivable imported-keyring cell, else any cell whose text carries the
+    // (full or shortened) address.
+    async find13xAccountCell(page, nameOrAddress) {
+        if (!FULL_ADDRESS_PATTERN.test(nameOrAddress)) {
+            return this.findAccountCellByName(page, nameOrAddress);
+        }
+        const addressLc = nameOrAddress.toLowerCase();
+        await this.searchAccountPicker(page, nameOrAddress);
+        // Imported (private-key) accounts have a fully derivable cell testid.
+        const imported = page
+            .locator(testId(`multichain-account-cell-keyring:Simple Key Pair/${addressLc}`))
+            .first();
+        if (await isVisible(imported, SHORT_TIMEOUT_MS).catch(() => false))
+            return imported;
+        const short = shortAddress(nameOrAddress);
+        const cells = this.accountGroupCells(page);
+        const deadline = Date.now() + 1_500;
+        do {
+            const count = await cells.count();
+            for (let index = 0; index < count; index += 1) {
+                const cell = cells.nth(index);
+                const text = ((await cell.textContent({ timeout: LOCATOR_PROBE_MS }).catch(() => '')) ?? '')
+                    .replace(/\s+/g, '')
+                    .toLowerCase();
+                if (text.includes(addressLc) || text.includes(short))
+                    return cell;
+            }
+            await wait(LOCATOR_PROBE_MS);
+        } while (Date.now() < deadline);
+        return undefined;
+    }
+    // 13.x rename via a surfaced (searched/visible) account cell's row menu.
+    async rename13xCellViaMenu(page, cell, newName) {
+        await cell.hover().catch(() => undefined);
+        await wait(LOCATOR_PROBE_MS);
+        const accessoryOpened = await clickFirstVisible([cell.locator(testId('multichain-account-cell-end-accessory'))], SHORT_TIMEOUT_MS);
+        const renameClicked = accessoryOpened &&
+            (await clickFirstVisible([
+                page.locator(testId('multichain-account-menu-item-rename')),
+                page.getByRole('menuitem', { name: /^Rename$/i }),
+            ], SHORT_TIMEOUT_MS));
+        if (!renameClicked) {
+            throw new Error('Unable to open the MetaMask rename dialog from the account row menu.');
+        }
+        await this.fillAccountNameAndSave(page, newName);
+    }
+    // Polls the wallet-details "Add account" button until it reads exactly
+    // "Add account" (not "Syncing…"/"Adding account…") for two consecutive
+    // reads — only then is the create dispatch not silently dropped.
+    async waitForAddAccountReady(addButton, timeout = DEFAULT_TIMEOUT_MS) {
+        const deadline = Date.now() + timeout;
+        let stable = 0;
+        while (Date.now() < deadline) {
+            const label = (await addButton.textContent({ timeout: LOCATOR_PROBE_MS }).catch(() => ''))?.trim();
+            if (label === 'Add account') {
+                stable += 1;
+                if (stable >= 2) {
+                    await wait(LOCATOR_PROBE_MS);
+                    return;
+                }
+            }
+            else {
+                stable = 0;
+            }
+            await wait(LOCATOR_PROBE_MS);
+        }
+    }
+    async openGlobalMenu(page) {
+        const opened = await clickFirstVisible([page.locator(testId('account-options-menu-button'))], DEFAULT_TIMEOUT_MS);
+        if (!opened)
+            throw new Error('Unable to open the MetaMask global menu.');
+    }
+    // 12.x rename: row options menu → Account details → editable label. (13.x
+    // renames through rename13xCellViaMenu / the account-details route.)
+    async renameActiveAccountFromDetails(page, newName) {
+        await waitForMetaMaskHome(page);
+        await closeMetaMaskOverlay(page);
+        await this.openAccountDetailsModal(page, DEFAULT_TIMEOUT_MS);
+        const editOpened = await clickFirstVisible([page.locator(testId('editable-label-button')), page.locator(testId('account-name-action'))], DEFAULT_TIMEOUT_MS);
+        if (!editOpened)
+            throw new Error('Unable to open the MetaMask account name editor.');
+        await this.fillAccountNameAndSave(page, newName);
+        await page.keyboard.press('Escape').catch(() => undefined);
+        await closeMetaMaskOverlay(page);
+    }
+    async renameAccountRow(page, row, newName, label) {
+        const menuOpened = await clickFirstVisible([
+            row.locator(testId('account-list-item-menu-button')),
+            ...(label ? [page.getByRole('button', { name: `${label} Options` })] : []),
+        ], SHORT_TIMEOUT_MS);
+        if (!menuOpened) {
+            throw new Error('Unable to open the MetaMask account row menu to rename.');
+        }
+        const detailsOpened = await clickFirstVisible([page.locator(testId('account-list-menu-details'))], DEFAULT_TIMEOUT_MS);
+        if (!detailsOpened)
+            throw new Error('Unable to open the MetaMask account details to rename.');
+        const editOpened = await clickFirstVisible([page.locator(testId('editable-label-button'))], DEFAULT_TIMEOUT_MS);
+        if (!editOpened)
+            throw new Error('Unable to open the MetaMask account name editor.');
+        await this.fillAccountNameAndSave(page, newName);
+        await closeMetaMaskOverlay(page);
+    }
+    async fillAccountNameAndSave(page, newName) {
+        const filled = await fillFirstVisibleStableValue([
+            page.locator(`${testId('account-name-input')} input`),
+            page.locator(testId('account-name-input')),
+            page.locator(`${testId('editable-input')} input`),
+            page.locator(testId('editable-input')),
+        ], newName, DEFAULT_TIMEOUT_MS);
+        if (!filled)
+            throw new Error('Unable to fill the MetaMask account name input.');
+        const saved = await clickFirstVisible([
+            page.locator(testId('save-account-label-input')),
+            page.locator('.mm-button-base[aria-label="Confirm"]'),
+            page.getByRole('button', { name: /^(Confirm|Save)$/i }),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!saved)
+            throw new Error('Unable to save the MetaMask account name.');
+        await waitForMetaMaskReady(page);
+    }
+    async confirmResetModal(page) {
+        // 12.x labels the confirm "Clear"; 13.x labels it "Delete".
+        const confirmed = await clickFirstVisible([
+            page.locator(testId('delete-activity-and-nonce-data-button')),
+            page.getByRole('button', { name: /^(Clear|Delete)$/i }),
+            page.locator('.modal button.btn-danger-primary'),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!confirmed)
+            throw new Error('Unable to confirm the MetaMask reset-account dialog.');
+        await waitForMetaMaskReady(page);
+    }
+    async leaveSettings(page) {
+        await clickFirstVisible([page.locator(testId('settings-back-button')), page.locator('.settings-page__close-button')], SHORT_TIMEOUT_MS);
+        await page.goto(extensionUrl(this.extensionId)).catch(() => undefined);
+        await waitForMetaMaskReady(page);
+        await closeMetaMaskOverlay(page);
+    }
+    async readToggleState(toggle) {
+        // react-toggle-button's state lives in the label's toggle-button--on/off
+        // class. Its inner <input type=checkbox> is bound by `value`, NOT
+        // `checked` (and is never clicked directly), so isChecked() always reads
+        // false — read the class first. `toggle` is the label.toggle-button.
+        const ownClass = (await toggle.getAttribute('class').catch(() => null)) ?? '';
+        const labelClass = /toggle-button--(on|off)/.test(ownClass)
+            ? ownClass
+            : (await toggle
+                .locator('xpath=ancestor-or-self::label[contains(@class,"toggle-button")][1]')
+                .getAttribute('class')
+                .catch(() => null)) ?? ownClass;
+        if (/toggle-button--on/.test(labelClass))
+            return true;
+        if (/toggle-button--off/.test(labelClass))
+            return false;
+        const ariaChecked = await toggle.getAttribute('aria-checked').catch(() => null);
+        if (ariaChecked === 'true' || ariaChecked === 'false')
+            return ariaChecked === 'true';
+        const checkbox = toggle.locator('input[type="checkbox"]').first();
+        const checked = await checkbox.isChecked({ timeout: LOCATOR_PROBE_MS }).catch(() => undefined);
+        if (checked !== undefined)
+            return checked;
+        return undefined;
+    }
     async home() {
         const page = await openExtensionHome(this.context, this.extensionId);
         await unlockMetaMaskIfNeeded(page, this.walletPassword);
@@ -627,6 +2094,7 @@ class MetaMaskRealWallet {
         ], timeout);
         if (!confirmed)
             throw new Error('Unable to confirm MetaMask notification.');
+        return confirmed;
     }
     async rejectFooterAction(page, extraLocators = []) {
         const rejected = await clickFirstVisible([
@@ -642,16 +2110,38 @@ class MetaMaskRealWallet {
     async selectAccounts(page, accounts) {
         if (!accounts?.length)
             return;
-        const rows = page.locator('.choose-account-list .choose-account-list__account');
+        // Newer MetaMask shows the currently selected account with an "Edit
+        // accounts" affordance; expand it so the full list renders.
+        await clickFirstVisible([
+            page.locator(testId('edit-accounts')),
+            page.getByRole('button', { name: /Edit accounts?/i }),
+        ], SHORT_TIMEOUT_MS);
+        const rowLocators = [
+            page.locator('.choose-account-list .choose-account-list__account'),
+            page.locator(testId('choose-account-list')).locator('[role="listitem"], li'),
+            page.locator('.multichain-account-list-item'),
+            page.locator('[data-testid="account-list-item"]'),
+        ];
+        let rows;
+        for (const candidate of rowLocators) {
+            if ((await candidate.count()) > 0) {
+                rows = candidate;
+                break;
+            }
+        }
+        if (!rows) {
+            throw new Error(`Unable to locate the MetaMask account list in the connect prompt to select: ${accounts.join(', ')}. ` +
+                'Connect without the accounts argument to use the default account, or update web3-tester for this MetaMask version.');
+        }
         const rowCount = await rows.count();
-        if (!rowCount)
-            return;
         const expected = accounts.map((account) => account.toLowerCase());
         const expectedShort = accounts.map(shortAddress);
+        let matched = false;
         for (let index = 0; index < rowCount; index += 1) {
             const row = rows.nth(index);
             const text = ((await row.textContent()) ?? '').toLowerCase();
-            const matches = expected.some((account) => text.includes(account)) || expectedShort.some((account) => text.includes(account));
+            const matches = expected.some((account) => text.includes(account)) ||
+                expectedShort.some((account) => text.includes(account));
             if (!matches)
                 continue;
             const checkbox = row.locator('input[type="checkbox"]').first();
@@ -659,9 +2149,10 @@ class MetaMaskRealWallet {
                 await checkbox.check();
             else
                 await row.click();
-            return;
+            matched = true;
+            break;
         }
-        if (rowCount > 1) {
+        if (!matched) {
             throw new Error(`Unable to find requested MetaMask account in connect prompt: ${accounts.join(', ')}.`);
         }
     }
@@ -719,40 +2210,61 @@ async function prepareMetaMask({ expectedAddress, page, setup, wallet, }) {
 }
 export async function launchRealWallet(options) {
     const extensionName = options.extensionName ?? DEFAULT_EXTENSION_NAME;
-    if (!fs.existsSync(options.extensionPath)) {
-        throw new Error(`MetaMask extension path does not exist: ${options.extensionPath}`);
-    }
-    const profile = resolveRealWalletProfile(options.profileDir);
-    const context = await chromium.launchPersistentContext(profile.userDataDir, {
-        args: [
-            ...(profile.profileDirectory ? [`--profile-directory=${profile.profileDirectory}`] : []),
-            `--disable-extensions-except=${options.extensionPath}`,
-            `--load-extension=${options.extensionPath}`,
-        ],
+    const generation = options.generation ?? detectWalletGeneration(options.extensionPath);
+    const extensionSession = await launchRealWalletExtension({
         baseURL: options.baseURL,
-        headless: options.headless ?? false,
+        extensionName,
+        extensionPath: options.extensionPath,
+        headless: options.headless,
+        initialPage: 'home.html',
+        locale: 'en-US',
+        profileDir: options.profileDir,
         slowMo: options.slowMo,
     });
-    const extensionId = await getExtensionId(context, extensionName);
-    const page = await openExtensionHome(context, extensionId);
-    const wallet = new MetaMaskRealWallet(context, page, extensionId, options.expectedAddress, passwordForSetup(options.setup));
+    const { context, extensionId } = extensionSession;
+    const page = extensionSession.page ?? (await openExtensionHome(context, extensionId));
+    const walletPassword = passwordForSetup(options.setup);
+    const wallet = new MetaMaskRealWallet(context, page, extensionId, options.expectedAddress, walletPassword, generation);
     await prepareMetaMask({
         expectedAddress: options.expectedAddress,
         page,
         setup: options.setup,
         wallet,
     });
+    await routeMetaMaskTabToHome(page);
+    await unlockMetaMaskIfNeeded(page, walletPassword);
     return {
+        addNetwork: (network) => wallet.addNetwork(network),
+        addNewAccount: (name) => wallet.addNewAccount(name),
+        addNewToken: () => wallet.addNewToken(),
+        approveAddToken: () => wallet.approveAddToken(),
+        approveNewNetwork: () => wallet.approveNewNetwork(),
+        approveSwitchNetwork: () => wallet.approveSwitchNetwork(),
         approveTokenPermission: (approvalOptions) => wallet.approveTokenPermission(approvalOptions),
-        close: () => context.close(),
+        close: () => extensionSession.close(),
         confirmSignature: () => wallet.confirmSignature(),
         confirmTransaction: (confirmationOptions) => wallet.confirmTransaction(confirmationOptions),
+        confirmTransactionAndWaitForMining: (miningOptions) => wallet.confirmTransactionAndWaitForMining(miningOptions),
         connectToDapp: (accounts) => wallet.connectToDapp(accounts),
         context,
         extensionId,
         getAccountAddress: () => wallet.getAccountAddress(),
+        importToken: (token) => wallet.importToken(token),
+        importWalletFromPrivateKey: (privateKey) => wallet.importWalletFromPrivateKey(privateKey),
+        lock: () => wallet.lock(),
+        rejectAddToken: () => wallet.rejectAddToken(),
+        rejectNewNetwork: () => wallet.rejectNewNetwork(),
         rejectSignature: () => wallet.rejectSignature(),
+        rejectSwitchNetwork: () => wallet.rejectSwitchNetwork(),
+        rejectTokenPermission: () => wallet.rejectTokenPermission(),
         rejectTransaction: () => wallet.rejectTransaction(),
+        renameAccount: (currentName, newName) => wallet.renameAccount(currentName, newName),
+        resetAccount: () => wallet.resetAccount(),
+        switchAccount: (nameOrAddress) => wallet.switchAccount(nameOrAddress),
+        switchNetwork: (name, switchOptions) => wallet.switchNetwork(name, switchOptions),
+        toggleShowTestNetworks: (on) => wallet.toggleShowTestNetworks(on),
+        unlock: (password) => wallet.unlock(password),
+        waitForUnlocked: () => wallet.waitForUnlocked(),
         wallet,
     };
 }