@prosopo/procaptcha-frictionless 2.14.0 → 2.15.1

package/src/ProcaptchaFrictionless.tsx

@@ -42,6 +42,8 @@ import {
 	normaliseRetryCoords,
 } from "./sessionInvalidatedRecovery.js";
 
+const NO_SESSION_FOUND_KEY = "CAPTCHA.NO_SESSION_FOUND";
+
 // Each session uses exactly one solver — chosen by the /frictionless response.
 const ProcaptchaLoader = async () =>
 	(await import("@prosopo/procaptcha-react")).Procaptcha;
@@ -94,7 +96,7 @@ const defaultLoadingState = (
 	attemptCount: number,
 ): FrictionlessLoadingState => ({
 	loading: false,
-	attemptCount: attemptCount || 0,
+	attemptCount,
 });
 
 export const ProcaptchaFrictionless = ({
@@ -113,10 +115,22 @@ export const ProcaptchaFrictionless = ({
 	// to click the checkbox a second time and the checkbox click position is
 	// preserved in the eventual solution salt.
 	const pendingRetryCoordsRef = useRef<RetryCoords | null>(null);
-	// One-shot outer guard so a persistently broken session doesn't loop.
-	// After we've retried once, a second NO_SESSION_FOUND falls back to the
-	// inner widget's own `frictionlessState.restart()` path.
-	const sessionInvalidatedFiredRef = useRef(false);
+	// Bounded outer guard so a persistently broken session doesn't loop. Each
+	// re-mint costs a /frictionless round trip, so the count is capped — but
+	// it is a count rather than a one-shot, because a widget legitimately
+	// mints a new session every time the user presses reload. `onReload`
+	// clears it for the same reason. When the budget is spent we fall over
+	// visibly (see `onSessionInvalidated`) instead of leaving the user on a
+	// dead "No session found" checkbox.
+	const sessionInvalidatedAttemptsRef = useRef(0);
+	// Escalation sessions we have already mounted a widget for. The provider
+	// mints exactly one escalation session per PoW solution and consumes it on
+	// the first challenge fetch, so a repeat handoff for the same id can only
+	// produce a widget that 400s with NO_SESSION_FOUND. The PoW manager fires
+	// `onEscalate` from inside its `providerRetry`-wrapped `submit()`, so a
+	// throw anywhere after the handoff re-runs submit and escalates a second
+	// time on the same envelope.
+	const escalatedSessionIdsRef = useRef(new Set<string>());
 	// Bumped on every mount so the replacement widget gets a fresh React
 	// `key`. Without it a re-render for the same captcha type reconciles onto
 	// the existing element, and the inner widget keeps the manager it built on
@@ -161,9 +175,14 @@ export const ProcaptchaFrictionless = ({
 		),
 	);
 
+	// `??`, not `||`: every caller that wants the counter back at zero passes
+	// literal 0, and `0 || current` silently kept the old count. `start()` then
+	// tripped its own `attemptCount >= 5` fall-over after five *cumulative*
+	// runs in a widget lifetime — five reload presses were enough to strand the
+	// user on the error placeholder even though every one of them succeeded.
 	const resetState = (attemptCount?: number) => {
 		stateRef.current = defaultLoadingState(
-			attemptCount || stateRef.current.attemptCount,
+			attemptCount ?? stateRef.current.attemptCount,
 		);
 	};
 
@@ -212,6 +231,12 @@ export const ProcaptchaFrictionless = ({
 			newSessionId: string,
 			coords?: RetryCoords,
 		) => {
+			// Idempotent per escalation session — see `escalatedSessionIdsRef`.
+			// Without this a re-run of the PoW widget's `submit()` mounts a
+			// second widget against the session the first one already spent,
+			// which the provider answers with 400 CAPTCHA.NO_SESSION_FOUND.
+			if (escalatedSessionIdsRef.current.has(newSessionId)) return;
+			escalatedSessionIdsRef.current.add(newSessionId);
 			void renderForCaptchaType(
 				next,
 				{
@@ -225,23 +250,38 @@ export const ProcaptchaFrictionless = ({
 
 		// The provider returned NO_SESSION_FOUND on the inner widget's
 		// challenge fetch — the sessionId minted upstream is no longer usable
-		// (usually because a duplicate /captcha/{type} POST from a WebView
-		// mount storm consumed it first). Re-run the frictionless flow to
+		// (a duplicate /captcha/{type} POST consumed it first, or the widget
+		// re-sent an id it had already spent). Re-run the frictionless flow to
 		// mint a fresh session, then re-mount the inner widget with the
 		// preserved checkbox click coords so the user is not asked to click a
-		// second time. One-shot per outer widget lifetime — if the retry
-		// also fails, fall through to the inner widget's existing
-		// `frictionlessState.restart()` path.
+		// second time.
+		//
+		// The inner widget cannot recover on its own here: it always takes
+		// this branch and returns before its own `frictionlessState.restart()`
+		// fallback, and its guard ref is fresh on every re-mount. So whatever
+		// this handler declines to do, nothing else does — hence the terminal
+		// `fallOverWithStyle` rather than a silent return once the retry
+		// budget is spent.
 		const onSessionInvalidated = (x?: number, y?: number) => {
 			const { shouldRestart } = handleSessionInvalidated(
 				x,
 				y,
-				sessionInvalidatedFiredRef,
+				sessionInvalidatedAttemptsRef,
 				pendingRetryCoordsRef,
 			);
-			if (!shouldRestart) return;
-			resetState(0);
-			void start();
+			if (shouldRestart) {
+				resetState(0);
+				void start();
+				return;
+			}
+			// Budget spent. Surface the error on the checkbox and let
+			// `fallOverWithStyle`'s NO_SESSION_FOUND branch schedule the
+			// 10-second full restart, so the user always has a way back.
+			const message = i18n.isInitialized
+				? i18n.t(NO_SESSION_FOUND_KEY)
+				: "No session found";
+			events.onError(new Error(message));
+			fallOverWithStyle(message, NO_SESSION_FOUND_KEY);
 		};
 
 		// The user pressed reload on the challenge. The provider consumed this
@@ -253,6 +293,9 @@ export const ProcaptchaFrictionless = ({
 		const onReload = (x?: number, y?: number) => {
 			pendingRetryCoordsRef.current = normaliseRetryCoords(x, y);
 			nextMountAutoStartRef.current = true;
+			// A reload mints a genuinely new session, so the invalidation
+			// budget for the *previous* one shouldn't count against it.
+			sessionInvalidatedAttemptsRef.current = 0;
 			resetState(0);
 			void start();
 		};
@@ -287,6 +330,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 					onReload={onReload}
 				/>,
 			);
@@ -302,6 +346,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 				/>,
 			);
 		} else {
@@ -317,6 +362,7 @@ export const ProcaptchaFrictionless = ({
 					autoStart={resumedAutoStart}
 					startCoords={startCoords}
 					onSessionInvalidated={onSessionInvalidated}
+					container={container}
 				/>,
 			);
 		}

package/src/sessionInvalidatedRecovery.ts

@@ -49,23 +49,43 @@ export const normaliseRetryCoords = (
 };
 
 /**
- * Semantics of the outer recovery handler. Returns whether the caller
- * should proceed to re-run the frictionless flow (`start()`), and mutates
- * the passed refs to record the one-shot fire + pending coords.
+ * How many times a single outer widget will re-mint a session in response to
+ * `CAPTCHA.NO_SESSION_FOUND` on the inner widget before giving up and handing
+ * over to the terminal fallback.
  *
- * Second calls are ignored (one-shot per outer widget lifetime) so a
- * persistently broken session doesn't loop.
+ * This used to be one-shot per outer widget lifetime, which stranded users:
+ * the inner widget always takes the `onSessionInvalidated` branch (its own
+ * guard ref is fresh on every re-mount, because the outer widget bumps its
+ * mount key) and returns without touching its own `restart()` fallback. Once
+ * the outer one-shot was spent nothing at all handled the second failure, so
+ * the checkbox sat on "No session found" forever. A widget legitimately mints
+ * many sessions over its lifetime — every reload press is a new one — so a
+ * single lifetime-wide attempt is far too coarse a bound.
+ */
+export const MAX_SESSION_INVALIDATED_RETRIES = 3;
+
+/**
+ * Semantics of the outer recovery handler. Returns whether the caller should
+ * proceed to re-run the frictionless flow (`start()`), and mutates the passed
+ * refs to record the attempt + pending coords.
+ *
+ * Bounded rather than one-shot: a persistently broken session still stops
+ * looping, but the caller is told (`exhausted`) so it can fall back visibly
+ * instead of silently doing nothing.
  */
 export const handleSessionInvalidated = (
 	x: number | undefined,
 	y: number | undefined,
-	firedRef: MutableRef<boolean>,
+	attemptsRef: MutableRef<number>,
 	pendingCoordsRef: MutableRef<RetryCoords | null>,
-): { shouldRestart: boolean } => {
-	if (firedRef.current) return { shouldRestart: false };
-	firedRef.current = true;
+	maxAttempts: number = MAX_SESSION_INVALIDATED_RETRIES,
+): { shouldRestart: boolean; exhausted: boolean } => {
+	if (attemptsRef.current >= maxAttempts) {
+		return { shouldRestart: false, exhausted: true };
+	}
+	attemptsRef.current += 1;
 	pendingCoordsRef.current = normaliseRetryCoords(x, y);
-	return { shouldRestart: true };
+	return { shouldRestart: true, exhausted: false };
 };
 
 /**

package/src/tests/escalationHandoff.integration.test.tsx

@@ -0,0 +1,354 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Post-PoW escalation, end to end on the client: the real
+ * ProcaptchaFrictionless wrapper hands off to the real image widget and its
+ * real Manager. Only the network is stubbed, and the stub enforces the
+ * provider's actual contract — `checkAndRemoveSession` consumes a session the
+ * moment it issues a challenge, so a second `/captcha/image` on the same
+ * sessionId is answered with 400 CAPTCHA.NO_SESSION_FOUND.
+ *
+ * Observed in production on provider 3.8.5:
+ *
+ *   11:27:49.910  POST /pow/solution        200  escalation envelope returned
+ *   11:27:50.263  POST /captcha/image       200  escalation session issued
+ *   11:27:55.030  POST /captcha/image       400  CAPTCHA.NO_SESSION_FOUND, same session
+ *
+ * The PoW manager fires `onEscalate` from inside its `providerRetry`-wrapped
+ * `submit()`, so a throw after the handoff re-runs submit and escalates a
+ * second time on the same envelope.
+ */
+
+import type { Ti18n } from "@prosopo/locale";
+import {
+	type Account,
+	ApiParams,
+	type BotDetectionFunction,
+	type CaptchaResponseBody,
+	CaptchaType,
+	ModeEnum,
+	type ProcaptchaClientConfigInput,
+	type ProcaptchaProps,
+	type RandomProvider,
+} from "@prosopo/types";
+import { type ReactElement, act, createElement } from "react";
+import { type Root, createRoot } from "react-dom/client";
+import {
+	type Mock,
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+} from "vitest";
+
+declare global {
+	var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+const ESCALATION_SESSION_ID = "provider-session-escalated";
+const FIRST_SESSION_ID = "provider-session-1";
+
+// The provider's one-shot session contract, as a stub: the first challenge
+// fetch for a sessionId succeeds, every later one fails the way
+// `checkAndRemoveSession` makes it fail.
+const mocks = vi.hoisted(() => {
+	const challengeRequests: (string | undefined)[] = [];
+	const consumed = new Set<string>();
+
+	const body = (): CaptchaResponseBody => ({
+		captchas: [
+			{
+				captchaId: "captcha-id-1",
+				captchaContentId: "captcha-content-id-1",
+				datasetId: "dataset-id",
+				salt: "0xsalt",
+				target: "cars",
+				items: [],
+			},
+		],
+		requestHash: "0xrequest-hash",
+		timestamp: "1700000000000",
+		signature: { provider: { requestHash: "0xprovider-request-hash" } },
+		status: "ok",
+	});
+
+	const getCaptchaChallenge = async (
+		_userAccount: string,
+		_provider: unknown,
+		sessionId?: string,
+	): Promise<CaptchaResponseBody> => {
+		challengeRequests.push(sessionId);
+		if (sessionId && consumed.has(sessionId)) {
+			// A 400 carrying a JSON body is *returned*, not thrown —
+			// HttpClientBase only throws when the failure isn't JSON. This is
+			// the envelope the provider's ProsopoApiError serialises to, and
+			// `error.key` is what the widget's recovery path keys off.
+			return {
+				...body(),
+				captchas: [],
+				error: {
+					key: "CAPTCHA.NO_SESSION_FOUND",
+					message: "No session found",
+					code: 400,
+				},
+			};
+		}
+		if (sessionId) consumed.add(sessionId);
+		return body();
+	};
+
+	class ProviderApiMock {
+		public getCaptchaChallenge = getCaptchaChallenge;
+	}
+
+	return { challengeRequests, consumed, ProviderApiMock };
+});
+
+vi.mock("@prosopo/api", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("@prosopo/api")>();
+	return { ...actual, ProviderApi: mocks.ProviderApiMock };
+});
+
+// The image Manager constructs an extension before it can ask for a challenge
+// (it then reads the account off the frictionless state, and nothing in this
+// flow signs anything). `ExtensionLoader` resolves to the class, so the mock
+// has to as well.
+class ExtensionMock {
+	public getAccount = async (): Promise<Account> => ({
+		account: { address: "user-address" },
+	});
+}
+
+vi.mock("@prosopo/procaptcha-common", async (importOriginal) => {
+	const actual =
+		await importOriginal<typeof import("@prosopo/procaptcha-common")>();
+	return {
+		...actual,
+		isSecureBrowserContext: () => true,
+		ExtensionLoader: async (_web2: boolean) => ExtensionMock,
+	};
+});
+
+vi.mock("@prosopo/locale", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("@prosopo/locale")>();
+	return {
+		...actual,
+		useTranslation: () => ({ t: (key: string) => key, ready: true }),
+		loadI18next: async () => undefined,
+	};
+});
+
+// The PoW widget is the escalation *source*, so it stays a stub — the test
+// drives its `onEscalate` callback directly. The image widget below it is real.
+const powMounts: { props: ProcaptchaProps }[] = [];
+vi.mock("@prosopo/procaptcha-pow", () => ({
+	ProcaptchaPow: (props: ProcaptchaProps) => {
+		powMounts.push({ props });
+		return createElement("div", { "data-widget": "pow" });
+	},
+}));
+vi.mock("@prosopo/procaptcha-puzzle", () => ({
+	ProcaptchaPuzzle: () => createElement("div", { "data-widget": "puzzle" }),
+}));
+
+const { ProcaptchaFrictionless } = await import("../ProcaptchaFrictionless.js");
+
+const provider: RandomProvider = {
+	providerAccount: "provider-account",
+	provider: { url: "https://provider.test" },
+};
+
+const userAccount: Account = { account: { address: "user-address" } };
+
+const config = (): ProcaptchaClientConfigInput => ({
+	account: { address: "5siteKey" },
+	userAccountAddress: "",
+	web2: true,
+	mode: ModeEnum.visible,
+});
+
+const i18nStub = {
+	isInitialized: true,
+	language: "en",
+	t: (key: string) => key,
+	changeLanguage: vi.fn(),
+} as unknown as Ti18n;
+
+const detectBot: Mock<BotDetectionFunction> = vi.fn(async () => ({
+	captchaType: CaptchaType.pow,
+	sessionId: FIRST_SESSION_ID,
+	status: "ok",
+	provider,
+	userAccount,
+}));
+
+let container: HTMLDivElement;
+let root: Root;
+
+const lastPowMount = () => {
+	const mount = powMounts.at(-1);
+	if (!mount) throw new Error("expected the pow widget to have mounted");
+	return mount;
+};
+
+/**
+ * Flush React work until the challenge traffic has been quiet for four
+ * consecutive polls, so the negative assertions know nothing further is on its
+ * way. Paired with `waitForChallenge` below rather than used alone: starting
+ * from an already-quiet count, a pure quiescence check can declare "settled"
+ * before a request that is still coming has been issued.
+ */
+const settle = async (): Promise<void> => {
+	let quiet = 0;
+	let previous = mocks.challengeRequests.length;
+	for (let poll = 0; poll < 40 && quiet < 4; poll++) {
+		await act(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 60));
+		});
+		const current = mocks.challengeRequests.length;
+		quiet = current === previous ? quiet + 1 : 0;
+		previous = current;
+	}
+};
+
+const challengeRequestCount = (sessionId: string): number =>
+	mocks.challengeRequests.filter((id) => id === sessionId).length;
+
+/** Flush until the image Manager has issued its challenge fetch. */
+const waitForChallenge = async (sessionId: string): Promise<void> => {
+	for (
+		let poll = 0;
+		poll < 60 && challengeRequestCount(sessionId) === 0;
+		poll++
+	) {
+		await act(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		});
+	}
+};
+
+/**
+ * The PoW solution came back with an escalation envelope. `expectRequest`
+ * distinguishes a handoff that should reach the network from one the wrapper
+ * is expected to swallow — waiting for the request in the first case is what
+ * keeps a late fetch from leaking into the next assertion.
+ */
+const escalate = async (
+	sessionId: string,
+	expectRequest = true,
+): Promise<void> => {
+	const { onEscalate } = lastPowMount().props;
+	await act(async () => {
+		onEscalate?.(CaptchaType.image, sessionId, { x: 120, y: 340 });
+	});
+	if (expectRequest) await waitForChallenge(sessionId);
+	await settle();
+};
+
+beforeEach(async () => {
+	powMounts.length = 0;
+	mocks.challengeRequests.length = 0;
+	mocks.consumed.clear();
+	detectBot.mockClear();
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	act(() => {
+		root = createRoot(container);
+	});
+	await act(async () => {
+		root.render(
+			createElement(ProcaptchaFrictionless, {
+				config: config(),
+				callbacks: {},
+				restart: vi.fn<() => void>(),
+				i18n: i18nStub,
+				detectBot,
+			}) as ReactElement,
+		);
+	});
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+	container.remove();
+	vi.clearAllMocks();
+});
+
+describe("post-PoW escalation handoff", () => {
+	it("fetches the image challenge exactly once for the escalation session", async () => {
+		await escalate(ESCALATION_SESSION_ID);
+
+		expect(challengeRequestCount(ESCALATION_SESSION_ID)).toBe(1);
+	});
+
+	it("does not re-request the challenge when the same escalation fires twice", async () => {
+		// The PoW manager escalates from inside providerRetry, so a retried
+		// submit() replays the same envelope. Before the guard this mounted a
+		// second image widget against a session the first one had already
+		// spent, and the provider answered 400 CAPTCHA.NO_SESSION_FOUND.
+		await escalate(ESCALATION_SESSION_ID);
+		await escalate(ESCALATION_SESSION_ID, false);
+
+		expect(challengeRequestCount(ESCALATION_SESSION_ID)).toBe(1);
+	});
+
+	it("still follows a genuinely new escalation session", async () => {
+		await escalate(ESCALATION_SESSION_ID);
+		await escalate("provider-session-escalated-2");
+
+		expect(challengeRequestCount(ESCALATION_SESSION_ID)).toBe(1);
+		expect(challengeRequestCount("provider-session-escalated-2")).toBe(1);
+	});
+
+	it("recovers rather than stranding the user when the escalation session is already gone", async () => {
+		// Something else consumed the escalation session first (a duplicate
+		// POST from a mount storm). The wrapper must re-mint via /frictionless
+		// rather than leaving a dead "No session found" checkbox.
+		mocks.consumed.add(ESCALATION_SESSION_ID);
+		const detectBotCallsBefore = detectBot.mock.calls.length;
+
+		await escalate(ESCALATION_SESSION_ID);
+
+		expect(challengeRequestCount(ESCALATION_SESSION_ID)).toBe(1);
+		expect(detectBot.mock.calls.length).toBeGreaterThan(detectBotCallsBefore);
+	});
+});
+
+describe("the one-shot session contract this suite stubs", () => {
+	it("issues a challenge on the first fetch", async () => {
+		const api = new mocks.ProviderApiMock();
+
+		const challenge = await api.getCaptchaChallenge("user", provider, "fresh");
+
+		expect(challenge[ApiParams.captchas]).toHaveLength(1);
+		expect(challenge[ApiParams.error]).toBeUndefined();
+	});
+
+	it("matches the provider on a second fetch: NO_SESSION_FOUND in the body, not a throw", async () => {
+		const api = new mocks.ProviderApiMock();
+		await api.getCaptchaChallenge("user", provider, "session-x");
+
+		const repeat = await api.getCaptchaChallenge("user", provider, "session-x");
+
+		expect(repeat[ApiParams.error]?.key).toBe("CAPTCHA.NO_SESSION_FOUND");
+		expect(repeat[ApiParams.captchas]).toHaveLength(0);
+	});
+});

package/src/tests/sessionInvalidatedRecovery.test.ts

@@ -14,6 +14,7 @@
 
 import { describe, expect, it } from "vitest";
 import {
+	MAX_SESSION_INVALIDATED_RETRIES,
 	type MutableRef,
 	type RetryCoords,
 	consumeRetryMountProps,
@@ -25,70 +26,97 @@ const ref = <T>(initial: T): MutableRef<T> => ({ current: initial });
 
 describe("handleSessionInvalidated", () => {
 	it("records both coords and signals a restart on the first fire", () => {
-		const firedRef = ref(false);
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
-		const result = handleSessionInvalidated(120, 340, firedRef, coordsRef);
+		const result = handleSessionInvalidated(120, 340, attemptsRef, coordsRef);
 
-		expect(result).toEqual({ shouldRestart: true });
-		expect(firedRef.current).toBe(true);
+		expect(result).toEqual({ shouldRestart: true, exhausted: false });
+		expect(attemptsRef.current).toBe(1);
 		expect(coordsRef.current).toEqual({ x: 120, y: 340 });
 	});
 
 	it("treats (0, 0) as 'no coords' — that's the autoStart / untrusted-event default, not a real click", () => {
-		const firedRef = ref(false);
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
-		const result = handleSessionInvalidated(0, 0, firedRef, coordsRef);
+		const result = handleSessionInvalidated(0, 0, attemptsRef, coordsRef);
 
-		expect(result).toEqual({ shouldRestart: true });
+		expect(result).toEqual({ shouldRestart: true, exhausted: false });
 		expect(coordsRef.current).toBeNull();
 	});
 
 	it("carries a real click even if only one axis is at the origin", () => {
-		const firedRef = ref(false);
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
-		handleSessionInvalidated(0, 340, firedRef, coordsRef);
+		handleSessionInvalidated(0, 340, attemptsRef, coordsRef);
 
 		expect(coordsRef.current).toEqual({ x: 0, y: 340 });
 	});
 
 	it("stores no coords when x or y is undefined (autoStart / non-trusted event)", () => {
-		const firedRef = ref(false);
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
 		const result = handleSessionInvalidated(
 			undefined,
 			undefined,
-			firedRef,
+			attemptsRef,
 			coordsRef,
 		);
 
-		expect(result).toEqual({ shouldRestart: true });
-		expect(firedRef.current).toBe(true);
+		expect(result).toEqual({ shouldRestart: true, exhausted: false });
+		expect(attemptsRef.current).toBe(1);
 		expect(coordsRef.current).toBeNull();
 	});
 
 	it("stores no coords when only one axis is present — never emit NaN into the salt", () => {
-		const firedRef = ref(false);
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
-		handleSessionInvalidated(120, undefined, firedRef, coordsRef);
+		handleSessionInvalidated(120, undefined, attemptsRef, coordsRef);
 
 		expect(coordsRef.current).toBeNull();
 	});
 
-	it("is one-shot per outer widget lifetime — a second call is a no-op", () => {
-		const firedRef = ref(false);
+	it("keeps re-minting up to the retry budget — a reload press is a legitimate new session", () => {
+		const attemptsRef = ref(0);
 		const coordsRef = ref<RetryCoords | null>(null);
 
-		handleSessionInvalidated(100, 200, firedRef, coordsRef);
-		const second = handleSessionInvalidated(500, 600, firedRef, coordsRef);
+		for (let i = 0; i < MAX_SESSION_INVALIDATED_RETRIES; i++) {
+			expect(
+				handleSessionInvalidated(100 + i, 200 + i, attemptsRef, coordsRef),
+			).toEqual({ shouldRestart: true, exhausted: false });
+		}
 
-		expect(second).toEqual({ shouldRestart: false });
-		// The second call must not overwrite the first attempt's coords.
+		expect(attemptsRef.current).toBe(MAX_SESSION_INVALIDATED_RETRIES);
+	});
+
+	it("reports exhausted once the budget is spent so the caller can fall over visibly", () => {
+		const attemptsRef = ref(MAX_SESSION_INVALIDATED_RETRIES);
+		const coordsRef = ref<RetryCoords | null>({ x: 100, y: 200 });
+
+		const result = handleSessionInvalidated(500, 600, attemptsRef, coordsRef);
+
+		expect(result).toEqual({ shouldRestart: false, exhausted: true });
+		// An exhausted call must not overwrite the pending attempt's coords.
 		expect(coordsRef.current).toEqual({ x: 100, y: 200 });
+		expect(attemptsRef.current).toBe(MAX_SESSION_INVALIDATED_RETRIES);
+	});
+
+	it("honours a caller-supplied budget", () => {
+		const attemptsRef = ref(0);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		expect(handleSessionInvalidated(1, 2, attemptsRef, coordsRef, 1)).toEqual({
+			shouldRestart: true,
+			exhausted: false,
+		});
+		expect(handleSessionInvalidated(3, 4, attemptsRef, coordsRef, 1)).toEqual({
+			shouldRestart: false,
+			exhausted: true,
+		});
 	});
 });