@walletwright/core 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @walletwright/core
 
+## 0.3.0
+
+### Minor Changes
+
+- fdb91d4: Fix a set of state-representation defects found by a repo-wide simplification audit.
+
+  **Caches now publish from staging.** Extension extraction and the onboarded profile build both wrote
+  in place, so an interrupted run (Ctrl-C, ENOSPC, a CI timeout, a flaky MV3 worker) could leave a
+  partial directory that still satisfied the "does it exist" check every later run made. That surfaced
+  much later as an unlock or selector timeout rather than as a build failure. Both now build inside the
+  cache and publish by rename. Profile replacement keeps the prior cache at a recovery path until the
+  new one lands, so a failed or interrupted publication can restore it.
+
+  **`launchWallet` no longer leaks its throwaway profile copy.** Cleanup was bound to the browser
+  context's `close` event, which does not exist yet if the profile copy or the launch itself fails, and
+  which nobody awaited. `launchWallet` now returns `close()` alongside `context` and `wallet`: it closes
+  the browser and then awaits removal of the copy. `context.close()` still triggers a best-effort
+  cleanup, so existing code keeps working, but `close()` is the documented path.
+
+  **Approval handling is more precise.** A popup respawned mid-approval is now positioned on screen like
+  the first one (it previously skipped that, and an off-screen window renders fine but refuses clicks).
+  The "did it close" check now tracks the exact page it drove instead of scanning the context for any
+  matching URL, which reported failure whenever a wallet chained a second popup or left a notification
+  window on its home screen. That check also now applies to `connectToDapp()`, which could previously
+  report success on a popup that never closed. MetaMask's `reject` gained the third-party-notice
+  dismissal and retry that `approve` already had, since the notice covers the whole footer.
+
+  **The `cache` CLI validates its flags.** It now uses `node:util`'s `parseArgs` in strict mode, so an
+  unknown flag, a flag missing its value, `--headless false` (which used to turn headless _on_), and
+  `--wallet=value` are all handled correctly instead of silently ignored or inverted. `--setup` combined
+  with a flag it would discard is now an error. Failures set `process.exitCode` rather than calling
+  `process.exit`, which could truncate the error message when stderr was piped.
+
+  **The mocks give each install its own bridge.** Installing `installMockWallet` or
+  `installMockStandardWallet` twice with different options used to discard the second handler while
+  returning its address, so the page signed with the first install's key on the first install's chain.
+
+  **Breaking (types only):** `WalletDefinition.reject` is now required. Every wallet in the registry
+  already declares it, and the public `Wallet` type has always promised rejection unconditionally, so
+  this only affects external code that annotates a `WalletDefinition` literal by hand. `isWalletKind` is
+  now exported.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -91,10 +91,10 @@ The same two calls drive every chain. A Phantom test can connect and sign on
 ```ts
 import { launchWallet } from "@walletwright/core";
 
-const { context, wallet } = await launchWallet(metamask);
+const { close, context, wallet } = await launchWallet(metamask);
 const page = await context.newPage();
 // drive the page and the wallet here
-await context.close();
+await close();
 ```
 
 ## Requirements and notes

package/dist/{cache-Bwv2i-hv.mjs → cache-CHP-6eU0.mjs}

@@ -1,4 +1,4 @@
-import { mkdir, readdir, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { chromium } from "@playwright/test";
 import { createHash } from "node:crypto";
@@ -14,10 +14,12 @@ const ZIP_SIGNATURE = Buffer.from([
 	4
 ]);
 /**
-* Download an extension archive and extract it to `<cacheDir>/<name>`, returning that path. A `.crx`
-* is a ZIP with a binary header, we slice from the ZIP signature before unzipping. Reuses an
-* existing extraction (so you can pre-place the extension to skip the download).
+* Prefix for in-progress extractions. It has to live inside `cacheDir` so publishing is a `rename`
+* on one filesystem (a cross-device rename fails with EXDEV), and it starts with a dot so it can
+* never collide with a wallet's `name`.
 */
+const STAGING_PREFIX = ".staging-";
+/** Download and validate an extension archive, then publish its extraction atomically from staging. */
 const downloadAndExtractExtension = async (options) => {
 	const { cacheDir, kind, name, sha256, url } = options;
 	const cacheRoot = path.resolve(cacheDir);
@@ -38,19 +40,28 @@ const downloadAndExtractExtension = async (options) => {
 		if (start === -1) throw new Error(`[walletwright] ${url} is not a valid CRX (no ZIP header found)`);
 		zipBytes = bytes.subarray(start);
 	}
-	await rm(outDir, {
-		force: true,
-		recursive: true
-	});
-	const zip = new AdmZip(zipBytes);
-	const root = path.resolve(outDir);
-	for (const entry of zip.getEntries()) {
-		const target = path.resolve(root, entry.entryName);
-		if (target !== root && !target.startsWith(root + path.sep)) throw new Error(`[walletwright] refusing to extract ${entry.entryName}: escapes ${outDir}`);
+	const staging = await mkdtemp(path.join(cacheRoot, STAGING_PREFIX));
+	try {
+		const zip = new AdmZip(zipBytes);
+		for (const entry of zip.getEntries()) {
+			const target = path.resolve(staging, entry.entryName);
+			if (target !== staging && !target.startsWith(staging + path.sep)) throw new Error(`[walletwright] refusing to extract ${entry.entryName}: escapes ${outDir}`);
+		}
+		zip.extractAllTo(staging, true);
+		if (!existsSync(path.join(staging, "manifest.json"))) throw new Error(`[walletwright] extracted ${name} but no manifest.json found in ${outDir}`);
+		if (existsSync(path.join(outDir, "manifest.json"))) return outDir;
+		await rm(outDir, {
+			force: true,
+			recursive: true
+		});
+		await rename(staging, outDir);
+		return outDir;
+	} finally {
+		await rm(staging, {
+			force: true,
+			recursive: true
+		}).catch(() => {});
 	}
-	zip.extractAllTo(outDir, true);
-	if (!existsSync(path.join(outDir, "manifest.json"))) throw new Error(`[walletwright] extracted ${name} but no manifest.json found in ${outDir}`);
-	return outDir;
 };
 /** Build the Chrome Web Store CRX download URL for an extension id. */
 const chromeWebStoreCrxUrl = (extensionId) => `https://clients2.google.com/service/update2/crx?response=redirect&prodversion=130.0&acceptformat=crx2,crx3&x=id%3D${extensionId}%26uc`;
@@ -101,7 +112,7 @@ const importPrivateKey = async ({ home }, privateKey) => {
 	});
 	await closeAccountMenu(home);
 };
-const rename = async ({ home }, options) => {
+const rename$1 = async ({ home }, options) => {
 	await openAccountMenu(home);
 	await home.getByTestId("multichain-account-cell-end-accessory").nth(options.index).click();
 	await home.getByTestId("multichain-account-menu-item-rename").click();
@@ -120,7 +131,7 @@ const switchTo = async ({ home }, index) => {
 const accounts = {
 	add: add$1,
 	importPrivateKey,
-	rename,
+	rename: rename$1,
 	switch: switchTo
 };
 
@@ -158,12 +169,7 @@ const sleep = (ms) => new Promise((resolve) => {
 });
 /** Render a timeout for an error message, so what a failure claims matches what it waited. */
 const formatTimeout = (ms) => `${Math.round(ms / 100) / 10}s`;
-/**
-* Poll `check` until it yields anything other than `undefined`/`false`, then hand that value back.
-* Returns `undefined` when the budget elapses, so only a caller that can genuinely continue without
-* the condition (an optional approval popup, say) branches on the result; everything else uses
-* `waitUntilOrThrow` and gets a named failure instead of a wallet that looks ready and isn't.
-*/
+/** Poll until `check` returns a value, or `undefined` when the timeout expires. */
 const waitUntil = async (check, { intervalMs = DEFAULT_INTERVAL_MS, timeoutMs }) => {
 	const deadline = Date.now() + timeoutMs;
 	for (;;) {
@@ -200,6 +206,12 @@ const RELOAD_SETTLE_TIMEOUT_MS = 5e3;
 const PROBE_INTERVAL_MS = 500;
 const PASSWORD_CLEARED_TIMEOUT_MS = 15e3;
 /**
+* Short on purpose. `unlock` is normally handed a page `reachUnlockScreen` already settled, so this
+* budget only matters when it is called on its own (the `settings.unlock` path), where a wallet with a
+* late-mounting UI needs a poll rather than a single read but a dead page should still fail fast.
+*/
+const UNLOCK_SETTLE_TIMEOUT_MS = 5e3;
+/**
 * The shared unlock flow: open the wallet's own page, wait for it to settle into a state we can
 * name, and type the password. Every wallet differs only in its entry page, how it submits, and
 * whether it can come back already unlocked.
@@ -228,11 +240,10 @@ const createUnlockScreen = ({ entry, isUnlocked, submit, wallet }) => {
 		return page;
 	};
 	const unlock = async (page, password) => {
+		const state = await settleWithin(page, UNLOCK_SETTLE_TIMEOUT_MS);
+		if (state === "unlocked") return;
+		if (state === void 0) throw new Error(`[walletwright] ${wallet} showed neither an unlock screen nor an unlocked wallet`);
 		const field = page.locator(PASSWORD_FIELD);
-		if (!await field.isVisible().catch(() => false)) {
-			if (await isUnlocked?.(page).catch(() => false) === true) return;
-			throw new Error(`[walletwright] ${wallet} showed neither an unlock screen nor an unlocked wallet`);
-		}
 		await field.fill(password);
 		await (submit === void 0 ? field.press("Enter") : submit(page, field));
 		if (!await field.waitFor({
@@ -305,39 +316,24 @@ const settings = {
 const BUTTON_TIMEOUT_MS = 45e3;
 /** The retry only covers a notice that rendered late, so it does not need the full budget again. */
 const RETRY_TIMEOUT_MS = 1e4;
-/**
-* First-time requests that MetaMask routes through a protocol Snap (e.g. adding a custom chain)
-* open a "Third-party software notice" modal over the confirm footer, and every click is
-* intercepted until it is accepted. Its buttons carry no testids, only text, and Accept stays
-* disabled until the notice is scrolled to the bottom.
-*/
+/** Snap notices intercept footer clicks and disable Accept until their content is scrolled. */
 const acceptThirdPartyNotice = async (popup) => {
 	const modal = popup.locator(".snap-install-warning");
 	if (await modal.count().catch(() => 0) === 0) return;
 	await modal.locator("p").last().scrollIntoViewIfNeeded().catch(() => {});
 	await modal.getByRole("button", { name: "Accept" }).click({ timeout: 3e3 }).catch(() => {});
 };
-/**
-* Confirm buttons differ by request type: connect popups use `confirm-btn`, signature and
-* transaction popups use `confirm-footer-button`, older builds used `page-container-footer-next`,
-* and requests routed through a protocol Snap (e.g. Solana) use
-* `confirm-<type>-confirm-snap-footer-button`, matched by suffix so every snap confirmation type is
-* covered. A popup renders exactly one of these buttons; the `.or()` union resolves whichever one
-* is present by DOM order, not by the order it's written in below, so one locator covers every
-* popup.
-*/
+/** Resolve the confirm test id used by standard, legacy, and Snap request footers. */
 const confirmButton = (popup) => popup.getByTestId("confirm-btn").or(popup.getByTestId("confirm-footer-button")).or(popup.locator("[data-testid=\"page-container-footer-next\"]")).or(popup.locator("[data-testid$=\"-confirm-snap-footer-button\"]")).first();
 const cancelButton = (popup) => popup.getByTestId("cancel-btn").or(popup.getByTestId("confirm-footer-cancel-button")).or(popup.locator("[data-testid=\"page-container-footer-cancel\"]")).or(popup.locator("[data-testid$=\"-cancel-snap-footer-button\"]")).first();
+/** Distinguishes a pending request from MetaMask's requestless notification home screen. */
+const approvalControls = (popup) => confirmButton(popup).or(cancelButton(popup));
 /**
-* What "this page is showing a request" means for MetaMask, as opposed to its wallet home. The
-* distinction matters for the page walletwright opens itself: `notification.html` renders the home
-* screen (account header, Buy/Swap/Send, a news carousel) when nothing is pending, so buttons on
-* screen prove nothing. A CI run handed that home screen to `approve` and waited out the full click
-* budget against a confirm button that was never going to exist.
+* Click one of the popup's footer buttons. The third-party notice covers that whole footer, so both
+* confirm and cancel are intercepted while it is up, and both need the dismiss-then-retry: without it
+* a click times out against a button that is rendered and enabled, which reads as a stale selector.
 */
-const approvalControls = (popup) => confirmButton(popup).or(cancelButton(popup));
-const approve = async (popup) => {
-	const button = confirmButton(popup);
+const clickFooterButton = async (popup, button) => {
 	await acceptThirdPartyNotice(popup);
 	try {
 		await button.click({ timeout: BUTTON_TIMEOUT_MS });
@@ -348,10 +344,9 @@ const approve = async (popup) => {
 		});
 	}
 };
-/** The cancel counterparts of `approve`; same union-by-DOM-order resolution, not written order. */
-const reject = async (popup) => {
-	await cancelButton(popup).click({ timeout: BUTTON_TIMEOUT_MS });
-};
+const approve = (popup) => clickFooterButton(popup, confirmButton(popup));
+/** The cancel counterpart of `approve`; same union-by-DOM-order resolution, not written order. */
+const reject = (popup) => clickFooterButton(popup, cancelButton(popup));
 
 //#endregion
 //#region src/internal/utils.ts
@@ -360,15 +355,7 @@ const DEFAULT_CACHE_DIR = ".walletwright";
 const DEFAULT_NOTIFICATION_MATCH = "notification.html";
 /** Stable per-setup profile directory name, so the same wallet+seed+password reuses one cache. */
 const profileKey = (setup) => createHash("sha256").update(`${setup.wallet}:${setup.version ?? "default"}:${setup.seedPhrase}:${setup.password}`).digest("hex").slice(0, 20);
-/**
-* Compute an extension's id without querying the browser (`chrome://extensions` is blocked headless,
-* and the service worker starts lazily). Chrome derives the id from the sha256 of either the
-* manifest's public `key` (if present, e.g. Phantom → its fixed Web Store id) or the absolute load
-* path (no key, e.g. MetaMask), taking the first 16 bytes and mapping each nibble 0-f → a-p.
-*
-* The path is resolved through symlinks (`realpathSync`) because Chrome hashes the *real* path, a
-* cache under a symlinked dir (e.g. macOS `/tmp` → `/private/tmp`) would otherwise yield a wrong id.
-*/
+/** Mirror Chrome's extension-id derivation; resolve symlinks because Chrome hashes the real path. */
 const extensionIdFromPath = (extensionPath) => {
 	const resolved = path.resolve(extensionPath);
 	const abs = (() => {
@@ -414,14 +401,7 @@ const APPROVAL_WINDOW = {
 };
 /** Far enough from the edge that a popup this size lands fully on any usable display. */
 const APPROVAL_WINDOW_OFFSET = 50;
-/**
-* Put a wallet-spawned approval window somewhere it can be clicked. It can open partly off-screen
-* on a small or virtual display, and Playwright will not click what is out of view, so a confirm
-* button that is rendered and enabled still times out. Synpress carries the same workaround.
-*
-* Best-effort throughout: headless has no window to move, and nothing here is required for a window
-* that already sits on screen.
-*/
+/** Move approval popups on-screen; headless and unsupported CDP targets are ignored. */
 const placeApprovalWindow = async (page) => {
 	await page.setViewportSize(APPROVAL_WINDOW).catch(() => {});
 	try {
@@ -440,7 +420,6 @@ const placeApprovalWindow = async (page) => {
 };
 /** Where Chrome persists an extension's `chrome.storage.local` inside a browser profile. */
 const extensionStateDir = (profileDir, extensionId) => path.join(profileDir, "Default", "Local Extension Settings", extensionId);
-const hasNotificationPopup = (context, extensionId, match = DEFAULT_NOTIFICATION_MATCH) => context.pages().some((page) => isApprovalPopup(page, extensionId, match));
 
 //#endregion
 //#region src/wallets/metamask/onboarding-patch.ts
@@ -451,18 +430,7 @@ const markOnboarded = (onboarding) => ({
 	firstTimeFlowType: typeof onboarding.firstTimeFlowType === "string" ? onboarding.firstTimeFlowType : "import",
 	onboardingTabs: {}
 });
-/**
-* Force `completedOnboarding=true` in MetaMask's persisted state so the cached wallet boots straight
-* to the unlock screen instead of getting stuck on the "wallet is ready" screen (whose "Open wallet"
-* action goes through the MV3 service worker and is unreliable under automation).
-*
-* MetaMask 13.13.x stored all state under a single `data` key; 13.3x stores each controller under its
-* own key (`OnboardingController`). Both are handled. Must run while the browser is closed.
-*
-* Every branch that can't find the state it means to patch throws: leaving the cache unpatched means
-* a wallet that boots to "wallet is ready" and ignores every dapp request, which is far harder to
-* diagnose from a spec than a failed cache build.
-*/
+/** Patch both MetaMask 13.x onboarding layouts while the browser has released LevelDB. */
 const markMetaMaskOnboarded = async (profileDir, extensionId) => {
 	const dbDir = extensionStateDir(profileDir, extensionId);
 	if (!existsSync(dbDir)) throw new Error(`[walletwright] MetaMask wrote no extension state to ${dbDir}`);
@@ -505,37 +473,24 @@ const markMetaMaskOnboarded = async (profileDir, extensionId) => {
 
 //#endregion
 //#region src/wallets/metamask.ts
-const DEFAULT_VERSION = "13.35.1";
+/** Release hashes for the pinned default. Add an entry before changing `DEFAULT_VERSION`. */
+const RELEASE_SHA256 = { "13.35.1": "4e0f8626df0ae9fb15f5f3ad6784a0b518f3ede067b2b0d4f539f9f457c5049c" };
 /**
-* sha256 of each pinned `metamask-chrome-<version>.zip` release asset, so a pinned download is
-* verified rather than trusted. This is the one place to fill in when bumping `DEFAULT_VERSION`:
-*
-*   curl -sL https://github.com/MetaMask/metamask-extension/releases/download/v<v>/metamask-chrome-<v>.zip | shasum -a 256
-*
-* A version a caller pins through `setup.version` has no entry here and downloads unverified, and
-* the Web-Store wallets can't be pinned at all (that endpoint always serves the current version).
+* Typed as a key of `RELEASE_SHA256`, so bumping the default without adding its hash above is a
+* compile error. `download.ts` skips verification for an unpinned `sha256`, so the same bump would
+* otherwise silently downgrade every default MetaMask download to unverified.
 */
-const RELEASE_SHA256 = { "13.35.1": "4e0f8626df0ae9fb15f5f3ad6784a0b518f3ede067b2b0d4f539f9f457c5049c" };
+const DEFAULT_VERSION = "13.35.1";
+const releaseSha256 = (version) => Object.entries(RELEASE_SHA256).find(([pinned]) => pinned === version)?.[1];
 /** Download inputs for a MetaMask release, split out so the integrity wiring is unit-testable. */
 const metamaskDownload = (cacheDir, version) => ({
 	cacheDir,
 	kind: "zip",
 	name: `metamask-chrome-${version}`,
-	sha256: RELEASE_SHA256[version],
+	sha256: releaseSha256(version),
 	url: `https://github.com/MetaMask/metamask-extension/releases/download/v${version}/metamask-chrome-${version}.zip`
 });
-/**
-* MetaMask's backup-and-sync restores account names for whichever SRP a profile holds, and test
-* seeds are shared (the public `test test … junk` one by thousands), so a synced profile reports a
-* stranger's account names in place of the ones a test just set: CI runs showed accounts called
-* `dev1` and `personal`, holding a real balance, where `Account 2` was expected. It only happens
-* where the sync actually lands, which makes it look like a flake. MetaMask's own e2e suite mocks
-* its external services for the same reason.
-*
-* Just the one host that stores the names. Cutting the auth stack around it (`authentication`,
-* `oidc`) reaches further than intended: other features authenticate through it too, and a wallet
-* that cannot authenticate can leave a request's confirm button disabled with nothing to explain it.
-*/
+/** MetaMask's account-name sync mutates shared test-seed profiles, so its own e2e suite blocks this host. */
 const ACCOUNT_SYNC_HOST = "user-storage.api.cx.metamask.io";
 const metamask = {
 	actions: {
@@ -696,34 +651,23 @@ const CONFIRM_LABELS = [
 	"Confirm"
 ];
 const CANCEL_LABELS = ["Cancel", "Reject"];
-/**
-* Rabby's approval window is focus-fragile: it unmounts its contents a few seconds after losing
-* focus, and Playwright's click (which waits for actionability, then for the click to settle) loses
-* the window mid-action. Rabby reads the vanished window as a dismissal, so the dapp gets
-* "User rejected the request" even though the confirm button was visible and enabled. Dispatching
-* the click inside the page skips focus, actionability, and post-click bookkeeping entirely. Rabby
-* is a plain React app, so `evaluate` works here (unlike MetaMask, which scuttles the realm).
-*
-* Signing is a two-step footer: "Sign" swaps itself for "Confirm", which must be clicked too, and
-* both start disabled while Rabby analyses the request. So keep clicking whichever labelled button
-* is currently enabled until the window closes, which is the only signal the request was answered.
-*/
+/** Rabby's focus-fragile popup requires in-page clicks; signing then requires a second Confirm click. */
 const clickApprovalButton = async (popup, labels) => {
-	let lastClicked = "";
+	const clickedLabels = /* @__PURE__ */ new Set();
 	return await waitUntil(async () => {
 		if (popup.isClosed()) return true;
 		const clicked = await popup.evaluate((arg) => {
 			const target = [...document.querySelectorAll("button")].find((button) => {
 				const text = (button.textContent ?? "").trim();
-				return arg.names.includes(text) && !button.disabled && text !== arg.skip;
+				return arg.names.includes(text) && !button.disabled && !arg.skip.includes(text);
 			});
 			target?.click();
 			return target ? (target.textContent ?? "").trim() : "";
 		}, {
 			names: [...labels],
-			skip: lastClicked
+			skip: [...clickedLabels]
 		}).catch(() => "");
-		if (clicked) lastClicked = clicked;
+		if (clicked) clickedLabels.add(clicked);
 	}, {
 		intervalMs: 300,
 		timeoutMs: APPROVAL_TIMEOUT_MS
@@ -796,7 +740,7 @@ const slush = {
 		await fclick(page, "Import existing from passphrase");
 		await sleep(1500);
 		const words = seedPhrase.trim().split(new RegExp("\\s+", "v"));
-		for (let i = 0; i < words.length; i++) await page.locator(`input[placeholder="Word ${i + 1}"]`).fill(words[i] ?? "");
+		for (let i = 0; i < words.length; i++) await page.getByLabel(`Word ${i + 1}`, { exact: true }).fill(words[i] ?? "");
 		await page.getByRole("button", { name: "Next" }).click();
 		await sleep(2e3);
 		await page.locator("input[placeholder=\"Password\"]").fill(password);
@@ -913,36 +857,82 @@ const extensionContextOptions = (extensionPath, headless) => ({
 const NAVIGATION_TIMEOUT_MS = 15e3;
 const FLUSH_SETTLE_MS = 3e3;
 const STATE_WRITE_TIMEOUT_MS = 1e4;
-/**
-* Chrome stores an extension's `chrome.storage.local` under `Local Extension Settings/<id>` and its
-* IndexedDB (what some single-page wallets persist their vault to) under
-* `IndexedDB/chrome-extension_<id>_0…`. Bytes in either one mean onboarding actually landed in the
-* profile; bytes in neither mean the "cache" is empty, and every later run would fail at unlock with
-* no hint that the build was the thing that went wrong.
-*/
+/** Wallet state may live in `chrome.storage.local` or extension IndexedDB. */
 const hasPersistedState = async (profileDir, extensionId) => {
 	const stores = [extensionStateDir(profileDir, extensionId), path.join(profileDir, "Default", "IndexedDB", `chrome-extension_${extensionId}_0.indexeddb.leveldb`)];
 	return (await Promise.allSettled(stores.map((dir) => readdir(dir)))).some((listing) => listing.status === "fulfilled" && listing.value.length > 0);
 };
 /**
-* Import the wallet once and persist an onboarded browser profile to disk (the "cache"), so tests
-* launch a ready-to-unlock wallet instead of re-running onboarding each time. Returns the profile
-* directory. Idempotent per (wallet, version, seed, password).
-*
-* `headless` only affects this build step; the tests choose their own mode via `launchWallet`.
+* Prefix for an in-progress build. Inside `cacheDir` so publishing is a `rename` on one filesystem,
+* dot-prefixed so it can never be mistaken for a 20-hex-character `profileKey`.
 */
+const BUILD_PREFIX = ".building-";
+const PREVIOUS_SUFFIX = ".previous";
+const isErrorCode = (error, code) => error instanceof Error && "code" in error && error.code === code;
+const pathExists = async (target) => {
+	try {
+		await stat(target);
+		return true;
+	} catch (error) {
+		if (isErrorCode(error, "ENOENT")) return false;
+		throw error;
+	}
+};
+const previousProfileDir = (profileDir) => `${profileDir}${PREVIOUS_SUFFIX}`;
+const restorePreviousProfile = async (profileDir) => {
+	const previous = previousProfileDir(profileDir);
+	if (await pathExists(profileDir)) {
+		await rm(previous, {
+			force: true,
+			recursive: true
+		});
+		return;
+	}
+	try {
+		await rename(previous, profileDir);
+	} catch (error) {
+		if (!isErrorCode(error, "ENOENT")) throw error;
+	}
+};
+const publishProfile = async (staging, profileDir) => {
+	await restorePreviousProfile(profileDir);
+	const previous = previousProfileDir(profileDir);
+	let movedPrevious = false;
+	try {
+		await rename(profileDir, previous);
+		movedPrevious = true;
+	} catch (error) {
+		if (!isErrorCode(error, "ENOENT")) throw error;
+	}
+	try {
+		await rename(staging, profileDir);
+	} catch (error) {
+		if (movedPrevious) try {
+			await rename(previous, profileDir);
+		} catch (rollbackError) {
+			const publishMessage = error instanceof Error ? error.message : String(error);
+			const rollbackMessage = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+			throw new Error(`[walletwright] failed to publish cache at ${profileDir}: ${publishMessage}; rollback failed: ${rollbackMessage}`, { cause: rollbackError });
+		}
+		throw error;
+	}
+	if (movedPrevious) await rm(previous, {
+		force: true,
+		recursive: true
+	});
+};
+/** Build in staging and retain the prior cache until the new profile publishes successfully. */
 const buildCache = async (setup, options = {}) => {
 	const definition = wallets[setup.wallet];
 	const cacheDir = path.resolve(setup.cacheDir ?? ".walletwright");
 	const extensionPath = await definition.prepareExtension(cacheDir, setup.version);
 	const profileDir = path.join(cacheDir, profileKey(setup));
-	await rm(profileDir, {
-		force: true,
-		recursive: true
-	});
-	await mkdir(profileDir, { recursive: true });
-	const context = await chromium.launchPersistentContext(profileDir, extensionContextOptions(extensionPath, options.headless === true));
+	await restorePreviousProfile(profileDir);
+	await mkdir(cacheDir, { recursive: true });
+	const staging = await mkdtemp(path.join(cacheDir, BUILD_PREFIX));
+	let context;
 	try {
+		context = await chromium.launchPersistentContext(staging, extensionContextOptions(extensionPath, options.headless === true));
 		await definition.prepareContext?.(context);
 		const extensionId = extensionIdFromPath(extensionPath);
 		const page = context.pages().find((candidate) => candidate.url() === "about:blank") ?? await context.newPage();
@@ -953,20 +943,26 @@ const buildCache = async (setup, options = {}) => {
 		await sleep(2e3);
 		await definition.importWallet(page, setup.seedPhrase, setup.password);
 		await sleep(FLUSH_SETTLE_MS);
-		await waitUntilOrThrow(() => hasPersistedState(profileDir, extensionId), {
+		await waitUntilOrThrow(() => hasPersistedState(staging, extensionId), {
 			intervalMs: 500,
-			message: `${definition.extensionName} onboarding wrote no wallet state into ${profileDir}`,
+			message: `${definition.extensionName} onboarding wrote no wallet state into ${staging}`,
 			timeoutMs: STATE_WRITE_TIMEOUT_MS
 		});
 		await context.close();
-		await definition.finalizeCache?.(profileDir, extensionId);
+		await definition.finalizeCache?.(staging, extensionId);
+		await publishProfile(staging, profileDir);
 		return profileDir;
 	} catch (error) {
-		await context.close().catch(() => {});
+		await context?.close().catch(() => {});
 		throw error;
+	} finally {
+		await rm(staging, {
+			force: true,
+			recursive: true
+		});
 	}
 };
 
 //#endregion
-export { wallets as a, extensionIdFromPath as c, placeApprovalWindow as d, profileKey as f, walletKindsByEcosystem as i, findNotificationPopup as l, waitUntil as m, extensionContextOptions as n, DEFAULT_CACHE_DIR as o, formatTimeout as p, isWalletKind as r, DEFAULT_NOTIFICATION_MATCH as s, buildCache as t, hasNotificationPopup as u };
-//# sourceMappingURL=cache-Bwv2i-hv.mjs.map
+export { walletKindsByEcosystem as a, DEFAULT_NOTIFICATION_MATCH as c, placeApprovalWindow as d, profileKey as f, isWalletKind as i, extensionIdFromPath as l, waitUntil as m, restorePreviousProfile as n, wallets as o, formatTimeout as p, extensionContextOptions as r, DEFAULT_CACHE_DIR as s, buildCache as t, findNotificationPopup as u };
+//# sourceMappingURL=cache-CHP-6eU0.mjs.map