@prosopo/procaptcha-puzzle 2.13.3 → 2.14.1

package/src/tests/domHarness.ts

@@ -0,0 +1,122 @@
+// 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.
+
+/**
+ * A minimal mount/unmount harness. The suite deliberately drives real DOM
+ * events rather than calling handlers directly, because every interactive
+ * element in this package drops untrusted events — behaviour that only shows
+ * up when a real event carries the flag.
+ */
+export interface Mounted {
+	container: HTMLDivElement;
+	unmount: () => void;
+}
+
+export const mount = (): Mounted => {
+	const container = document.createElement("div");
+	document.body.appendChild(container);
+	return {
+		container,
+		unmount: () => {
+			container.remove();
+		},
+	};
+};
+
+interface FireOptions {
+	trusted?: boolean;
+	clientX?: number;
+	clientY?: number;
+	touches?: { clientX: number; clientY: number }[];
+	key?: string;
+}
+
+/**
+ * jsdom marks everything it dispatches untrusted, and exposes `isTrusted` as a
+ * non-configurable accessor onto its internal implementation object, so the
+ * flag has to be set there rather than shadowed on the event. Anything the
+ * components filter on untrusted events is untestable otherwise.
+ */
+const setTrusted = (event: Event, trusted: boolean): void => {
+	for (const symbol of Object.getOwnPropertySymbols(event)) {
+		const impl: unknown = Reflect.get(event, symbol);
+		if (impl && typeof impl === "object" && "isTrusted" in impl) {
+			// A plain assignment would not survive: dispatchEvent stamps
+			// isTrusted back to false on the way in, so the flag is pinned with
+			// an accessor that swallows the write.
+			Object.defineProperty(impl, "isTrusted", {
+				configurable: true,
+				get: () => trusted,
+				set: () => undefined,
+			});
+			return;
+		}
+	}
+	throw new Error("could not reach the jsdom event implementation");
+};
+
+const build = (type: string, options: FireOptions): Event => {
+	if (undefined !== options.key) {
+		return new KeyboardEvent(type, {
+			bubbles: true,
+			cancelable: true,
+			key: options.key,
+		});
+	}
+	return new MouseEvent(type, {
+		bubbles: true,
+		cancelable: true,
+		clientX: options.clientX ?? 0,
+		clientY: options.clientY ?? 0,
+	});
+};
+
+/**
+ * Dispatches a real event at the element. Touch points are plain objects:
+ * jsdom has no Touch constructor.
+ */
+export const fire = (
+	element: Element,
+	type: string,
+	options: FireOptions = {},
+): void => {
+	fireAndReturn(element, type, options);
+};
+
+/** Like `fire`, but hands back the event so a test can inspect what the
+ * handler did to it — whether it prevented the default form submission, say. */
+export const fireAndReturn = (
+	element: Element,
+	type: string,
+	options: FireOptions = {},
+): Event => {
+	const event = build(type, options);
+	setTrusted(event, options.trusted ?? true);
+	if (options.touches) {
+		Object.defineProperty(event, "touches", { value: options.touches });
+	}
+	element.dispatchEvent(event);
+	return event;
+};
+
+/**
+ * Renders coalesce onto the microtask queue, so a state change is not visible
+ * in the DOM until it has drained.
+ */
+export const settle = async (): Promise<void> => {
+	// A macrotask turn, so a pending dynamic import resolves too — draining the
+	// microtask queue alone is not enough for the code-split boundaries.
+	await new Promise<void>((resolve: () => void) => setTimeout(resolve, 0));
+	await Promise.resolve();
+};

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

@@ -0,0 +1,179 @@
+// 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.
+
+import type { Ti18n } from "@prosopo/locale";
+import {
+	type GetPuzzleCaptchaResponse,
+	ModeEnum,
+	type ProcaptchaProps,
+	type ProcaptchaState,
+	type PuzzleEvent,
+} from "@prosopo/types";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+	type ProcaptchaPuzzleHandle,
+	mountProcaptchaPuzzleWidget,
+} from "../components/procaptchaWidget.js";
+import { type Mounted, fire, mount, settle } from "./domHarness.js";
+import { challengeResponse, config, frictionless } from "./managerHarness.js";
+
+// The canvas is deliberately NOT mocked here: the point of this suite is
+// whether the overlay the user has to drag actually becomes visible. The
+// widget suite stubs the canvas, so it asserts the challenge was handed over,
+// not that anything reached the screen.
+const mocks = vi.hoisted(() => {
+	const start =
+		vi.fn<
+			(x?: number, y?: number) => Promise<GetPuzzleCaptchaResponse | undefined>
+		>();
+	const submitSolution =
+		vi.fn<(x: number, y: number, events: PuzzleEvent[]) => Promise<boolean>>();
+	const resetState = vi.fn<() => void>();
+	return { start, submitSolution, resetState };
+});
+
+vi.mock("../services/Manager.js", () => ({
+	Manager: (
+		_config: unknown,
+		_state: ProcaptchaState,
+		_updateState: (next: Partial<ProcaptchaState>) => void,
+	) => ({
+		start: mocks.start,
+		submitSolution: mocks.submitSolution,
+		resetState: mocks.resetState,
+	}),
+}));
+
+vi.mock("@prosopo/locale", async (importOriginal) => ({
+	...(await importOriginal<typeof import("@prosopo/locale")>()),
+	loadI18next: vi.fn(async () => undefined),
+}));
+
+const i18nStub = {
+	isInitialized: true,
+	language: "en",
+	t: (key: string) => key,
+	changeLanguage: vi.fn(),
+	hasLoadedNamespace: () => true,
+	on: () => undefined,
+	off: () => undefined,
+} as unknown as Ti18n;
+
+const props = (overrides: Partial<ProcaptchaProps> = {}): ProcaptchaProps =>
+	({
+		config: config({ mode: ModeEnum.visible }),
+		callbacks: {},
+		i18n: i18nStub,
+		frictionlessState: frictionless(),
+		...overrides,
+	}) as unknown as ProcaptchaProps;
+
+let mounted: Mounted;
+let handle: ProcaptchaPuzzleHandle | undefined;
+
+// Class names are hashed by the CSS-module build, so the surface is addressed
+// through the `data-cy` hooks the components ship for exactly this reason.
+const surface = (): HTMLElement | null =>
+	document.querySelector<HTMLElement>('[data-cy="challenge-surface"]');
+
+// The panel carrying the entrance animation is the only element under the
+// surface with an inline opacity of its own.
+const panelOpacity = (): string | undefined => {
+	const content = document.querySelector('[data-cy="challenge-content"]');
+	if (!content) return undefined;
+	return Array.from(
+		content.querySelectorAll<HTMLElement>("[style*='opacity']"),
+	).at(-1)?.style.opacity;
+};
+
+// The entrance animation flips opacity inside a requestAnimationFrame, so a
+// test has to let a frame run before reading it.
+const frame = async (): Promise<void> => {
+	await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+	await settle();
+};
+
+beforeEach(() => {
+	mocks.start.mockResolvedValue(challengeResponse());
+	mounted = mount();
+});
+
+afterEach(() => {
+	handle?.destroy();
+	handle = undefined;
+	mounted.unmount();
+	for (const layer of Array.from(
+		document.querySelectorAll(".prosopo-challenge-surface"),
+	)) {
+		layer.remove();
+	}
+	vi.clearAllMocks();
+});
+
+describe("the puzzle overlay actually reaches the screen", () => {
+	test("visible mode: the panel is opaque after the entrance frame", async () => {
+		handle = mountProcaptchaPuzzleWidget(mounted.container, props());
+		const checkbox = mounted.container.querySelector("input");
+		expect(checkbox, "the visible widget renders a checkbox").not.toBeNull();
+		if (checkbox) fire(checkbox, "click");
+		await settle();
+		await frame();
+
+		expect(mocks.start).toHaveBeenCalledTimes(1);
+		expect(surface(), "the overlay is mounted").not.toBeNull();
+		expect(panelOpacity()).toBe("1");
+	});
+
+	// Invisible mode has no checkbox, so the overlay is opened by the host
+	// page's execute(). It still has to reach the screen: the piece is dragged
+	// by hand, and a panel left at opacity 0 is a challenge nobody can solve.
+	test("invisible mode: the panel is opaque after the entrance frame", async () => {
+		handle = mountProcaptchaPuzzleWidget(
+			mounted.container,
+			props({ config: config({ mode: ModeEnum.invisible }) }),
+		);
+		document.dispatchEvent(new Event("procaptcha:execute"));
+		await settle();
+		await frame();
+
+		expect(mocks.start).toHaveBeenCalledTimes(1);
+		expect(surface(), "the overlay is mounted").not.toBeNull();
+		expect(panelOpacity()).toBe("1");
+	});
+
+	// The entrance frame is cancelled on teardown, so a canvas destroyed and
+	// remounted before it runs would stay transparent for good.
+	test("invisible mode: a remounted overlay still becomes opaque", async () => {
+		handle = mountProcaptchaPuzzleWidget(
+			mounted.container,
+			props({ config: config({ mode: ModeEnum.invisible }) }),
+		);
+		document.dispatchEvent(new Event("procaptcha:execute"));
+		await settle();
+		await frame();
+		expect(panelOpacity()).toBe("1");
+
+		handle.destroy();
+		handle = mountProcaptchaPuzzleWidget(
+			mounted.container,
+			props({ config: config({ mode: ModeEnum.invisible }) }),
+		);
+		document.dispatchEvent(new Event("procaptcha:execute"));
+		await settle();
+		await frame();
+
+		expect(surface(), "the overlay is mounted again").not.toBeNull();
+		expect(panelOpacity()).toBe("1");
+	});
+});

package/src/tests/procaptchaPuzzle.test-d.ts

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { Ti18n } from "@prosopo/locale";
+import type { Ti18n, Translator } from "@prosopo/locale";
 import type {
 	FrictionlessState,
 	GetPuzzleCaptchaResponse,
@@ -24,11 +24,13 @@ import type {
 	PuzzleEvent,
 } from "@prosopo/types";
 import { lightTheme } from "@prosopo/widget-skeleton";
-import type { ReactElement } from "react";
 import { assertType, describe, expectTypeOf, test } from "vitest";
-import { PuzzleCanvas } from "../components/PuzzleCanvas.js";
+import {
+	type PuzzleCanvasProps,
+	mountPuzzleCanvas,
+} from "../components/puzzleCanvas.js";
 import type * as entrypoint from "../index.js";
-import { ProcaptchaPuzzle } from "../index.js";
+import { mountProcaptchaPuzzle } from "../index.js";
 import { Manager } from "../services/Manager.js";
 import {
 	challengeResponse,
@@ -42,17 +44,25 @@ import {
 const i18n = (): Ti18n => undefined as unknown as Ti18n;
 
 describe("the package entrypoint's types", () => {
-	test("ProcaptchaPuzzle takes the shared widget props and renders an element", () => {
-		expectTypeOf(ProcaptchaPuzzle).parameters.toEqualTypeOf<
-			[ProcaptchaProps]
+	test("mountProcaptchaPuzzle takes a host element and the shared widget props", () => {
+		expectTypeOf(mountProcaptchaPuzzle).parameters.toEqualTypeOf<
+			[HTMLElement, ProcaptchaProps]
 		>();
-		expectTypeOf(ProcaptchaPuzzle).returns.toExtend<ReactElement>();
+		expectTypeOf(mountProcaptchaPuzzle).returns.toExtend<{
+			destroy: () => void;
+		}>();
 	});
 
-	test("the inner widget's default export is not re-exported", () => {
-		// `export *` skips default exports, so consumers can only reach the lazy
-		// wrapper — the one that works without a code-splitting bundler.
-		expectTypeOf<keyof typeof entrypoint>().toEqualTypeOf<"ProcaptchaPuzzle">();
+	test("the entrypoint exposes the lazy wrapper and the widget itself", () => {
+		// The lazy wrapper is what works without a code-splitting bundler; the
+		// direct mount is what ProcaptchaFrictionless imports once it has already
+		// paid for the dynamic import of this package.
+		expectTypeOf<keyof typeof entrypoint>().toEqualTypeOf<
+			| "mountProcaptchaPuzzle"
+			| "loadProcaptchaPuzzle"
+			| "mountProcaptchaPuzzleWidget"
+			| "mountPuzzleCanvas"
+		>();
 	});
 
 	test("config, callbacks and i18n are all required", () => {
@@ -140,6 +150,7 @@ describe("Manager's types", () => {
 });
 
 describe("PuzzleCanvas' types", () => {
+	const translator = (): Translator => undefined as unknown as Translator;
 	const onComplete = (
 		_finalX: number,
 		_finalY: number,
@@ -148,9 +159,9 @@ describe("PuzzleCanvas' types", () => {
 
 	test("every prop is required, since none has a sensible default", () => {
 		// @ts-expect-error - a board with no imagery cannot be rendered.
-		PuzzleCanvas({ originX: 0, originY: 0 });
+		mountPuzzleCanvas({ originX: 0, originY: 0 });
 		// @ts-expect-error - `submitting` gates the drag; omitting it unlocks it.
-		PuzzleCanvas({
+		mountPuzzleCanvas({
 			originX: 0,
 			originY: 0,
 			background: "data:image/webp;base64,UklGRg==",
@@ -159,12 +170,13 @@ describe("PuzzleCanvas' types", () => {
 			onComplete,
 			showRetry: false,
 			theme: lightTheme,
+			translator: translator(),
 		});
 	});
 
-	test("the full prop set renders an element", () => {
+	test("the full prop set mounts a component that can be updated and torn down", () => {
 		expectTypeOf(
-			PuzzleCanvas({
+			mountPuzzleCanvas({
 				originX: 0,
 				originY: 0,
 				background: "data:image/webp;base64,UklGRg==",
@@ -174,8 +186,12 @@ describe("PuzzleCanvas' types", () => {
 				showRetry: false,
 				submitting: false,
 				theme: lightTheme,
+				translator: translator(),
 			}),
-		).toExtend<ReactElement>();
+		).toExtend<{
+			update: (props: PuzzleCanvasProps) => void;
+			destroy: () => void;
+		}>();
 	});
 
 	test("the drop is reported synchronously, not as a promise", () => {

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

@@ -14,34 +14,43 @@
 
 import type { Ti18n } from "@prosopo/locale";
 import type { ProcaptchaProps } from "@prosopo/types";
-import { type ReactElement, act, createElement } from "react";
-import { type Root, createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ProcaptchaPuzzleHandle } from "../components/procaptchaWidget.js";
 import * as entrypoint from "../index.js";
+import { type Mounted, mount, settle } from "./domHarness.js";
 import { config } from "./managerHarness.js";
 
 /**
- * The outer component exists only to lazy-load the widget and hand it the props
- * it was given, so what is worth pinning down is that nothing is dropped on the
- * way through — a wrapper that names props one at a time silently loses the
- * ones added later.
+ * The outer entry point exists only to lazy-load the widget and hand it the
+ * props it was given, so what is worth pinning down is that nothing is dropped
+ * on the way through — a wrapper that names props one at a time silently loses
+ * the ones added later.
  */
 const mocks = vi.hoisted(() => ({
 	received: [] as ProcaptchaProps[],
+	destroyed: { count: 0 },
 }));
 
-vi.mock("../components/ProcaptchaWidget.js", async () => {
-	const { createElement: create } = await import("react");
-	return {
-		default: (props: ProcaptchaProps) => {
-			mocks.received.push(props);
-			return create("div", { "data-testid": "widget" });
-		},
-	};
-});
+vi.mock("../components/procaptchaWidget.js", () => ({
+	mountProcaptchaPuzzleWidget: (
+		container: HTMLElement,
+		props: ProcaptchaProps,
+	): ProcaptchaPuzzleHandle => {
+		mocks.received.push(props);
+		const element = document.createElement("div");
+		element.setAttribute("data-testid", "widget");
+		container.appendChild(element);
+		return {
+			destroy: () => {
+				element.remove();
+				mocks.destroyed.count += 1;
+			},
+		};
+	},
+}));
 
-let container: HTMLDivElement;
-let root: Root;
+let mounted: Mounted;
+let widget: ProcaptchaPuzzleHandle | undefined;
 
 const props = (overrides: Partial<ProcaptchaProps> = {}): ProcaptchaProps => ({
 	config: config(),
@@ -51,33 +60,29 @@ const props = (overrides: Partial<ProcaptchaProps> = {}): ProcaptchaProps => ({
 });
 
 const render = async (widgetProps: ProcaptchaProps): Promise<void> => {
-	await act(async () => {
-		root.render(
-			createElement(entrypoint.ProcaptchaPuzzle, widgetProps) as ReactElement,
-		);
-	});
+	widget = entrypoint.mountProcaptchaPuzzle(mounted.container, widgetProps);
+	await settle();
 };
 
 beforeEach(() => {
 	mocks.received.length = 0;
-	container = document.createElement("div");
-	document.body.appendChild(container);
-	act(() => {
-		root = createRoot(container);
-	});
+	mocks.destroyed.count = 0;
+	widget = undefined;
+	mounted = mount();
 });
 
 afterEach(() => {
-	act(() => {
-		root.unmount();
-	});
-	container.remove();
+	widget?.destroy();
+	widget = undefined;
+	mounted.unmount();
 });
 
-describe("ProcaptchaPuzzle", () => {
+describe("mountProcaptchaPuzzle", () => {
 	test("renders the widget once it has loaded", async () => {
 		await render(props());
-		expect(container.querySelector('[data-testid="widget"]')).not.toBeNull();
+		expect(
+			mounted.container.querySelector('[data-testid="widget"]'),
+		).not.toBeNull();
 	});
 
 	test("passes on the props the widget needs but never names", async () => {
@@ -103,21 +108,31 @@ describe("ProcaptchaPuzzle", () => {
 		expect(mocks.received[0]?.config).toEqual(config());
 	});
 
-	test("mounts one widget per render, not one per prop change", async () => {
+	test("tears the loaded widget down", async () => {
 		await render(props());
-		await render(props({ autoStart: true }));
-		expect(container.querySelectorAll('[data-testid="widget"]')).toHaveLength(
-			1,
-		);
+		widget?.destroy();
+		widget = undefined;
+		expect(mocks.destroyed.count).toBe(1);
+		expect(
+			mounted.container.querySelector('[data-testid="widget"]'),
+		).toBeNull();
+	});
+
+	test("cancels a mount that is still loading", async () => {
+		// Otherwise a widget torn down mid-load reappears as an orphan that
+		// nothing holds a handle to.
+		widget = entrypoint.mountProcaptchaPuzzle(mounted.container, props());
+		widget.destroy();
+		widget = undefined;
+		await settle();
+		expect(mocks.received).toHaveLength(0);
 	});
 });
 
 describe("the package entrypoint", () => {
-	test("exports the wrapper a consumer mounts", () => {
-		// The inner ProcaptchaWidget is a default export, which `export *` does
-		// not re-export: consumers get the lazy-loading wrapper only, which is
-		// the one that works outside a bundler that can code-split.
-		expect(typeof entrypoint.ProcaptchaPuzzle).toBe("function");
-		expect(Object.keys(entrypoint)).toEqual(["ProcaptchaPuzzle"]);
+	test("exports the mount functions a consumer needs", () => {
+		expect(typeof entrypoint.mountProcaptchaPuzzle).toBe("function");
+		expect(typeof entrypoint.loadProcaptchaPuzzle).toBe("function");
+		expect(typeof entrypoint.mountProcaptchaPuzzleWidget).toBe("function");
 	});
 });