@marigoldlabs/web3-tester 0.1.2 → 0.4.2

package/dist/real-wallet-extension.js

@@ -0,0 +1,245 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+export function resolveRealWalletProfile(profileDir) {
+    const resolved = path.resolve(profileDir);
+    const profileDirectory = path.basename(resolved);
+    const userDataDir = path.dirname(resolved);
+    const looksLikeChromeProfile = /^(?:Default|Profile \d+)$/.test(profileDirectory);
+    if (looksLikeChromeProfile && fs.existsSync(path.join(userDataDir, 'Local State'))) {
+        return { profileDirectory, userDataDir };
+    }
+    return { userDataDir: resolved };
+}
+/**
+ * Resolves the headed/headless choice for real-wallet extension launches.
+ * The explicit option wins over the environment.
+ */
+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 ' +
+        '(launchRealWalletExtension / 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).');
+}
+export function readExtensionManifest(extensionPath) {
+    const manifestPath = path.join(extensionPath, 'manifest.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read extension manifest at ${manifestPath}: ${message}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('manifest is not an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to parse extension manifest at ${manifestPath}: ${message}`);
+    }
+}
+function usableManifestString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || /^__MSG_[^_]+__$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+export function extensionManifestName(extensionPath) {
+    return usableManifestString(readExtensionManifest(extensionPath).name);
+}
+export function extensionManifestDefaultPage(manifest) {
+    return (usableManifestString(manifest.action?.default_popup) ??
+        usableManifestString(manifest.browser_action?.default_popup) ??
+        usableManifestString(manifest.options_ui?.page) ??
+        usableManifestString(manifest.side_panel?.default_path));
+}
+function normalizeExtensionPage(page = '') {
+    return page.replace(/^\/+/, '');
+}
+export function extensionPageUrl(extensionId, page = '') {
+    const normalized = normalizeExtensionPage(page);
+    return `chrome-extension://${extensionId}/${normalized}`;
+}
+export function resolveExtensionPageUrl(extensionId, page = '') {
+    if (/^chrome-extension:\/\//.test(page))
+        return page;
+    return extensionPageUrl(extensionId, page);
+}
+export function extensionIdFromUrl(url) {
+    return /^chrome-extension:\/\/([^/]+)\//.exec(url)?.[1];
+}
+function wait(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isRecoverableExtensionPageOpenError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /ERR_BLOCKED_BY_CLIENT|page crashed|target page, context or browser has been closed/i.test(message);
+}
+async function discoverExtensionIdFromRuntime(context, timeoutMs) {
+    const workerId = context.serviceWorkers().map((worker) => extensionIdFromUrl(worker.url())).find(Boolean);
+    if (workerId)
+        return workerId;
+    const pageId = context.pages().map((page) => extensionIdFromUrl(page.url())).find(Boolean);
+    if (pageId)
+        return pageId;
+    const worker = await context.waitForEvent('serviceworker', { timeout: timeoutMs }).catch(() => undefined);
+    if (worker) {
+        const extensionId = extensionIdFromUrl(worker.url());
+        if (extensionId)
+            return extensionId;
+    }
+    return undefined;
+}
+async function discoverExtensionIdFromManagementApi(context, extensionName) {
+    const page = await context.newPage();
+    try {
+        await page.goto('chrome://extensions', { waitUntil: 'domcontentloaded' });
+        const extensions = await page.evaluate(() => {
+            const chromeApi = globalThis;
+            return new Promise((resolve, reject) => {
+                if (!chromeApi.chrome?.management?.getAll) {
+                    reject(new Error('chrome.management.getAll is not available on chrome://extensions.'));
+                    return;
+                }
+                chromeApi.chrome.management.getAll((items) => {
+                    const error = chromeApi.chrome?.runtime?.lastError;
+                    if (error)
+                        reject(new Error(error.message ?? 'Unable to enumerate Chrome extensions.'));
+                    else
+                        resolve(items);
+                });
+            });
+        });
+        const exact = extensions.find((extension) => extension.name.toLowerCase() === extensionName.toLowerCase());
+        if (exact)
+            return exact.id;
+        const available = extensions.map((extension) => extension.name).sort().join(', ');
+        throw new Error(`Unable to find extension "${extensionName}". Installed extensions: ${available || 'none'}.`);
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+export async function discoverRealWalletExtensionId(context, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const runtimeId = await discoverExtensionIdFromRuntime(context, timeoutMs);
+    if (runtimeId)
+        return runtimeId;
+    if (!options.extensionName) {
+        throw new Error('Unable to discover extension ID from runtime pages/service workers. Pass extensionName or extensionId.');
+    }
+    return discoverExtensionIdFromManagementApi(context, options.extensionName);
+}
+export async function openRealWalletExtensionPage(context, extensionId, page = '') {
+    const url = resolveExtensionPageUrl(extensionId, page);
+    const acceptsHashRoute = !url.includes('#');
+    let lastError;
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        const existing = context
+            .pages()
+            .find((candidate) => {
+            if (candidate.isClosed())
+                return false;
+            const candidateUrl = candidate.url();
+            return candidateUrl === url || (acceptsHashRoute && candidateUrl.startsWith(`${url}#`));
+        });
+        const target = existing ?? (await context.newPage());
+        try {
+            if (target.url() !== url)
+                await target.goto(url, { waitUntil: 'domcontentloaded' });
+            await target.waitForLoadState('domcontentloaded').catch(() => undefined);
+            return target;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === 5 || !isRecoverableExtensionPageOpenError(error))
+                throw error;
+            await target.close().catch(() => undefined);
+            await wait(750 + attempt * 750);
+        }
+    }
+    throw lastError;
+}
+export async function launchRealWalletExtension(options) {
+    const extensionPath = path.resolve(options.extensionPath);
+    if (!fs.existsSync(extensionPath)) {
+        throw new Error(`Wallet extension path does not exist: ${extensionPath}`);
+    }
+    const manifest = readExtensionManifest(extensionPath);
+    const extensionName = options.extensionName ?? usableManifestString(manifest.name);
+    const headless = resolveRealWalletHeadless(options.headless);
+    const profile = resolveRealWalletProfile(options.profileDir);
+    const context = await chromium
+        .launchPersistentContext(profile.userDataDir, {
+        args: [
+            ...(profile.profileDirectory ? [`--profile-directory=${profile.profileDirectory}`] : []),
+            `--disable-extensions-except=${extensionPath}`,
+            `--load-extension=${extensionPath}`,
+            ...(options.launchArgs ?? []),
+        ],
+        baseURL: options.baseURL,
+        channel: 'chromium',
+        headless,
+        locale: options.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 extension 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;
+    });
+    let extensionId;
+    let page;
+    try {
+        extensionId =
+            options.extensionId ??
+                (await discoverRealWalletExtensionId(context, {
+                    extensionName,
+                }));
+        const initialPage = options.initialPage === undefined ? extensionManifestDefaultPage(manifest) : options.initialPage;
+        page =
+            initialPage === false || initialPage === undefined
+                ? undefined
+                : await openRealWalletExtensionPage(context, extensionId, initialPage);
+    }
+    catch (error) {
+        await context.close().catch(() => undefined);
+        throw error;
+    }
+    return {
+        close: () => context.close(),
+        context,
+        extensionId,
+        extensionPath,
+        manifest,
+        page,
+        profile,
+        extensionUrl: (targetPage = '') => extensionPageUrl(extensionId, targetPage),
+        openPage: (targetPage = '') => openRealWalletExtensionPage(context, extensionId, targetPage),
+    };
+}
+//# sourceMappingURL=real-wallet-extension.js.map

package/dist/real-wallet-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-wallet-extension.js","sourceRoot":"","sources":["../src/real-wallet-extension.ts"],"names":[],"mappings":"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"}

package/dist/real-wallet-fixtures.d.ts

@@ -0,0 +1,52 @@
+import { type BuildWalletProfileOptions } from './real-wallet-cache.js';
+import { type RealWalletSession, type RealWalletSetup, type WalletGeneration } from './real-wallet.js';
+export type RealWalletFixtureOptions = {
+    /** Wallet setup. Defaults to WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE / _PASSWORD. */
+    setup?: RealWalletSetup;
+    /**
+     * Unpacked MetaMask directory. Defaults to
+     * WEB3_TESTER_REAL_WALLET_EXTENSION_PATH, or downloads the pinned release.
+     */
+    extensionPath?: string;
+    /** MetaMask version to download when extensionPath is not given. */
+    metamaskVersion?: string;
+    /**
+     * Explicit persistent profile directory. Disables the profile cache; the
+     * test reuses (and mutates) this profile directly, so parallel tests must
+     * not share it.
+     */
+    profileDir?: string;
+    baseURL?: string;
+    expectedAddress?: string;
+    /**
+     * MetaMask UI generation to drive ('12x' | '13x'). Defaults to the major
+     * version in the extension's manifest; set explicitly for custom builds.
+     */
+    generation?: WalletGeneration;
+    /**
+     * Run the browser headless. No default — choose explicitly here or via
+     * WEB3_TESTER_REAL_WALLET_HEADLESS=true|false. Headed is the fully
+     * validated mode.
+     */
+    headless?: boolean;
+    /**
+     * One-time profile customization baked into the cached profile (import
+     * keys, add accounts/networks/tokens) — Synpress defineWalletSetup-style.
+     * Ignored when an explicit profileDir bypasses the cache.
+     */
+    profileSetup?: BuildWalletProfileOptions['customize'];
+};
+export type RealWalletFixtures = {
+    realWalletOptions: RealWalletFixtureOptions;
+    realWallet: RealWalletSession;
+};
+/**
+ * Playwright fixtures for real-MetaMask tests. Each test gets a disposable
+ * clone of a cached, pre-onboarded profile (built once per seed phrase +
+ * extension version), so tests are isolated, parallel-safe, and skip
+ * onboarding cost after the first run. `context` and `page` are rebound to
+ * the persistent extension context.
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & RealWalletFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from './matchers.js';
+//# sourceMappingURL=real-wallet-fixtures.d.ts.map

package/dist/real-wallet-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-wallet-fixtures.d.ts","sourceRoot":"","sources":["../src/real-wallet-fixtures.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,wBAAwB,GAAG;IACrC,4FAA4F;IAC5F,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAC,WAAW,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C,UAAU,EAAE,iBAAiB,CAAC;CAC/B,CAAC;AAiBF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,kQAoFf,CAAC;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/real-wallet-fixtures.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { test as base } from '@playwright/test';
+import { prepareMetaMaskExtension } from './metamask-extension.js';
+import { buildWalletProfile, cloneWalletProfile, } from './real-wallet-cache.js';
+import { benchmarkForTest, benchmarkObjectMethods } from './benchmark.js';
+import { launchRealWallet, } from './real-wallet.js';
+const setupFromEnv = () => ({
+    password: process.env.WEB3_TESTER_REAL_WALLET_PASSWORD || undefined,
+    seedPhrase: process.env.WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE || undefined,
+});
+const assertChromiumProject = (browserName) => {
+    if (browserName !== 'chromium') {
+        throw new Error('@marigoldlabs/web3-tester/real-wallet-fixtures launch a Chromium extension context. ' +
+            `The current Playwright project uses "${browserName}". Exclude real-wallet tests from non-Chromium ` +
+            'projects, or run them in a dedicated Chromium project.');
+    }
+};
+/**
+ * Playwright fixtures for real-MetaMask tests. Each test gets a disposable
+ * clone of a cached, pre-onboarded profile (built once per seed phrase +
+ * extension version), so tests are isolated, parallel-safe, and skip
+ * onboarding cost after the first run. `context` and `page` are rebound to
+ * the persistent extension context.
+ */
+export const test = base.extend({
+    realWalletOptions: [
+        async ({}, use) => {
+            await use({});
+        },
+        { option: true },
+    ],
+    realWallet: async ({ realWalletOptions, browserName }, use, testInfo) => {
+        assertChromiumProject(browserName);
+        const benchmark = benchmarkForTest(testInfo, { suite: 'real-wallet' });
+        let session;
+        try {
+            const options = realWalletOptions;
+            const setup = options.setup ?? setupFromEnv();
+            const extensionPath = options.extensionPath ??
+                process.env.WEB3_TESTER_REAL_WALLET_EXTENSION_PATH ??
+                (await benchmark.measure('realWallet.prepareMetaMaskExtension', () => prepareMetaMaskExtension({ version: options.metamaskVersion })));
+            let profileDir = options.profileDir ?? process.env.WEB3_TESTER_REAL_WALLET_PROFILE_DIR;
+            if (!profileDir) {
+                if (!setup.seedPhrase) {
+                    throw new Error('Real-wallet fixtures need a seed phrase (realWalletOptions.setup.seedPhrase or ' +
+                        'WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE) to build a cached profile, ' +
+                        'or an explicit profileDir pointing at a prepared MetaMask profile.');
+                }
+                const cachedProfile = await benchmark.measure('realWallet.buildWalletProfile', () => buildWalletProfile({
+                    extensionPath,
+                    setup,
+                    headless: options.headless,
+                    generation: options.generation,
+                    customize: options.profileSetup,
+                }));
+                profileDir = await benchmark.measure('realWallet.cloneWalletProfile', () => cloneWalletProfile(cachedProfile, path.join(testInfo.outputDir, 'metamask-profile')));
+            }
+            session = await benchmark.measure('realWallet.launchRealWallet', () => launchRealWallet({
+                baseURL: options.baseURL,
+                expectedAddress: options.expectedAddress,
+                extensionPath,
+                generation: options.generation,
+                headless: options.headless,
+                profileDir,
+                setup,
+            }));
+            await use(benchmarkObjectMethods(session, benchmark, { prefix: 'realWallet', exclude: ['close'] }));
+        }
+        finally {
+            if (session) {
+                const activeSession = session;
+                await benchmark.measure('realWallet.close', () => activeSession.close().catch(() => undefined));
+            }
+            await benchmark.flush();
+        }
+    },
+    context: async ({ realWallet }, use) => {
+        await use(realWallet.context);
+    },
+    page: async ({ context }, use) => {
+        const page = await context.newPage();
+        await use(page);
+        await page.close().catch(() => undefined);
+    },
+});
+// The web3-extended expect: every matcher from ./matchers.js, zero migration.
+export { expect } from './matchers.js';
+//# sourceMappingURL=real-wallet-fixtures.js.map

package/dist/real-wallet-fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-wallet-fixtures.js","sourceRoot":"","sources":["../src/real-wallet-fixtures.ts"],"names":[],"mappings":"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"}

package/dist/real-wallet.d.ts

@@ -1,8 +1,15 @@
-import { type BrowserContext } from '@playwright/test';
-export type RealWalletProfile = {
-    profileDirectory?: string;
-    userDataDir: string;
-};
+import type { BrowserContext, Locator } from '@playwright/test';
+export { resolveRealWalletHeadless, resolveRealWalletProfile } from './real-wallet-extension.js';
+export type { RealWalletProfile } from './real-wallet-extension.js';
+/**
+ * MetaMask UI generation the selector surface drives. '13x' is the
+ * multichain UI (validated against 13.34.1, the pinned default); '12x' is
+ * the classic UI (last validated against 12.23.1). Both are first-class
+ * configuration: the generation is derived from the extension manifest at
+ * launch and selects which generation's selectors run — the other
+ * generation's selectors are not probed as fallbacks.
+ */
+export type WalletGeneration = '12x' | '13x';
 export type RealWalletSetup = {
     password?: string;
     seedPhrase?: string;
@@ -17,12 +24,49 @@ export type RealWalletLaunchOptions = {
     expectedAddress?: string;
     extensionName?: string;
     extensionPath: string;
+    /**
+     * UI generation to drive. Defaults to the major version in the extension's
+     * manifest (>= 13 → '13x'). Set explicitly for custom builds whose
+     * manifest version does not reflect their UI generation.
+     */
+    generation?: WalletGeneration;
+    /**
+     * Run the browser headless. There is deliberately no default — choose
+     * explicitly here or via WEB3_TESTER_REAL_WALLET_HEADLESS=true|false.
+     * Headed is the fully validated mode; headless loads the extension through
+     * the full Chromium build (channel 'chromium') and is validated for
+     * extension load + clipboard, but the full confirmation journey is not
+     * proven headless yet.
+     */
     headless?: boolean;
     profileDir: string;
     setup?: RealWalletSetup;
     slowMo?: number;
 };
+export type RealWalletNetwork = {
+    name: string;
+    rpcUrl: string;
+    chainId: number;
+    symbol: string;
+    blockExplorerUrl?: string;
+};
+export type RealWalletToken = {
+    /** ERC-20 contract address (0x + 40 hex). */
+    address: string;
+    /** Optional symbol override; MetaMask usually autofills from the contract. */
+    symbol?: string;
+    /** Optional decimals override. */
+    decimals?: number;
+    /**
+     * 13.x only: network to import the token on (name as shown in the import
+     * modal's network selector). Defaults to the wallet's active network.
+     */
+    networkName?: string;
+};
 export type RealWalletController = {
+    addNetwork(network: RealWalletNetwork): Promise<void>;
+    approveNewNetwork(): Promise<void>;
+    approveSwitchNetwork(): Promise<void>;
     approveTokenPermission(options?: {
         gasSetting?: RealWalletGasSettings;
         spendLimit?: 'max' | number;
@@ -33,27 +77,83 @@ export type RealWalletController = {
     }): Promise<void>;
     connectToDapp(accounts?: string[]): Promise<void>;
     getAccountAddress(): Promise<string>;
+    rejectNewNetwork(): Promise<void>;
     rejectSignature(): Promise<void>;
+    rejectSwitchNetwork(): Promise<void>;
+    rejectTokenPermission(): Promise<void>;
     rejectTransaction(): Promise<void>;
-};
-export type RealWalletSession = {
-    approveTokenPermission(options?: {
-        gasSetting?: RealWalletGasSettings;
-        spendLimit?: 'max' | number;
+    switchNetwork(name: string, options?: {
+        chainId?: number;
     }): Promise<void>;
-    close(): Promise<void>;
-    confirmSignature(): Promise<void>;
-    confirmTransaction(options?: {
+    /** Creates the next derived account on the active SRP, optionally named. */
+    addNewAccount(name?: string): Promise<void>;
+    /** Synpress-parity alias for approveAddToken(). */
+    addNewToken(): Promise<void>;
+    /** Approves a pending wallet_watchAsset ("Add suggested tokens") prompt. */
+    approveAddToken(): Promise<void>;
+    rejectAddToken(): Promise<void>;
+    /**
+     * confirmTransaction, then watch the newest activity row until confirmed.
+     * The hash is read best-effort via "Copy transaction ID" — undefined when
+     * the clipboard read fails (the mining wait still completes).
+     */
+    confirmTransactionAndWaitForMining(options?: {
         gasSetting?: RealWalletGasSettings;
-    }): Promise<void>;
-    connectToDapp(accounts?: string[]): Promise<void>;
+        /** Wait budget for the activity row to reach confirmed. Default 60_000. */
+        timeoutMs?: number;
+    }): Promise<{
+        txHash?: `0x${string}`;
+    }>;
+    /** Manual token import: tokens tab → Import tokens → Custom token form. */
+    importToken(token: RealWalletToken): Promise<void>;
+    /** Imports a private-key account ("Imported" keyring); throws on MetaMask errors (e.g. duplicates). */
+    importWalletFromPrivateKey(privateKey: string): Promise<void>;
+    /** Global menu → Lock; resolves once the unlock screen is visible. */
+    lock(): Promise<void>;
+    renameAccount(currentName: string, newName: string): Promise<void>;
+    /** Clears activity/nonce data (12.x: Advanced; 13.x: Developer tools). */
+    resetAccount(): Promise<void>;
+    /** Selects an account in the picker by display name or (best-effort on 13.x) address. */
+    switchAccount(nameOrAddress: string): Promise<void>;
+    /** Idempotent when `on` is given (reads the toggle first); blind toggle when omitted. */
+    toggleShowTestNetworks(on?: boolean): Promise<void>;
+    /** Unlocks with the given password or the password from launch setup. */
+    unlock(password?: string): Promise<void>;
+    /** Resolves once MetaMask is no longer showing the locked screen. */
+    waitForUnlocked(): Promise<void>;
+};
+export type RealWalletSession = RealWalletController & {
+    close(): Promise<void>;
     context: BrowserContext;
     extensionId: string;
-    getAccountAddress(): Promise<string>;
-    rejectSignature(): Promise<void>;
-    rejectTransaction(): Promise<void>;
     wallet: RealWalletController;
 };
-export declare function resolveRealWalletProfile(profileDir: string): RealWalletProfile;
+/**
+ * A selector-stack entry optionally scoped to one UI generation. Bare
+ * locators apply to both generations; tagged entries are dropped — not
+ * probed — when the wallet is configured for the other generation, so a
+ * wrong-generation selector can never burn its probe budget.
+ */
+type GenLocator = Locator | {
+    gen: WalletGeneration;
+    loc: Locator;
+};
+/**
+ * @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 declare function resolveGenLocators(locators: readonly GenLocator[], generation: WalletGeneration): Locator[];
+/** @internal Maps an extension manifest version to the UI generation it ships. */
+export declare function walletGenerationForVersion(version: string): WalletGeneration;
+/** @internal Validates and trims a 32-byte hex private key (0x optional). */
+export declare function normalizePrivateKey(privateKey: string): string;
+/** @internal */
+export declare function isFullTxHash(value: string | undefined): value is `0x${string}`;
+/**
+ * @internal Matches an account picker row by display name, or by full /
+ * shortened address when the identifier is an address.
+ */
+export declare function accountRowMatcher(identifier: string): RegExp;
 export declare function launchRealWallet(options: RealWalletLaunchOptions): Promise<RealWalletSession>;
 //# sourceMappingURL=real-wallet.d.ts.map

package/dist/real-wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-wallet.d.ts","sourceRoot":"","sources":["../src/real-wallet.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,cAAc,EAA2B,MAAM,kBAAkB,CAAC;AAG1F,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,KAAK,GACL,QAAQ,GACR,YAAY,GACZ;IACE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,sBAAsB,CAAC,OAAO,CAAC,EAAE;QAC/B,UAAU,CAAC,EAAE,qBAAqB,CAAC;QACnC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,qBAAqB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sBAAsB,CAAC,OAAO,CAAC,EAAE;QAC/B,UAAU,CAAC,EAAE,qBAAqB,CAAC;QACnC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,qBAAqB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;CAC9B,CAAC;AAgBF,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAW9E;AAq4BD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgDnG"}
+{"version":3,"file":"real-wallet.d.ts","sourceRoot":"","sources":["../src/real-wallet.ts"],"names":[],"mappings":"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"}