@marigoldlabs/web3-tester 0.1.1 → 0.4.1

package/dist/real-wallet.js

@@ -1,10 +1,72 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { chromium } from '@playwright/test';
+import { extensionManifestVersion } from './metamask-extension.js';
+import { passwordForSetup } from './real-wallet-setup.js';
 const DEFAULT_EXTENSION_NAME = 'MetaMask';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const SHORT_TIMEOUT_MS = 2_000;
+const LOCATOR_PROBE_MS = 250;
+// 13.x derives many accounts from a heavily-used SRP; the account-tree
+// backup-and-sync races createNextMultichainAccountGroup and silently drops
+// ~1/3 of add clicks until it settles. Dwell before the first create.
+const ACCOUNT_TREE_SETTLE_MS = 12_000;
+const FULL_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
 const testId = (id) => `[data-testid="${id}"]`;
+/**
+ * @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;
+}
+/** @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';
+}
+function detectWalletGeneration(extensionPath) {
+    try {
+        return walletGenerationForVersion(extensionManifestVersion(extensionPath));
+    }
+    catch {
+        // No readable manifest version: assume the pinned default generation.
+        return '13x';
+    }
+}
+/**
+ * @internal Resolves the headed/headless choice. There is deliberately no
+ * default: the two modes have different validation status (headed is fully
+ * validated end to end; headless is validated for extension load and the
+ * clipboard round-trip only), so every run must pick one explicitly.
+ */
+export function resolveRealWalletHeadless(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const env = process.env.WEB3_TESTER_REAL_WALLET_HEADLESS;
+    if (env === 'true')
+        return true;
+    if (env === 'false')
+        return false;
+    if (env) {
+        throw new Error(`WEB3_TESTER_REAL_WALLET_HEADLESS must be "true" or "false", got "${env}".`);
+    }
+    throw new Error('Real-wallet launches need an explicit headed/headless choice: pass headless: true|false ' +
+        '(launchRealWallet / buildWalletProfile / realWalletOptions) or set ' +
+        'WEB3_TESTER_REAL_WALLET_HEADLESS=true|false. Headed is the fully validated mode; ' +
+        'headless needs the full Chromium build (npx playwright install chromium).');
+}
 function extensionUrl(extensionId, page = 'home.html') {
     return `chrome-extension://${extensionId}/${page}`;
 }
@@ -29,36 +91,195 @@ async function isHidden(locator, timeout = SHORT_TIMEOUT_MS) {
     await locator.first().waitFor({ state: 'hidden', timeout });
     return true;
 }
-async function clickFirstVisible(locators, timeout = SHORT_TIMEOUT_MS) {
-    for (const locator of locators) {
-        const target = locator.first();
-        if (!(await isVisible(target, timeout).catch(() => false)))
-            continue;
-        await target.click();
-        return true;
-    }
-    return false;
+function wait(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function findVisibleLocator(locators, timeout = SHORT_TIMEOUT_MS, options = {}) {
+    const deadline = Date.now() + timeout;
+    do {
+        const remaining = Math.max(deadline - Date.now(), 1);
+        for (const locator of locators) {
+            const target = locator.first();
+            const probeTimeout = Math.min(LOCATOR_PROBE_MS, remaining);
+            if (!(await isVisible(target, probeTimeout).catch(() => false)))
+                continue;
+            if (options.requireEnabled && !(await target.isEnabled({ timeout: 0 }).catch(() => false)))
+                continue;
+            return target;
+        }
+        const delay = Math.min(LOCATOR_PROBE_MS, Math.max(deadline - Date.now(), 0));
+        if (delay > 0)
+            await wait(delay);
+    } while (Date.now() < deadline);
+    return undefined;
+}
+async function clickFirstVisible(locators, timeout = SHORT_TIMEOUT_MS, options = { requireEnabled: true }) {
+    const target = await findVisibleLocator(locators, timeout, {
+        requireEnabled: options.requireEnabled ?? true,
+    });
+    if (!target)
+        return undefined;
+    await target.click({ force: options.force, timeout });
+    return target;
 }
 async function fillFirstVisible(locators, value, timeout = DEFAULT_TIMEOUT_MS) {
-    for (const locator of locators) {
-        const target = locator.first();
-        if (!(await isVisible(target, timeout).catch(() => false)))
-            continue;
-        await target.fill(value);
-        return true;
+    const target = await findVisibleLocator(locators, timeout);
+    if (!target)
+        return false;
+    await target.fill(value);
+    return true;
+}
+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')),
+        page.locator(testId('onboarding-terms-checkbox')),
+        page.locator(testId('srp-input-import__srp-note')),
+        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' }),
+        page.getByRole('heading', { name: 'Import a wallet' }),
+    ];
+}
+async function isMetaMaskOnboardingVisible(page) {
+    return isOnboardingRoute(page.url()) || Boolean(await findVisibleLocator(metaMaskOnboardingLocators(page), SHORT_TIMEOUT_MS));
+}
+function metaMaskSeedPhraseInputLocators(page) {
+    return [
+        page.locator(testId('srp-input-import__srp-note')),
+        page.locator('#first-word-input-text-area'),
+        page.locator('textarea[name="seedPhrase"]'),
+        page.locator('textarea').first(),
+    ];
+}
+function metaMaskSeedPhraseImportLocators(page) {
+    return [
+        ...metaMaskSeedPhraseInputLocators(page),
+        page.getByRole('heading', { name: 'Import a wallet' }),
+    ];
+}
+function metaMaskSeedPhraseWordInputs(page) {
+    return page.locator('.srp-input-import__words-list input, input[id^="import-srp__srp-word-"], input[data-testid^="import-srp__srp-word-"], input[name^="srp-word-"]');
+}
+async function isSeedPhraseConfirmEnabled(page, timeout = SHORT_TIMEOUT_MS) {
+    return Boolean(await findVisibleLocator([page.locator(testId('import-srp-confirm'))], timeout, {
+        requireEnabled: true,
+    }));
+}
+async function fillMetaMaskSeedPhraseWordGrid(page, words, startIndex = 0) {
+    const wordInputs = metaMaskSeedPhraseWordInputs(page);
+    for (let index = startIndex; index < words.length; index += 1) {
+        const input = wordInputs.nth(index);
+        await input.waitFor({ state: 'visible', timeout: DEFAULT_TIMEOUT_MS });
+        await input.fill(words[index]);
+        if (index < words.length - 1) {
+            await input.press('Space');
+            await wait(100);
+        }
     }
-    return false;
+}
+async function isMetaMaskSeedPhraseImportVisible(page) {
+    return (/#\/?onboarding\/import-with-recovery-phrase/.test(page.url()) ||
+        Boolean(await findVisibleLocator(metaMaskSeedPhraseImportLocators(page), SHORT_TIMEOUT_MS)));
+}
+async function isMetaMaskCreatePasswordVisible(page) {
+    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) {
     await page.waitForLoadState('domcontentloaded', { timeout: DEFAULT_TIMEOUT_MS }).catch(() => undefined);
     await isHidden(page.locator('.spinner, .loading-overlay, [data-testid="loading-overlay"]'), DEFAULT_TIMEOUT_MS).catch(() => undefined);
 }
+function metaMaskUnlockPasswordLocators(page) {
+    return [page.locator(testId('unlock-password')), page.locator('input[type="password"]').first()];
+}
+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 closeMetaMaskOverlay(page) {
-    await clickFirstVisible([
-        page.locator(testId('popover-close')),
-        page.locator('.mm-modal-content .mm-modal-header button').first(),
-        page.getByRole('button', { name: 'Close' }),
-    ], SHORT_TIMEOUT_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 closed = await clickFirstVisible([
+            page.locator(testId('not-now-button')),
+            page.locator(testId('popover-close')),
+            page.locator('.mm-modal-content button[aria-label="Close"]'),
+            page.locator('.mm-modal-content .mm-modal-header button').first(),
+        ], SHORT_TIMEOUT_MS).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 }),
+    ];
+}
+function metaMaskAccountMenuLocators(page) {
+    return [
+        page.locator(testId('account-options-menu-button')),
+        page.locator(testId('account-menu-icon')),
+        page.getByRole('button', { name: /Account options|Account menu/i }),
+    ];
+}
+function metaMaskPromptActions(page) {
+    return [
+        page.locator(testId('onboarding-complete-done')),
+        page.locator(testId('metametrics-no-thanks')),
+        page.getByRole('button', { name: 'No thanks' }),
+        page.getByRole('button', { name: 'Done' }),
+        page.getByRole('button', { name: 'Skip' }),
+        page.getByRole('button', { name: 'Continue' }),
+        page.getByRole('button', { name: 'Open wallet' }),
+        page.getByRole('button', { name: 'Maybe later' }),
+        page.getByRole('link', { name: 'Maybe later' }),
+    ];
+}
+function metaMaskTextPromptActions(page) {
+    return [
+        page.getByText('Maybe later', { exact: true }),
+        page.getByText('No thanks', { exact: true }),
+    ];
+}
+async function clickMetaMaskPromptAction(page, timeout = SHORT_TIMEOUT_MS) {
+    return ((await clickFirstVisible(metaMaskPromptActions(page), timeout)) ||
+        (await clickFirstVisible(metaMaskTextPromptActions(page), timeout, { requireEnabled: false })));
+}
+async function waitForMetaMaskHome(page, timeout = DEFAULT_TIMEOUT_MS) {
+    const deadline = Date.now() + timeout;
+    do {
+        await waitForMetaMaskReady(page);
+        if (await findVisibleLocator(metaMaskAccountMenuLocators(page), SHORT_TIMEOUT_MS))
+            return true;
+        if (await clickMetaMaskPromptAction(page, SHORT_TIMEOUT_MS))
+            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);
@@ -113,7 +334,7 @@ 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().startsWith(homeUrl))
+    if (page.url() !== homeUrl)
         await page.goto(homeUrl);
     await waitForMetaMaskReady(page);
     return page;
@@ -121,37 +342,105 @@ async function openExtensionHome(context, extensionId) {
 function notificationUrlPrefix(extensionId) {
     return extensionUrl(extensionId, 'notification.html');
 }
+function extensionPageUrlPrefix(extensionId) {
+    return `chrome-extension://${extensionId}/`;
+}
+function metaMaskActionContentLocators(page) {
+    return [
+        page.getByRole('heading', {
+            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|Add suggested tokens?/i),
+    ];
+}
+function metaMaskActionControlLocators(page) {
+    return [
+        page.locator(testId('confirm-footer-button')),
+        page.locator(testId('confirmation-submit-button')),
+        page.locator(testId('page-container-footer-next')),
+        page.locator(testId('request-signature__sign')),
+        page.locator(testId('signature-sign-button')),
+        page.locator(testId('custom-spending-cap-input')),
+        page.locator('.set-approval-for-all-warning__footer__approve-button'),
+        page.getByRole('button', { name: /^(Confirm|Connect|Next|Approve|Sign)$/i }),
+    ];
+}
+function metaMaskActionLocators(page) {
+    return [...metaMaskActionContentLocators(page), ...metaMaskActionControlLocators(page)];
+}
+async function findMetaMaskActionPage(context, extensionId) {
+    const extensionPrefix = extensionPageUrlPrefix(extensionId);
+    let controlOnlyPage;
+    for (const page of [...context.pages()].reverse()) {
+        if (page.isClosed() || !page.url().startsWith(extensionPrefix))
+            continue;
+        await page.waitForLoadState('domcontentloaded', { timeout: LOCATOR_PROBE_MS }).catch(() => undefined);
+        if (await findVisibleLocator(metaMaskActionContentLocators(page), LOCATOR_PROBE_MS, { requireEnabled: false })) {
+            return page;
+        }
+        if (!controlOnlyPage &&
+            (await findVisibleLocator(metaMaskActionControlLocators(page), LOCATOR_PROBE_MS, { requireEnabled: false }))) {
+            controlOnlyPage = page;
+        }
+    }
+    return controlOnlyPage;
+}
+async function findMetaMaskLockedPage(context, extensionId) {
+    const extensionPrefix = extensionPageUrlPrefix(extensionId);
+    for (const page of [...context.pages()].reverse()) {
+        if (page.isClosed() || !page.url().startsWith(extensionPrefix))
+            continue;
+        await page.waitForLoadState('domcontentloaded', { timeout: LOCATOR_PROBE_MS }).catch(() => undefined);
+        if (await isMetaMaskUnlockVisible(page))
+            return page;
+    }
+    return undefined;
+}
+function findMetaMaskNotificationPage(context, extensionId) {
+    const notificationPrefix = notificationUrlPrefix(extensionId);
+    return [...context.pages()]
+        .reverse()
+        .find((page) => !page.isClosed() && page.url().startsWith(notificationPrefix));
+}
 async function getNotificationPage(context, extensionId, timeout = DEFAULT_TIMEOUT_MS) {
     const prefix = notificationUrlPrefix(extensionId);
+    const extensionPrefix = extensionPageUrlPrefix(extensionId);
     const startedAt = Date.now();
-    let page = context.pages().find((candidate) => candidate.url().startsWith(prefix));
+    // 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 + Math.min(5_000, timeout / 2);
+    let forcedPage;
+    let page = await findMetaMaskActionPage(context, extensionId);
     while (!page && Date.now() - startedAt < timeout) {
-        const pendingPages = context.pages().filter((candidate) => !candidate.isClosed());
-        for (const pendingPage of pendingPages) {
-            await pendingPage
-                .waitForURL((url) => url.href.startsWith(prefix), { timeout: 250 })
-                .catch(() => undefined);
-            if (pendingPage.url().startsWith(prefix)) {
-                page = pendingPage;
-                break;
-            }
-        }
-        if (page)
-            break;
         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) {
-            page = context.pages().find((openPage) => openPage.url().startsWith(prefix));
-            continue;
+        if (!forcedPage && Date.now() >= forceAt) {
+            forcedPage = await context.newPage();
+            await forcedPage.goto(extensionUrl(extensionId, 'notification.html')).catch(() => undefined);
+            await waitForMetaMaskReady(forcedPage);
         }
-        await candidate
-            .waitForURL((url) => url.href.startsWith(prefix), { timeout: Math.min(remaining, 5_000) })
-            .catch(() => undefined);
-        if (candidate.url().startsWith(prefix))
-            page = candidate;
+        else {
+            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),
+                })
+                    .catch(() => undefined);
+            }
+        }
+        page = await findMetaMaskActionPage(context, extensionId);
     }
-    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;
@@ -159,62 +448,129 @@ 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');
+}
+async function pageContainsAddress(page, address) {
+    const normalizedAddress = address.toLowerCase();
+    const text = ((await page.locator('body').textContent({ timeout: SHORT_TIMEOUT_MS }).catch(() => '')) ?? '')
+        .replace(/\s+/g, '')
+        .toLowerCase();
+    return (text.includes(normalizedAddress) ||
+        (text.includes(normalizedAddress.slice(0, 6)) && text.includes(normalizedAddress.slice(-4))) ||
+        (text.includes(normalizedAddress.slice(0, 7)) && text.includes(normalizedAddress.slice(-5))));
+}
 async function fillSeedPhrase(page, seedPhrase) {
     const words = seedPhrase.trim().split(/\s+/);
     if (words.length < 12) {
         throw new Error('setup.seedPhrase must contain at least 12 words.');
     }
-    const singleInputFilled = await fillFirstVisible([
-        page.locator(testId('srp-input-import__srp-note')),
-        page.locator('textarea[name="seedPhrase"]'),
-        page.locator('textarea').first(),
-    ], words.join(' '), SHORT_TIMEOUT_MS);
-    if (singleInputFilled)
-        return;
-    const wordInputs = page.locator('input[id^="import-srp__srp-word-"], input[data-testid^="import-srp__srp-word-"]');
+    const singleInput = await findVisibleLocator(metaMaskSeedPhraseInputLocators(page), DEFAULT_TIMEOUT_MS);
+    if (singleInput) {
+        await startSeedPhraseWordGrid(singleInput, words[0]);
+        await fillMetaMaskSeedPhraseWordGrid(page, words, 1);
+        if (await isSeedPhraseConfirmEnabled(page)) {
+            return;
+        }
+    }
+    const wordInputs = metaMaskSeedPhraseWordInputs(page);
     if ((await wordInputs.count()) >= words.length) {
+        await fillMetaMaskSeedPhraseWordGrid(page, words);
+        if (await isSeedPhraseConfirmEnabled(page))
+            return;
+    }
+    const textboxes = page.getByRole('textbox');
+    if ((await textboxes.count()) >= words.length) {
         for (const [index, word] of words.entries()) {
-            await wordInputs.nth(index).fill(word);
+            await textboxes.nth(index).fill(word);
         }
         return;
     }
     throw new Error('Unable to find MetaMask seed phrase input fields.');
 }
 async function importMetaMaskWallet(page, setup) {
-    if (!setup.password || !setup.seedPhrase) {
-        throw new Error('MetaMask is on onboarding. Provide setup.password and setup.seedPhrase to import a wallet through web3-tester, or use a preconfigured persistent profile.');
+    const password = passwordForSetup(setup);
+    if (!password || !setup.seedPhrase) {
+        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();
     }
-    const importStarted = await clickFirstVisible([
-        page.locator(testId('onboarding-import-wallet')),
-        page.locator(testId('onboarding-import-with-srp-button')),
-        page.getByRole('button', { name: 'Import an existing wallet' }),
-        page.getByRole('button', { name: 'Import wallet' }),
-    ], DEFAULT_TIMEOUT_MS);
-    if (!importStarted)
-        throw new Error('Unable to start MetaMask wallet import flow.');
-    await clickFirstVisible([
-        page.locator(testId('metametrics-no-thanks')),
-        page.locator(testId('metametrics-i-agree')),
-        page.getByRole('button', { name: 'No thanks' }),
-        page.getByRole('button', { name: 'I agree' }),
-    ], SHORT_TIMEOUT_MS);
-    await fillSeedPhrase(page, setup.seedPhrase);
-    const seedConfirmed = await clickFirstVisible([
-        page.locator(testId('import-srp-confirm')),
-        page.getByRole('button', { name: 'Confirm Secret Recovery Phrase' }),
-        page.getByRole('button', { name: 'Confirm' }),
-    ], DEFAULT_TIMEOUT_MS);
-    if (!seedConfirmed)
-        throw new Error('Unable to confirm MetaMask seed phrase import.');
-    const passwordFilled = await fillFirstVisible([page.locator(testId('create-password-new-input')), page.locator('input[type="password"]').nth(0)], setup.password);
+    if (!(await isMetaMaskSeedPhraseImportVisible(page)) && !(await isMetaMaskCreatePasswordVisible(page))) {
+        const importStarted = await clickFirstVisible([
+            page.locator(testId('onboarding-import-wallet')),
+            page.locator(testId('onboarding-import-with-srp-button')),
+            page.getByRole('button', { name: 'I have an existing wallet' }),
+            page.getByRole('button', { name: 'Import an existing wallet' }),
+            page.getByRole('button', { name: 'Import wallet' }),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!importStarted)
+            throw new Error('Unable to start MetaMask wallet import flow.');
+        await waitForMetaMaskReady(page);
+        await clickFirstVisible([
+            page.locator(testId('onboarding-import-with-srp-button')),
+            page.getByRole('button', { name: 'Import using Secret Recovery Phrase' }),
+        ], 5_000);
+        await clickFirstVisible([
+            page.locator(testId('metametrics-no-thanks')),
+            page.locator(testId('metametrics-i-agree')),
+            page.getByRole('button', { name: 'No thanks' }),
+            page.getByRole('button', { name: 'I agree' }),
+        ], SHORT_TIMEOUT_MS);
+    }
+    if (!(await isMetaMaskCreatePasswordVisible(page))) {
+        await fillSeedPhrase(page, setup.seedPhrase);
+        const seedConfirmed = await clickFirstVisible([
+            page.locator(testId('import-srp-confirm')),
+            page.getByRole('button', { name: 'Confirm Secret Recovery Phrase' }),
+            page.getByRole('button', { name: 'Confirm' }),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!seedConfirmed)
+            throw new Error('Unable to confirm MetaMask seed phrase import.');
+    }
+    const passwordFilled = await fillFirstVisible([page.locator(testId('create-password-new-input')), page.locator('input[type="password"]').nth(0)], password);
     if (!passwordFilled)
         throw new Error('Unable to find MetaMask password input.');
-    const confirmationPasswordFilled = await fillFirstVisible([page.locator(testId('create-password-confirm-input')), page.locator('input[type="password"]').nth(1)], setup.password);
+    const confirmationPasswordFilled = await fillFirstVisible([page.locator(testId('create-password-confirm-input')), page.locator('input[type="password"]').nth(1)], password);
     if (!confirmationPasswordFilled)
         throw new Error('Unable to find MetaMask password confirmation input.');
     const passwordTerms = page.locator(testId('create-password-terms'));
@@ -224,38 +580,102 @@ 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 clickFirstVisible([
-        page.locator(testId('onboarding-complete-done')),
-        page.getByRole('button', { name: 'Done' }),
-        page.getByRole('button', { name: 'Skip' }),
-    ], DEFAULT_TIMEOUT_MS);
-    await waitForMetaMaskReady(page);
+    await finishMetaMaskOnboarding(page, password);
 }
 async function unlockMetaMask(page, password) {
-    const passwordFilled = await fillFirstVisible([page.locator(testId('unlock-password')), page.locator('input[type="password"]').first()], password, DEFAULT_TIMEOUT_MS);
+    const passwordFilled = await fillFirstVisible(metaMaskUnlockPasswordLocators(page), password, DEFAULT_TIMEOUT_MS);
     if (!passwordFilled)
         throw new Error('Unable to find MetaMask unlock password input.');
-    const unlocked = await clickFirstVisible([page.locator(testId('unlock-submit')), page.getByRole('button', { name: 'Unlock' })], DEFAULT_TIMEOUT_MS);
+    const unlocked = await clickFirstVisible(metaMaskUnlockSubmitLocators(page), DEFAULT_TIMEOUT_MS);
     if (!unlocked)
         throw new Error('Unable to submit MetaMask unlock form.');
     await waitForMetaMaskReady(page);
 }
+async function unlockMetaMaskIfNeeded(page, password) {
+    if (!(await isMetaMaskUnlockVisible(page)))
+        return false;
+    if (!password) {
+        throw new Error('MetaMask profile is locked. Provide setup.password to unlock through web3-tester, or unlock the persistent profile before running.');
+    }
+    await page.bringToFront().catch(() => undefined);
+    await unlockMetaMask(page, password);
+    return true;
+}
+async function finishMetaMaskOnboarding(page, password) {
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        await waitForMetaMaskReady(page);
+        const actions = [...metaMaskPromptActions(page), ...metaMaskTextPromptActions(page)];
+        const onSetupScreen = isOnboardingRoute(page.url()) ||
+            Boolean(await findVisibleLocator(actions, SHORT_TIMEOUT_MS));
+        if (!onSetupScreen)
+            break;
+        const advanced = await clickMetaMaskPromptAction(page, 5_000);
+        if (!advanced)
+            break;
+    }
+    // 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())) {
+        const homeUrl = page.url().split('#')[0];
+        await page.goto(homeUrl).catch(() => undefined);
+        await waitForMetaMaskReady(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;
     homePage;
     extensionId;
-    constructor(context, homePage, extensionId) {
+    expectedAddress;
+    walletPassword;
+    generation;
+    constructor(context, homePage, extensionId, 
+    // Mutable: account mutations (switchAccount, imports, new accounts) must
+    // invalidate it, or getAccountAddress's fast-path returns stale results.
+    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()) {
@@ -276,9 +696,12 @@ class MetaMaskRealWallet {
             await scrollButton.click();
         }
         const signed = await clickFirstVisible([
+            page.locator(testId('confirm-footer-button')),
+            page.locator(testId('confirmation-submit-button')),
             page.locator(testId('request-signature__sign')),
             structuredSignButton,
             page.locator(testId('page-container-footer-next')),
+            page.getByRole('button', { name: 'Confirm' }),
             page.getByRole('button', { name: 'Sign' }),
         ], DEFAULT_TIMEOUT_MS);
         if (!signed)
@@ -286,10 +709,43 @@ class MetaMaskRealWallet {
         await clickFirstVisible([page.locator(testId('signature-warning-sign-button'))], SHORT_TIMEOUT_MS);
     }
     async confirmTransaction(options) {
-        const page = await this.notificationPage();
-        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);
+        let page = await 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);
+            const clicked = await this.confirmFooterAction(page);
+            // The click registered once the confirmed control leaves the view or
+            // the popup closes — no fixed sleep deciding "settled".
+            await 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 findVisibleLocator(metaMaskActionLocators(page), SHORT_TIMEOUT_MS, {
+                    requireEnabled: false,
+                });
+                if (!nextStep)
+                    return;
+                await 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;
+            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 page.bringToFront().catch(() => undefined);
+        }
+        throw new Error('MetaMask transaction confirmation did not settle after multiple confirmation steps.');
     }
     async connectToDapp(accounts) {
         const page = await this.notificationPage();
@@ -302,20 +758,229 @@ class MetaMaskRealWallet {
     }
     async getAccountAddress() {
         const page = await this.home();
+        await waitForMetaMaskHome(page);
         await closeMetaMaskOverlay(page);
-        const openedMenu = await clickFirstVisible([page.locator(testId('account-options-menu-button'))], 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();
+        if (this.expectedAddress && await pageContainsAddress(page, this.expectedAddress)) {
+            return this.expectedAddress;
+        }
+        // 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);
+        // 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 closeMetaMaskOverlay(page);
+            return elementText;
+        }
+        await addressCopy.click().catch(() => undefined);
+        const pasted = await this.readClipboardViaPaste();
         await closeMetaMaskOverlay(page);
-        if (!address?.startsWith('0x'))
-            throw new Error('Unable to read selected MetaMask account address.');
-        return address;
+        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) {
+        if (this.generation === '12x') {
+            const menuOpened = await clickFirstVisible([page.locator(testId('account-options-menu-button'))], SHORT_TIMEOUT_MS);
+            const detailsOpened = menuOpened &&
+                (await clickFirstVisible([page.locator(testId('account-list-menu-details'))], DEFAULT_TIMEOUT_MS));
+            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.
+        let addressMenuOpened = await clickFirstVisible([page.locator(testId('default-address-menu-button'))], SHORT_TIMEOUT_MS);
+        if (!addressMenuOpened) {
+            const pickerOpened = await clickFirstVisible([page.locator(testId('account-menu-icon'))], DEFAULT_TIMEOUT_MS);
+            if (!pickerOpened)
+                throw new Error('Unable to open the MetaMask account picker.');
+            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 =
+                (await clickFirstVisible([selectedRow.locator(testId('multichain-account-cell-end-accessory'))], DEFAULT_TIMEOUT_MS)) ??
+                    (await clickFirstVisible([page.getByRole('button', { name: 'Open multichain account address menu' }).first()], SHORT_TIMEOUT_MS));
+        }
+        if (!addressMenuOpened)
+            throw new Error('Unable to open the MetaMask account address menu.');
+        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')),
+        ], DEFAULT_TIMEOUT_MS);
+        if (!detailsOpened)
+            throw new Error('Unable to open the MetaMask account address view.');
+    }
+    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) {
+        const page = await this.home();
+        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. (The bare "Add network"
+        // buttons on the default tab add preconfigured popular networks, not a
+        // custom RPC.) Playwright's actionability checks wait out the modal
+        // slide-in; 12.x has no Custom tab.
+        if (this.generation === '13x') {
+            await clickFirstVisible([page.getByRole('tab', { name: /^Custom$/i })], 8_000);
+        }
+        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);
+    }
+    async switchNetwork(name, options = {}) {
+        const page = await this.home();
+        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.');
+        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. 12.x has no Custom tab, so
+        // its retry just re-probes the rows with the full budget.
+        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) {
+            throw new Error(`Unable to select MetaMask network "${name}". Add it first with addNetwork(), and check "Show test networks" if it is a testnet.`);
+        }
+        await waitForMetaMaskReady(page);
+        await closeMetaMaskOverlay(page);
+    }
+    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();
@@ -328,16 +993,843 @@ class MetaMaskRealWallet {
         const page = await this.notificationPage();
         await this.rejectFooterAction(page);
     }
-    async home() {
-        if (!this.homePage.isClosed()) {
-            await this.homePage.bringToFront().catch(() => undefined);
-            await waitForMetaMaskReady(this.homePage);
-            return this.homePage;
+    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 normalized = normalizePrivateKey(privateKey);
+        const page = await this.preparedHome();
+        await this.openAccountPicker(page);
+        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);
+                }
+                const addWallet = page.locator(testId('account-list-add-wallet-button')).first();
+                await addWallet.scrollIntoViewIfNeeded({ timeout: SHORT_TIMEOUT_MS }).catch(() => undefined);
+                if (await clickFirstVisible([addWallet], DEFAULT_TIMEOUT_MS)) {
+                    importOpened = Boolean(await clickFirstVisible([
+                        page.locator(testId('choose-wallet-type-import-account')),
+                        page.getByText('Import an account', { exact: true }),
+                    ], DEFAULT_TIMEOUT_MS));
+                }
+            }
+        }
+        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);
+        if (!keyFilled)
+            throw new Error('Unable to find the MetaMask private key input.');
+        const confirmed = await clickFirstVisible([page.locator(testId('import-account-confirm-button'))], DEFAULT_TIMEOUT_MS);
+        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'), DEFAULT_TIMEOUT_MS).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;
+        await closeMetaMaskOverlay(page);
+    }
+    async addNewAccount(name) {
+        const page = await this.preparedHome();
+        if (this.generation === '12x') {
+            await this.openAccountPicker(page);
+            // 12.x: action button → Add account → optional name → submit.
+            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.');
+            }
+            if (name) {
+                await fillFirstVisible([page.locator('#account-name'), page.locator(testId('account-name-input'))], name, SHORT_TIMEOUT_MS);
+            }
+            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;
+            await closeMetaMaskOverlay(page);
+            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 this.openAccountPicker(page);
+        const walletId = await this.activeSrpWalletId(page);
+        await page.keyboard.press('Escape').catch(() => undefined);
+        await wait(ACCOUNT_TREE_SETTLE_MS);
+        const walletCellPrefix = `[data-testid^="multichain-account-cell-${walletId}/"]`;
+        const createAttempts = 8;
+        let newIndex = -1;
+        for (let attempt = 0; attempt < createAttempts && newIndex < 0; 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);
+            await page.goto(`${home}#/multichain-wallet-details-page?id=${encodeURIComponent(walletId)}`);
+            await waitForMetaMaskReady(page);
+            const addButton = page.locator(testId('add-multichain-account-button')).first();
+            if (!(await addButton.waitFor({ state: 'visible', timeout: DEFAULT_TIMEOUT_MS }).then(() => true).catch(() => false))) {
+                throw new Error('Unable to find the MetaMask add-account control on the wallet details page — update web3-tester for this MetaMask version.');
+            }
+            await this.waitForAddAccountReady(addButton);
+            // 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 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;
+            await addButton.click();
+            const created = await page
+                .locator(testId(`multichain-account-cell-${walletId}/${candidate}`))
+                .waitFor({ state: 'attached', timeout: 15_000 })
+                .then(() => true)
+                .catch(() => false);
+            if (created)
+                newIndex = candidate;
+        }
+        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;
+        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 page.goto(`${home}#/multichain-account-details?accountGroupId=${encodeURIComponent(`${walletId}/${newIndex}`)}`);
+            await 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 this.fillAccountNameAndSave(page, name);
+        }
+        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 this.preparedHome();
+        await this.openAccountPicker(page);
+        if (this.generation === '13x') {
+            const cell = await 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 cell.click();
+            await waitForMetaMaskReady(page);
+            this.expectedAddress = FULL_ADDRESS_PATTERN.test(nameOrAddress) ? nameOrAddress : undefined;
+            await 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;
+        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() {
+        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);
+        if (!locked)
+            throw new Error('Unable to find the MetaMask lock action in the global menu.');
+        const lockScreen = await findVisibleLocator(metaMaskUnlockPasswordLocators(page), DEFAULT_TIMEOUT_MS);
+        if (!lockScreen)
+            throw 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 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 if (
+        // 13.x: Developer tools tab → "Delete activity and nonce data".
+        await clickFirstVisible([
+            page.locator(testId('settings-tab-item-developer-tools')),
+            page.getByText(/^Developer tools$/i),
+        ], SHORT_TIMEOUT_MS)) {
+            if (await clickFirstVisible([
+                page.locator(testId('developer-options-delete-activity-and-nonce-data')).getByRole('button'),
+                page.locator(testId('developer-options-delete-activity-and-nonce-data')),
+            ], SHORT_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"]')], 'Clear activity', SHORT_TIMEOUT_MS);
+            if (await clickFirstVisible([page.locator(testId('settings-search-result-item')).first()], SHORT_TIMEOUT_MS)) {
+                const cleared = await clickFirstVisible([
+                    page.locator(testId('advanced-setting-reset-account')).getByRole('button'),
+                    page.locator(testId('developer-options-delete-activity-and-nonce-data')).getByRole('button'),
+                    page.getByRole('button', { name: /Clear activity( tab)? data|Delete activity/i }),
+                ], DEFAULT_TIMEOUT_MS);
+                if (cleared) {
+                    await this.confirmResetModal(page);
+                    await this.leaveSettings(page);
+                    return;
+                }
+            }
         }
-        return openExtensionHome(this.context, this.extensionId);
+        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) {
+        const 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.
+            const home = page.url().split('#')[0];
+            const toggle = page.locator(testId('networks-page-show-test-networks')).first();
+            // The first navigation to #/networks can race the React render; renavigate
+            // until the toggle attaches.
+            let toggleReady = false;
+            for (let attempt = 0; attempt < 3 && !toggleReady; attempt += 1) {
+                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);
+                toggleReady = await toggle
+                    .waitFor({ state: 'attached', timeout: 10_000 })
+                    .then(() => true)
+                    .catch(() => false);
+            }
+            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(home);
+            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 this.confirmTransaction({ gasSetting: options.gasSetting });
+        const timeoutMs = options.timeoutMs ?? 60_000;
+        const page = await this.preparedHome();
+        const activityOpened = await 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;
+        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 {
+            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 preparedHome() {
+        const page = await this.home();
+        await waitForMetaMaskHome(page);
+        await closeMetaMaskOverlay(page);
+        return page;
+    }
+    async openAccountPicker(page) {
+        // Under load the home screen can still be settling when the picker icon is
+        // probed; on retry, re-navigate to a clean home render before re-clicking.
+        // (The icon is an always-enabled control, so don't gate on enabled-ness.)
+        const home = page.url().split('#')[0];
+        let opened;
+        for (let attempt = 0; attempt < 3 && !opened; attempt += 1) {
+            if (attempt > 0) {
+                await page.goto(`${home}#/`).catch(() => undefined);
+                await waitForMetaMaskHome(page, DEFAULT_TIMEOUT_MS);
+            }
+            opened = await clickFirstVisible([page.locator(testId('account-menu-icon'))], DEFAULT_TIMEOUT_MS, {
+                requireEnabled: false,
+            });
+        }
+        if (!opened)
+            throw new Error('Unable to open the MetaMask account picker.');
+        await this.settleAccountList(page);
+    }
+    // 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) {
+        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);
+        // The filter debounces; give the list a beat to re-render.
+        await wait(700);
+        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 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: SHORT_TIMEOUT_MS }).catch(() => null))?.trim();
+            if (cellName === name)
+                return cell;
+        }
+        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 count = await cells.count();
+        for (let index = 0; index < count; index += 1) {
+            const cell = cells.nth(index);
+            const text = ((await cell.textContent({ timeout: SHORT_TIMEOUT_MS }).catch(() => '')) ?? '')
+                .replace(/\s+/g, '')
+                .toLowerCase();
+            if (text.includes(addressLc) || text.includes(short))
+                return cell;
+        }
+        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) {
+        const deadline = Date.now() + DEFAULT_TIMEOUT_MS;
+        let stable = 0;
+        while (Date.now() < deadline) {
+            const label = (await addButton.textContent({ timeout: SHORT_TIMEOUT_MS }).catch(() => ''))?.trim();
+            if (label === 'Add account') {
+                stable += 1;
+                if (stable >= 2) {
+                    await wait(1_500);
+                    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 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 fillFirstVisible([
+            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);
+        return page;
     }
     async notificationPage() {
-        return getNotificationPage(this.context, this.extensionId);
+        await this.unlockVisibleMetaMask();
+        let page = await getNotificationPage(this.context, this.extensionId).catch(async (error) => {
+            if (await this.unlockVisibleMetaMask()) {
+                return getNotificationPage(this.context, this.extensionId);
+            }
+            throw error;
+        });
+        if (await unlockMetaMaskIfNeeded(page, this.walletPassword)) {
+            page = await getNotificationPage(this.context, this.extensionId);
+        }
+        return page;
+    }
+    async unlockVisibleMetaMask() {
+        const page = await findMetaMaskLockedPage(this.context, this.extensionId);
+        if (!page)
+            return false;
+        return unlockMetaMaskIfNeeded(page, this.walletPassword);
     }
     async confirmFooterAction(page, timeout = DEFAULT_TIMEOUT_MS) {
         const confirmed = await clickFirstVisible([
@@ -351,6 +1843,7 @@ class MetaMaskRealWallet {
         ], timeout);
         if (!confirmed)
             throw new Error('Unable to confirm MetaMask notification.');
+        return confirmed;
     }
     async rejectFooterAction(page, extraLocators = []) {
         const rejected = await clickFirstVisible([
@@ -366,16 +1859,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();
@@ -383,9 +1898,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(', ')}.`);
         }
     }
@@ -427,24 +1943,13 @@ class MetaMaskRealWallet {
     }
 }
 async function prepareMetaMask({ expectedAddress, page, setup, wallet, }) {
-    const onboardingImport = page.locator(testId('onboarding-import-wallet'));
-    const onboardingCreate = page.locator(testId('onboarding-create-wallet'));
-    const onboardingTerms = page.locator(testId('onboarding-terms-checkbox'));
-    if ((await isVisible(onboardingImport, SHORT_TIMEOUT_MS).catch(() => false)) ||
-        (await isVisible(onboardingCreate, SHORT_TIMEOUT_MS).catch(() => false)) ||
-        (await isVisible(onboardingTerms, SHORT_TIMEOUT_MS).catch(() => false))) {
-        if (!setup?.password || !setup.seedPhrase) {
-            throw new Error('MetaMask is on onboarding. Provide setup.password and setup.seedPhrase to import a wallet through web3-tester, or use a preconfigured persistent profile.');
+    if (await isMetaMaskOnboardingVisible(page)) {
+        if (!setup?.seedPhrase) {
+            throw new Error('MetaMask is on onboarding. Provide setup.seedPhrase to import a wallet through web3-tester, or use a preconfigured persistent profile.');
         }
         await importMetaMaskWallet(page, setup);
     }
-    const unlockPassword = page.locator(testId('unlock-password'));
-    if (await isVisible(unlockPassword, SHORT_TIMEOUT_MS).catch(() => false)) {
-        if (!setup?.password) {
-            throw new Error('MetaMask profile is locked. Provide setup.password to unlock through web3-tester, or unlock the persistent profile before running.');
-        }
-        await unlockMetaMask(page, setup.password);
-    }
+    await unlockMetaMaskIfNeeded(page, passwordForSetup(setup));
     if (!expectedAddress)
         return;
     const address = await wallet.getAccountAddress();
@@ -457,20 +1962,39 @@ export async function launchRealWallet(options) {
     if (!fs.existsSync(options.extensionPath)) {
         throw new Error(`MetaMask extension path does not exist: ${options.extensionPath}`);
     }
+    const generation = options.generation ?? detectWalletGeneration(options.extensionPath);
+    const headless = resolveRealWalletHeadless(options.headless);
     const profile = resolveRealWalletProfile(options.profileDir);
-    const context = await chromium.launchPersistentContext(profile.userDataDir, {
+    const context = await chromium
+        .launchPersistentContext(profile.userDataDir, {
         args: [
             ...(profile.profileDirectory ? [`--profile-directory=${profile.profileDirectory}`] : []),
             `--disable-extensions-except=${options.extensionPath}`,
             `--load-extension=${options.extensionPath}`,
         ],
         baseURL: options.baseURL,
-        headless: options.headless ?? false,
+        // channel 'chromium' is the Playwright-blessed way to run extensions
+        // both headed and headless: it selects the full Chromium build (the
+        // default headless shell cannot load extensions).
+        channel: 'chromium',
+        headless,
+        // Text fallbacks in the selector stacks are English; pin the UI locale.
+        locale: 'en-US',
         slowMo: options.slowMo,
+    })
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/executable doesn't exist/i.test(message)) {
+            throw new Error("Real-wallet mode needs the full Chromium build for channel 'chromium' — a " +
+                'chromium_headless_shell-only install cannot load extensions. ' +
+                'Run: npx playwright install chromium\n' +
+                message);
+        }
+        throw error;
     });
     const extensionId = await getExtensionId(context, extensionName);
     const page = await openExtensionHome(context, extensionId);
-    const wallet = new MetaMaskRealWallet(context, page, extensionId);
+    const wallet = new MetaMaskRealWallet(context, page, extensionId, options.expectedAddress, passwordForSetup(options.setup), generation);
     await prepareMetaMask({
         expectedAddress: options.expectedAddress,
         page,
@@ -478,16 +2002,36 @@ export async function launchRealWallet(options) {
         wallet,
     });
     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(),
         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),
         wallet,
     };
 }