@prosopo/procaptcha-bundle 4.1.48 → 4.1.50

package/dist/tests/reset.unit.test.js

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const mocks = vi.hoisted(() => ({
+    prefetchDetector: vi.fn(),
+    createWidgets: vi.fn(),
+}));
+vi.mock("@prosopo/procaptcha-frictionless", () => ({
+    prefetchDetector: mocks.prefetchDetector,
+}));
+vi.mock("@prosopo/procaptcha-common", () => ({
+    getWindowCallback: vi.fn(),
+    pickIpMode: vi.fn(() => undefined),
+}));
+vi.mock("../util/widgetFactory.js", () => ({
+    WidgetFactory: vi.fn(function () {
+        return { createWidgets: mocks.createWidgets };
+    }),
+}));
+const { render, reset, remove } = await import("../index.js");
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+const makeRoot = () => ({ unmount: vi.fn(), render: vi.fn() });
+const queueRoots = (...roots) => {
+    for (const root of roots) {
+        mocks.createWidgets.mockResolvedValueOnce([root]);
+    }
+};
+beforeEach(async () => {
+    vi.clearAllMocks();
+    await remove();
+    mocks.createWidgets.mockResolvedValue([makeRoot()]);
+});
+describe("render", () => {
+    it("returns a widget id", async () => {
+        queueRoots(makeRoot());
+        const widgetId = await render(document.createElement("div"), {
+            siteKey: SITE_KEY,
+        });
+        expect(typeof widgetId).toBe("string");
+        expect(widgetId).toBeTruthy();
+    });
+    it("returns undefined when the factory creates no widget", async () => {
+        mocks.createWidgets.mockResolvedValueOnce([]);
+        const widgetId = await render(document.createElement("div"), {
+            siteKey: SITE_KEY,
+        });
+        expect(widgetId).toBeUndefined();
+    });
+});
+describe("reset", () => {
+    it("unmounts the old root and mounts a replacement", async () => {
+        const first = makeRoot();
+        const second = makeRoot();
+        queueRoots(first, second);
+        const element = document.createElement("div");
+        await render(element, { siteKey: SITE_KEY });
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+        await reset();
+        expect(first.unmount).toHaveBeenCalledTimes(1);
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(2);
+        expect(mocks.createWidgets).toHaveBeenLastCalledWith([element], expect.objectContaining({ siteKey: SITE_KEY }), true, false);
+        expect(second.unmount).not.toHaveBeenCalled();
+    });
+    it("resets only the widget whose id is given", async () => {
+        const firstA = makeRoot();
+        const firstB = makeRoot();
+        const replacementA = makeRoot();
+        queueRoots(firstA, firstB, replacementA);
+        const elementA = document.createElement("div");
+        const elementB = document.createElement("div");
+        const idA = await render(elementA, { siteKey: SITE_KEY });
+        await render(elementB, { siteKey: SITE_KEY });
+        await reset(idA);
+        expect(firstA.unmount).toHaveBeenCalledTimes(1);
+        expect(firstB.unmount).not.toHaveBeenCalled();
+        expect(mocks.createWidgets).toHaveBeenLastCalledWith([elementA], expect.anything(), true, false);
+    });
+    it("keeps the widget resettable more than once", async () => {
+        const roots = [makeRoot(), makeRoot(), makeRoot()];
+        queueRoots(...roots);
+        await render(document.createElement("div"), { siteKey: SITE_KEY });
+        await reset();
+        await reset();
+        expect(roots[0]?.unmount).toHaveBeenCalledTimes(1);
+        expect(roots[1]?.unmount).toHaveBeenCalledTimes(1);
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(3);
+    });
+    it("preserves the invisible flag when rebuilding", async () => {
+        queueRoots(makeRoot(), makeRoot());
+        const button = document.createElement("button");
+        await render(button, { siteKey: SITE_KEY });
+        await reset();
+        expect(mocks.createWidgets).toHaveBeenLastCalledWith([button], expect.anything(), true, true);
+    });
+    it("does nothing for an unknown widget id", async () => {
+        queueRoots(makeRoot());
+        await render(document.createElement("div"), { siteKey: SITE_KEY });
+        await reset("procaptcha-widget-does-not-exist");
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+    });
+});
+describe("remove", () => {
+    it("unmounts without mounting a replacement", async () => {
+        const root = makeRoot();
+        queueRoots(root);
+        const element = document.createElement("div");
+        element.innerHTML = "<span>skeleton</span>";
+        await render(element, { siteKey: SITE_KEY });
+        await remove();
+        expect(root.unmount).toHaveBeenCalledTimes(1);
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+        expect(element.innerHTML).toBe("");
+    });
+    it("makes a subsequent reset a no-op", async () => {
+        queueRoots(makeRoot());
+        await render(document.createElement("div"), { siteKey: SITE_KEY });
+        await remove();
+        await reset();
+        expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=reset.unit.test.js.map

package/dist/tests/reset.unit.test.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/procaptcha-bundle",
-	"version": "4.1.48",
+	"version": "4.1.50",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"main": "dist/index.js",
@@ -39,13 +39,13 @@
 	},
 	"browserslist": ["> 0.5%, last 2 versions, not dead"],
 	"dependencies": {
-		"@prosopo/dotenv": "3.0.51",
-		"@prosopo/locale": "3.2.9",
-		"@prosopo/procaptcha-common": "2.11.22",
-		"@prosopo/procaptcha-frictionless": "2.13.4",
-		"@prosopo/types": "5.0.2",
-		"@prosopo/util": "3.3.5",
-		"@prosopo/widget-skeleton": "2.8.5",
+		"@prosopo/dotenv": "3.0.52",
+		"@prosopo/locale": "3.3.0",
+		"@prosopo/procaptcha-common": "2.11.24",
+		"@prosopo/procaptcha-frictionless": "2.13.6",
+		"@prosopo/types": "5.0.4",
+		"@prosopo/util": "3.3.6",
+		"@prosopo/widget-skeleton": "2.8.6",
 		"dotenv": "16.4.5",
 		"fast-glob": "3.3.2",
 		"jsdom": "25.0.0",
@@ -68,7 +68,7 @@
 		"registry": "https://registry.npmjs.org"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.7",
+		"@prosopo/config": "3.3.8",
 		"@types/jsdom": "21.1.7",
 		"@types/node": "22.10.2",
 		"@types/react": "18.3.1",

package/src/index.ts

@@ -21,7 +21,49 @@ import { WidgetFactory } from "./util/widgetFactory.js";
 import { WidgetThemeResolver } from "./util/widgetThemeResolver.js";
 
 const BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
-let procaptchaRoots: Root[] = [];
+
+/**
+ * Everything needed to rebuild a widget in place.
+ *
+ * Previously only the React `Root` was retained, which made `reset()` a
+ * one-way operation: unmounting tore out the React tree but the widget
+ * skeleton (created imperatively by `createWidgetSkeleton`, not by React)
+ * stayed in the DOM, leaving a container with a logo and no checkbox. There
+ * was no record of which element or render options produced it, so nothing
+ * could put it back. Keeping the descriptor alongside the root is what lets
+ * `reset()` remount rather than just destroy.
+ */
+interface WidgetEntry {
+	root: Root;
+	element: Element;
+	renderOptions: ProcaptchaRenderOptions;
+	isWeb2: boolean;
+	invisible: boolean;
+}
+
+const procaptchaWidgets = new Map<string, WidgetEntry>();
+
+let widgetIdCounter = 0;
+const nextWidgetId = (): string => `procaptcha-widget-${widgetIdCounter++}`;
+
+const registerWidgets = (
+	roots: Root[],
+	elements: Element[],
+	renderOptions: ProcaptchaRenderOptions,
+	isWeb2: boolean,
+	invisible: boolean,
+): string[] =>
+	roots.map((root, index) => {
+		const id = nextWidgetId();
+		procaptchaWidgets.set(id, {
+			root,
+			element: at(elements, index),
+			renderOptions,
+			isWeb2,
+			invisible,
+		});
+		return id;
+	});
 
 const widgetFactory = new WidgetFactory(new WidgetThemeResolver());
 
@@ -87,17 +129,25 @@ const implicitRender = async () => {
 		// `customDetectBot` claims the in-flight promise when it eventually runs.
 		startDetectorPrefetch(siteKey, { ipv4, ipv6 });
 
+		const implicitRenderOptions: ProcaptchaRenderOptions = {
+			siteKey: siteKey,
+			ipv4,
+			ipv6,
+		};
+
 		const root = await widgetFactory.createWidgets(
 			elements,
-			{
-				siteKey: siteKey,
-				ipv4,
-				ipv6,
-			},
+			implicitRenderOptions,
 			!(web3 === "true"),
 		);
 
-		procaptchaRoots.push(...root);
+		registerWidgets(
+			root,
+			elements,
+			implicitRenderOptions,
+			!(web3 === "true"),
+			false,
+		);
 	}
 
 	// Check for invisible mode indicators (procaptcha class on buttons)
@@ -114,19 +164,21 @@ const implicitRender = async () => {
 
 			startDetectorPrefetch(siteKey, { ipv4, ipv6 });
 
+			const buttonRenderOptions: ProcaptchaRenderOptions = {
+				siteKey: siteKey,
+				callback: callback,
+				ipv4,
+				ipv6,
+			};
+
 			const root = await widgetFactory.createWidgets(
 				[button],
-				{
-					siteKey: siteKey,
-					callback: callback,
-					ipv4,
-					ipv6,
-				},
+				buttonRenderOptions,
 				true,
 				true,
 			);
 
-			procaptchaRoots.push(...root);
+			registerWidgets(root, [button], buttonRenderOptions, true, true);
 
 			// Add click event listener to the button
 			button.addEventListener("click", async (event) => {
@@ -138,10 +190,19 @@ const implicitRender = async () => {
 };
 
 // Explicit render for targeting specific elements
+/**
+ * Renders a widget into `element` and returns its id, which `reset()` and
+ * `remove()` accept to target this widget alone. Previously this returned
+ * nothing, so callers had no handle on an individual widget and the only
+ * available reset was all-or-nothing.
+ *
+ * Returns undefined when no widget was created, rather than throwing — the
+ * factory legitimately yields nothing for an element it cannot mount into.
+ */
 export const render = async (
 	element: Element,
 	renderOptions: ProcaptchaRenderOptions,
-) => {
+): Promise<string | undefined> => {
 	startDetectorPrefetch(renderOptions.siteKey, renderOptions);
 
 	const hasInvisibleSize =
@@ -149,26 +210,27 @@ export const render = async (
 		renderOptions.size === "invisible";
 
 	const isWeb2 = !renderOptions.web3;
-
-	if (hasInvisibleSize || element.tagName.toLowerCase() === "button") {
-		const roots = await widgetFactory.createWidgets(
-			[element],
-			renderOptions,
-			isWeb2,
-			true,
-		);
-		procaptchaRoots.push(...roots);
-		return;
-	}
+	const invisible =
+		hasInvisibleSize || element.tagName.toLowerCase() === "button";
 
 	const roots = await widgetFactory.createWidgets(
 		[element],
 		renderOptions,
 		isWeb2,
-		false,
+		invisible,
 	);
 
-	procaptchaRoots.push(...roots);
+	const ids = registerWidgets(
+		roots,
+		[element],
+		renderOptions,
+		isWeb2,
+		invisible,
+	);
+
+	// Deliberately not `at()`: it throws on an empty array before it consults
+	// `optional`, and zero roots is a legitimate outcome here.
+	return ids[0];
 };
 
 export default function ready(fn: () => void) {
@@ -246,6 +308,7 @@ declare global {
 			ready: typeof ready;
 			render: typeof render;
 			reset: typeof reset;
+			remove: typeof remove;
 			execute: typeof execute;
 		};
 	}
@@ -284,17 +347,69 @@ const start = () => {
 	}
 };
 
-export const reset = () => {
-	for (const root of procaptchaRoots) {
-		root.unmount();
+/**
+ * Returns a widget to its unsolved state, ready to be solved again. Pass a
+ * widget id to reset one widget, or omit it to reset every widget on the page.
+ *
+ * This remounts rather than merely unmounting. The previous implementation
+ * unmounted every root and then called `start()`, which only re-renders when
+ * the page uses implicit rendering — and even then only via the
+ * `document.readyState` fallback, because the script's `load` event has long
+ * since fired. On an explicitly-rendered page nothing came back at all: the
+ * skeleton stayed in the DOM with no checkbox inside it, and no fresh captcha
+ * request was ever made. Rebuilding from the stored descriptor makes reset
+ * behave the same way on both paths.
+ *
+ * `start()` is deliberately not called here any more. It re-renders implicit
+ * widgets, which would double up with the remount below, and it attaches
+ * another `load` listener to the script tag on every call.
+ */
+export const reset = async (widgetId?: string): Promise<void> => {
+	const ids: string[] =
+		undefined === widgetId ? Array.from(procaptchaWidgets.keys()) : [widgetId];
+
+	for (const id of ids) {
+		const current = procaptchaWidgets.get(id);
+		if (!current) continue;
+
+		current.root.unmount();
+
+		const [root] = await widgetFactory.createWidgets(
+			[current.element],
+			current.renderOptions,
+			current.isWeb2,
+			current.invisible,
+		);
+
+		if (root) {
+			procaptchaWidgets.set(id, { ...current, root });
+		} else {
+			procaptchaWidgets.delete(id);
+		}
 	}
-	procaptchaRoots = [];
+};
 
-	start();
+/**
+ * Tears a widget down without putting it back — the behaviour `reset()` used
+ * to have by accident on explicitly-rendered pages, kept as an explicit
+ * operation for callers that genuinely want the widget gone (a closing modal,
+ * an SPA route change).
+ */
+export const remove = (widgetId?: string): void => {
+	const ids =
+		undefined === widgetId ? Array.from(procaptchaWidgets.keys()) : [widgetId];
+
+	for (const id of ids) {
+		const entry = procaptchaWidgets.get(id);
+		if (!entry) continue;
+		entry.root.unmount();
+		entry.element.innerHTML = "";
+		procaptchaWidgets.delete(id);
+	}
 };
 
 // set the procaptcha attribute on the window
-window.procaptcha = { ready, render, reset, execute };
+window.procaptcha = { ready, render, reset, remove, execute };
 
 // Dispatch a custom event to notify that window.procaptcha is ready
 const procaptchaReadyEvent = new CustomEvent(PROCAPTCHA_READY_EVENT, {

package/src/tests/reset.unit.test.ts

@@ -0,0 +1,204 @@
+// 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.
+
+/**
+ * `reset()` used to unmount every React root and then call `start()`, which
+ * re-renders only on implicitly-rendered pages. An explicitly-rendered widget
+ * was therefore destroyed and never rebuilt: the skeleton stayed in the DOM
+ * with no checkbox inside it and no fresh captcha request was made. These
+ * tests pin the remount so that regression cannot return.
+ */
+
+import type { Root } from "react-dom/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	prefetchDetector: vi.fn(),
+	createWidgets: vi.fn(),
+}));
+
+vi.mock("@prosopo/procaptcha-frictionless", () => ({
+	prefetchDetector: mocks.prefetchDetector,
+}));
+
+vi.mock("@prosopo/procaptcha-common", () => ({
+	getWindowCallback: vi.fn(),
+	pickIpMode: vi.fn(() => undefined),
+}));
+
+vi.mock("../util/widgetFactory.js", () => ({
+	WidgetFactory: vi.fn(function () {
+		return { createWidgets: mocks.createWidgets };
+	}),
+}));
+
+const { render, reset, remove } = await import("../index.js");
+
+const SITE_KEY = "5CcNvLUdiXFpzKDMjThGLSK9rhWHA1H4EF3zrgkpkjAdqmuP";
+
+const makeRoot = (): Root =>
+	({ unmount: vi.fn(), render: vi.fn() }) as unknown as Root;
+
+/** Each createWidgets call yields a distinct root, as the real factory does. */
+const queueRoots = (...roots: Root[]): void => {
+	for (const root of roots) {
+		mocks.createWidgets.mockResolvedValueOnce([root]);
+	}
+};
+
+beforeEach(async () => {
+	vi.clearAllMocks();
+	// Drop any widgets registered by a previous test — module state persists
+	// across tests in the same file.
+	await remove();
+	mocks.createWidgets.mockResolvedValue([makeRoot()]);
+});
+
+describe("render", () => {
+	it("returns a widget id", async () => {
+		queueRoots(makeRoot());
+
+		const widgetId = await render(document.createElement("div"), {
+			siteKey: SITE_KEY,
+		});
+
+		expect(typeof widgetId).toBe("string");
+		expect(widgetId).toBeTruthy();
+	});
+
+	it("returns undefined when the factory creates no widget", async () => {
+		mocks.createWidgets.mockResolvedValueOnce([] as Root[]);
+
+		const widgetId = await render(document.createElement("div"), {
+			siteKey: SITE_KEY,
+		});
+
+		expect(widgetId).toBeUndefined();
+	});
+});
+
+describe("reset", () => {
+	it("unmounts the old root and mounts a replacement", async () => {
+		const first = makeRoot();
+		const second = makeRoot();
+		queueRoots(first, second);
+
+		const element = document.createElement("div");
+		await render(element, { siteKey: SITE_KEY });
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+
+		await reset();
+
+		expect(first.unmount).toHaveBeenCalledTimes(1);
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(2);
+		// Rebuilt into the same element, with the options it was rendered with.
+		expect(mocks.createWidgets).toHaveBeenLastCalledWith(
+			[element],
+			expect.objectContaining({ siteKey: SITE_KEY }),
+			true,
+			false,
+		);
+		expect(second.unmount).not.toHaveBeenCalled();
+	});
+
+	it("resets only the widget whose id is given", async () => {
+		const firstA = makeRoot();
+		const firstB = makeRoot();
+		const replacementA = makeRoot();
+		queueRoots(firstA, firstB, replacementA);
+
+		const elementA = document.createElement("div");
+		const elementB = document.createElement("div");
+		const idA = await render(elementA, { siteKey: SITE_KEY });
+		await render(elementB, { siteKey: SITE_KEY });
+
+		await reset(idA);
+
+		expect(firstA.unmount).toHaveBeenCalledTimes(1);
+		expect(firstB.unmount).not.toHaveBeenCalled();
+		expect(mocks.createWidgets).toHaveBeenLastCalledWith(
+			[elementA],
+			expect.anything(),
+			true,
+			false,
+		);
+	});
+
+	it("keeps the widget resettable more than once", async () => {
+		const roots = [makeRoot(), makeRoot(), makeRoot()];
+		queueRoots(...roots);
+
+		await render(document.createElement("div"), { siteKey: SITE_KEY });
+		await reset();
+		await reset();
+
+		expect(roots[0]?.unmount).toHaveBeenCalledTimes(1);
+		expect(roots[1]?.unmount).toHaveBeenCalledTimes(1);
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(3);
+	});
+
+	it("preserves the invisible flag when rebuilding", async () => {
+		queueRoots(makeRoot(), makeRoot());
+
+		const button = document.createElement("button");
+		await render(button, { siteKey: SITE_KEY });
+
+		await reset();
+
+		expect(mocks.createWidgets).toHaveBeenLastCalledWith(
+			[button],
+			expect.anything(),
+			true,
+			true,
+		);
+	});
+
+	it("does nothing for an unknown widget id", async () => {
+		queueRoots(makeRoot());
+		await render(document.createElement("div"), { siteKey: SITE_KEY });
+
+		await reset("procaptcha-widget-does-not-exist");
+
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("remove", () => {
+	it("unmounts without mounting a replacement", async () => {
+		const root = makeRoot();
+		queueRoots(root);
+
+		const element = document.createElement("div");
+		element.innerHTML = "<span>skeleton</span>";
+		await render(element, { siteKey: SITE_KEY });
+
+		await remove();
+
+		expect(root.unmount).toHaveBeenCalledTimes(1);
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+		// The skeleton is plain DOM, so unmounting React alone would leave it
+		// behind — remove() is responsible for clearing the container too.
+		expect(element.innerHTML).toBe("");
+	});
+
+	it("makes a subsequent reset a no-op", async () => {
+		queueRoots(makeRoot());
+		await render(document.createElement("div"), { siteKey: SITE_KEY });
+
+		await remove();
+		await reset();
+
+		expect(mocks.createWidgets).toHaveBeenCalledTimes(1);
+	});
+});