@prosopo/procaptcha-bundle 4.2.5 → 4.4.0

package/.turbo/turbo-build$colon$cjs.log

@@ -1,5 +1,5 @@
 
-> @prosopo/procaptcha-bundle@4.2.5 build:cjs
+> @prosopo/procaptcha-bundle@4.4.0 build:cjs
 > NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV
 
 ViteCommonJSConfig: .
@@ -57,21 +57,22 @@ ViteCommonJSConfig: .
 vite v8.1.5 building ssr environment for production...
 Bundle build started
 
-✓ 11 modules transformed.
+✓ 12 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/cjs/util/widgetThemeResolver.cjs               0.57 kB │ gzip: 0.29 kB
-dist/cjs/util/timeout.cjs                           0.63 kB │ gzip: 0.29 kB
-dist/cjs/util/config.cjs                            0.66 kB │ gzip: 0.33 kB
-dist/cjs/util/captcha/components/bundleCaptcha.cjs  0.82 kB │ gzip: 0.39 kB
-dist/cjs/util/configCreator.cjs                     0.88 kB │ gzip: 0.46 kB
-dist/cjs/_virtual/_rolldown/runtime.cjs             1.00 kB │ gzip: 0.50 kB
-dist/cjs/util/clientSession.cjs                     1.08 kB │ gzip: 0.56 kB
-dist/cjs/util/language.cjs                          1.08 kB │ gzip: 0.45 kB
-dist/cjs/util/captcha/captchaRenderer.cjs           2.40 kB │ gzip: 0.80 kB
-dist/cjs/util/widgetFactory.cjs                     2.73 kB │ gzip: 0.89 kB
-dist/cjs/index.cjs                                  9.20 kB │ gzip: 3.22 kB
+dist/cjs/util/widgetThemeResolver.cjs                0.57 kB │ gzip: 0.29 kB
+dist/cjs/util/timeout.cjs                            0.63 kB │ gzip: 0.29 kB
+dist/cjs/util/config.cjs                             0.66 kB │ gzip: 0.33 kB
+dist/cjs/util/captcha/components/bundleCaptcha.cjs   0.82 kB │ gzip: 0.39 kB
+dist/cjs/util/startMode.cjs                          0.89 kB │ gzip: 0.40 kB
+dist/cjs/util/configCreator.cjs                      1.00 kB │ gzip: 0.50 kB
+dist/cjs/_virtual/_rolldown/runtime.cjs              1.00 kB │ gzip: 0.50 kB
+dist/cjs/util/clientSession.cjs                      1.08 kB │ gzip: 0.56 kB
+dist/cjs/util/language.cjs                           1.08 kB │ gzip: 0.45 kB
+dist/cjs/util/widgetFactory.cjs                      2.78 kB │ gzip: 0.90 kB
+dist/cjs/util/captcha/captchaRenderer.cjs            3.04 kB │ gzip: 1.00 kB
+dist/cjs/index.cjs                                  11.88 kB │ gzip: 3.88 kB
 
-[MIXED_EXPORTS] Entry module "src/index.ts" is using named (including "default", "execute", "remove", "render", "reset") and default exports together. Consumers of your bundle will have to use `..default` to access the default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
+[MIXED_EXPORTS] Entry module "src/index.ts" is using named (including "default", "execute", "remove", "render", "reset", "start") and default exports together. Consumers of your bundle will have to use `..default` to access the default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
 
-✓ built in 41ms
+✓ built in 59ms

package/.turbo/turbo-build$colon$tsc.log

@@ -1,8 +1,8 @@
 
-> @prosopo/procaptcha-bundle@4.2.5 build:tsc
+> @prosopo/procaptcha-bundle@4.4.0 build:tsc
 > tsc --build --verbose
 
-1:56:47 PM - Projects in this build: 
+1:15:52 PM - Projects in this build: 
     * ../../dev/config/tsconfig.json
     * ../util/tsconfig.json
     * ../logger/tsconfig.json
@@ -27,51 +27,51 @@
     * ../procaptcha-frictionless/tsconfig.json
     * tsconfig.json
 
-1:56:47 PM - Project '../../dev/config/tsconfig.json' is up to date because newest input '../../dev/config/src/webpack/webpack.config.ts' is older than output '../../dev/config/tsconfig.tsbuildinfo'
+1:15:52 PM - Project '../../dev/config/tsconfig.json' is up to date because newest input '../../dev/config/src/webpack/webpack.config.ts' is older than output '../../dev/config/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../util/tsconfig.json' is up to date because newest input '../util/src/url.ts' is older than output '../util/tsconfig.tsbuildinfo'
+1:15:52 PM - Project '../util/tsconfig.json' is up to date because newest input '../util/src/url.ts' is older than output '../util/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../logger/tsconfig.json' is up to date because newest input '../logger/src/index.ts' is older than output '../logger/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../logger/tsconfig.json' is up to date because newest input '../logger/src/index.ts' is older than output '../logger/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../dotenv/tsconfig.json' is up to date because newest input '../dotenv/src/index.ts' is older than output '../dotenv/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../dotenv/tsconfig.json' is up to date because newest input '../dotenv/src/env.ts' is older than output '../dotenv/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../locale/tsconfig.json' is up to date because newest input '../locale/src/translationKey.ts' is older than output '../locale/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../locale/tsconfig.json' is up to date because newest input '../locale/src/translationKey.ts' is older than output '../locale/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../util-crypto/tsconfig.json' is up to date because newest input '../util-crypto/src/types.ts' is older than output '../util-crypto/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../util-crypto/tsconfig.json' is up to date because newest input '../util-crypto/src/types.ts' is older than output '../util-crypto/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../types/tsconfig.json' is up to date because newest input '../types/src/index.ts' is older than output '../types/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../types/tsconfig.json' is up to date because newest input '../types/src/types.test-d.ts' is older than output '../types/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../api/tsconfig.json' is up to date because newest input '../api/src/index.ts' is older than output '../api/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../api/tsconfig.json' is up to date because newest input '../api/src/tests/apiHarness.ts' is older than output '../api/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../common/tsconfig.json' is up to date because newest input '../common/src/index.ts' is older than output '../common/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../common/tsconfig.json' is up to date because newest input '../common/src/utils/batches.ts' is older than output '../common/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../fingerprintjs/tsconfig.json' is up to date because newest input '../fingerprintjs/src/utils/browser.ts' is older than output '../fingerprintjs/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../fingerprintjs/tsconfig.json' is up to date because newest input '../fingerprintjs/src/utils/browser.ts' is older than output '../fingerprintjs/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../fingerprint/tsconfig.json' is up to date because newest input '../fingerprint/src/index.ts' is older than output '../fingerprint/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../fingerprint/tsconfig.json' is up to date because newest input '../fingerprint/src/index.ts' is older than output '../fingerprint/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../load-balancer/tsconfig.json' is up to date because newest input '../load-balancer/src/balancer.ts' is older than output '../load-balancer/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../load-balancer/tsconfig.json' is up to date because newest input '../load-balancer/src/balancer.ts' is older than output '../load-balancer/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../widget-skeleton/tsconfig.json' is up to date because newest input '../widget-skeleton/src/constants.ts' is older than output '../widget-skeleton/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../widget-skeleton/tsconfig.json' is up to date because newest input '../widget-skeleton/src/index.ts' is older than output '../widget-skeleton/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../keyring/tsconfig.json' is up to date because newest input '../keyring/src/index.ts' is older than output '../keyring/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../keyring/tsconfig.json' is up to date because newest input '../keyring/src/keyring/keyring.test.ts' is older than output '../keyring/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../account/tsconfig.json' is up to date because newest input '../account/src/workers/cryptoWorker.ts' is older than output '../account/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../account/tsconfig.json' is up to date because newest input '../account/src/custom.d.ts' is older than output '../account/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha-common/tsconfig.json' is up to date because newest input '../procaptcha-common/src/simdReadings.ts' is older than output '../procaptcha-common/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha-common/tsconfig.json' is up to date because newest input '../procaptcha-common/src/tests/challengeSurfaceRender.unit.test.tsx' is older than output '../procaptcha-common/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha-pow/tsconfig.json' is up to date because newest input '../procaptcha-pow/src/index.ts' is older than output '../procaptcha-pow/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha-pow/tsconfig.json' is up to date because newest input '../procaptcha-pow/src/tests/managerHarness.ts' is older than output '../procaptcha-pow/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha-puzzle/tsconfig.json' is up to date because newest input '../procaptcha-puzzle/src/index.ts' is older than output '../procaptcha-puzzle/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha-puzzle/tsconfig.json' is up to date because newest input '../procaptcha-puzzle/src/index.ts' is older than output '../procaptcha-puzzle/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../datasets/tsconfig.json' is up to date because newest input '../datasets/src/index.ts' is older than output '../datasets/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../datasets/tsconfig.json' is up to date because newest input '../datasets/src/tests/dataset.unit.test.ts' is older than output '../datasets/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha/tsconfig.json' is up to date because newest input '../procaptcha/src/index.ts' is older than output '../procaptcha/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha/tsconfig.json' is up to date because newest input '../procaptcha/src/modules/Manager.ts' is older than output '../procaptcha/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha-react/tsconfig.json' is up to date because newest input '../procaptcha-react/src/index.ts' is older than output '../procaptcha-react/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha-react/tsconfig.json' is up to date because newest input '../procaptcha-react/src/index.ts' is older than output '../procaptcha-react/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project '../procaptcha-frictionless/tsconfig.json' is up to date because newest input '../procaptcha-frictionless/src/ProcaptchaFrictionless.tsx' is older than output '../procaptcha-frictionless/tsconfig.tsbuildinfo'
+1:15:53 PM - Project '../procaptcha-frictionless/tsconfig.json' is up to date because newest input '../procaptcha-frictionless/src/customDetectBot.ts' is older than output '../procaptcha-frictionless/tsconfig.tsbuildinfo'
 
-1:56:47 PM - Project 'tsconfig.json' is out of date because output file 'tsconfig.tsbuildinfo' does not exist
+1:15:53 PM - Project 'tsconfig.json' is out of date because output file 'tsconfig.tsbuildinfo' does not exist
 
-1:56:47 PM - Building project '/home/runner/work/captcha/captcha/packages/procaptcha-bundle/tsconfig.json'...
+1:15:53 PM - Building project '/home/runner/work/captcha/captcha/packages/procaptcha-bundle/tsconfig.json'...
 

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 
-> @prosopo/procaptcha-bundle@4.2.5 build
+> @prosopo/procaptcha-bundle@4.4.0 build
 > npm run build:cross-env -- --mode ${NODE_ENV:-development}
 
 
-> @prosopo/procaptcha-bundle@4.2.5 build:cross-env
+> @prosopo/procaptcha-bundle@4.4.0 build:cross-env
 > vite build --config vite.esm.config.ts --mode production
 
 ViteEsmConfig: .
@@ -61,19 +61,20 @@ ViteEsmConfig: .
 vite v8.1.5 building ssr environment for production...
 Bundle build started
 
-✓ 11 modules transformed.
+✓ 12 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/_virtual/_rolldown/runtime.js             0.04 kB │ gzip: 0.06 kB
-dist/util/widgetThemeResolver.js               0.55 kB │ gzip: 0.29 kB
-dist/util/timeout.js                           0.61 kB │ gzip: 0.29 kB
-dist/util/config.js                            0.62 kB │ gzip: 0.33 kB
-dist/util/captcha/components/bundleCaptcha.js  0.68 kB │ gzip: 0.35 kB
-dist/util/configCreator.js                     0.86 kB │ gzip: 0.45 kB
-dist/util/language.js                          1.01 kB │ gzip: 0.44 kB
-dist/util/clientSession.js                     1.03 kB │ gzip: 0.55 kB
-dist/util/captcha/captchaRenderer.js           2.04 kB │ gzip: 0.72 kB
-dist/util/widgetFactory.js                     2.52 kB │ gzip: 0.85 kB
-dist/index.js                                  8.85 kB │ gzip: 3.14 kB
+dist/_virtual/_rolldown/runtime.js              0.04 kB │ gzip: 0.06 kB
+dist/util/widgetThemeResolver.js                0.55 kB │ gzip: 0.29 kB
+dist/util/timeout.js                            0.61 kB │ gzip: 0.29 kB
+dist/util/config.js                             0.62 kB │ gzip: 0.33 kB
+dist/util/captcha/components/bundleCaptcha.js   0.68 kB │ gzip: 0.35 kB
+dist/util/startMode.js                          0.78 kB │ gzip: 0.39 kB
+dist/util/configCreator.js                      0.98 kB │ gzip: 0.49 kB
+dist/util/language.js                           1.01 kB │ gzip: 0.44 kB
+dist/util/clientSession.js                      1.03 kB │ gzip: 0.55 kB
+dist/util/widgetFactory.js                      2.57 kB │ gzip: 0.87 kB
+dist/util/captcha/captchaRenderer.js            2.64 kB │ gzip: 0.92 kB
+dist/index.js                                  11.43 kB │ gzip: 3.79 kB
 
-✓ built in 62ms
+✓ built in 59ms

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @prosopo/procaptcha-bundle
 
+## 4.4.0
+### Minor Changes
+
+- d288371: Let a site choose where a challenge opens, and which button triggers it.
+  
+  - `placement: "popup" | "float"`, also `data-placement`. `popup` is the default and unchanged. `float` opens the challenge directly above the widget and keeps it pinned there as the page scrolls, leaves the page usable behind it, and dismisses on Escape or an outside click. An invisible widget always uses popup.
+  - `bind: "#selector"`, also `data-bind`. The matching host-page button triggers that one widget, in visible or invisible mode. The click's default action is prevented so a submit button does not post the form before a token exists.
+  - `execute(widgetId?)`. Called with no argument every widget responds, as before. Called with the id `render()` returns, only that widget runs. Implicitly rendered invisible buttons now trigger only their own widget.
+  
+  Behaviour changes for existing widgets:
+  
+  - Escape now closes the image and puzzle challenge in both placements. For the image captcha this runs the cancel path, which fires `onClose` and restarts frictionless.
+  - Image and puzzle now present on one shared `ChallengeSurface`. Both were already portalled to `document.body`, so neither moves in the page, but the markup around them changed: the outer layer keeps `prosopo-modalOuter` for the image captcha and also carries `prosopo-challenge-surface`, and a new `prosopo-challenge-content` element sits between it and `prosopo-modalInner`. A direct-child selector such as `.prosopo-modalOuter > .prosopo-modalInner` no longer matches, and the centring transform now lives on `prosopo-challenge-content` rather than on `prosopo-modalInner`.
+  
+  `createConfig` takes a named options object.
+
+### Patch Changes
+
+- Updated dependencies [6f57ee9]
+- Updated dependencies [d288371]
+  - @prosopo/types@5.7.0
+  - @prosopo/util@3.3.9
+  - @prosopo/procaptcha-common@2.13.0
+  - @prosopo/procaptcha-frictionless@2.15.0
+  - @prosopo/dotenv@3.0.55
+
+## 4.3.0
+### Minor Changes
+
+- 80f73c1: Sites can now control when the widget starts working.
+  
+  By default the widget runs bot detection, starts the behavioural collectors and calls `/frictionless` as soon as it mounts. Rendering with `data-start-mode="manual"` (or `startMode: "manual"` in the render options) keeps all of that off the page load: the checkbox still appears immediately, at its final size, so nothing shifts, but the widget does nothing else until one of two things happens.
+  
+  - The site calls `window.procaptcha.start()`, optionally with a widget id, or dispatches a `procaptcha:start` event on `document`. The frictionless flow runs and the widget then waits for a click exactly as it does today.
+  - The visitor clicks the checkbox. The frictionless flow runs and whichever challenge the provider chooses opens straight away, carrying that click's position, so the visitor is never asked to click twice.
+  
+  Both triggers are one-shot: whichever comes first wins and the other is ignored. `window.procaptcha.execute()` also starts a manual widget, opening its challenge immediately. Widgets in the default `auto` mode are unaffected.
+
+### Patch Changes
+
+- 89dd38a: chore(deps): batch the outstanding dependabot bumps into one upgrade
+  
+  Rolls up dependabot PRs #3112, #3127-#3134 and #3159. Majors: `mongoose`
+  8 -> 9, `bson` 6 -> 7, `@noble/curves` 1 -> 2, `@polkadot/util-crypto`
+  13 -> 14, `@typegoose/auto-increment` 4 -> 5, `@babel/preset-env` 7 -> 8,
+  `@types/jsdom` 21 -> 30, `@types/bcrypt` 5 -> 6, `@actions/github` 6 -> 9,
+  `testcontainers` 11 -> 12. The rest are minor/patch.
+  
+  Code changes the majors forced:
+  - `@noble/curves` v2 requires `.js` specifiers and renamed the point API,
+    so `secp256k1.ProjectivePoint.fromHex(...).toRawBytes()` becomes
+    `secp256k1.Point.fromBytes(...).toBytes()`, `RistrettoPoint` becomes
+    `ristretto255.Point`, and `abstract/utils` moves to `utils.js`.
+  - mongoose 9 drops `RootFilterQuery` (now `QueryFilter`), no longer sets
+    `background: true` on schema indexes by default, and no longer declares
+    `id` on `Document`, which un-hid a mismatch between
+    `updateDappUserCommitment`'s `Hash` parameter and the `string` `id` it
+    filters on.
+  - mongoose 9 rejects an aggregation-pipeline update (an array) unless the
+    call passes `updatePipeline: true`, so the six pipeline writes in
+    `ProviderDatabase` now opt in explicitly.
+  - mongoose 9's `castUpdate` throws on a `$setOnInsert` key inside `$set`.
+    `storeUserImageCaptchaSolution` passed its record straight in as the
+    update, and mongoose's `moveImmutableProperties` mutates that object on
+    an upsert -- adding the very `$setOnInsert` key the record then carried
+    into `CentralDbStreamer.streamImageRecord`. Image records stopped
+    reaching the central DB (the streamer is fire-and-forget, so it only
+    logged) and signup verification returned 500. The update is now an
+    explicit `$set` over a shallow copy.
+  - `@prosopo/database` moves from mongodb 6.20 to 7.5 to match the driver
+    mongoose 9 pulls, so bson 7 is the only copy resolvable in the package.
+  - `vitest`/`@vitest/coverage-v8` go to 4.1.11 alongside dependabot's
+    `@vitest/spy` bump; leaving them at 4.1.10 installed a second copy of
+    `@vitest/spy` and broke type inference in the provider test utils.
+- Updated dependencies [89dd38a]
+- Updated dependencies [80f73c1]
+- Updated dependencies [8a670d3]
+  - @prosopo/dotenv@3.0.54
+  - @prosopo/locale@3.4.1
+  - @prosopo/procaptcha-common@2.12.6
+  - @prosopo/procaptcha-frictionless@2.14.0
+  - @prosopo/types@5.6.0
+  - @prosopo/util@3.3.8
+  - @prosopo/widget-skeleton@2.8.7
+
 ## 4.2.5
 ### Patch Changes
 

package/dist/cjs/index.cjs

@@ -3,20 +3,23 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_config = require("./util/config.cjs");
+const require_startMode = require("./util/startMode.cjs");
 const require_widgetFactory = require("./util/widgetFactory.cjs");
 const require_widgetThemeResolver = require("./util/widgetThemeResolver.cjs");
 let _prosopo_procaptcha_common = require("@prosopo/procaptcha-common");
+let _prosopo_types = require("@prosopo/types");
 let _prosopo_util = require("@prosopo/util");
 //#region src/index.ts
 var BUNDLE_NAMES = ["procaptcha.bundle.iife.js", "procaptcha.bundle.js"];
 var procaptchaWidgets = /* @__PURE__ */ new Map();
 var widgetIdCounter = 0;
 var nextWidgetId = () => `procaptcha-widget-${widgetIdCounter++}`;
-var registerWidgets = (roots, elements, renderOptions, isWeb2, invisible) => roots.map((root, index) => {
+var registerWidgets = (widgets, elements, renderOptions, isWeb2, invisible) => widgets.map(({ root, container }, index) => {
 	const id = nextWidgetId();
 	procaptchaWidgets.set(id, {
 		root,
 		element: (0, _prosopo_util.at)(elements, index),
+		target: container,
 		renderOptions,
 		isWeb2,
 		invisible
@@ -37,6 +40,7 @@ var widgetFactory = new require_widgetFactory.WidgetFactory(new require_widgetTh
 */
 var startDetectorPrefetch = (siteKey, flags) => {
 	if (!siteKey) return;
+	if (flags.startMode === _prosopo_types.StartModeEnum.manual) return;
 	Promise.all([import("@prosopo/procaptcha-frictionless"), import("@prosopo/procaptcha-common")]).then(([frictionless, common]) => {
 		frictionless.prefetchDetector(process.env.PROSOPO_DEFAULT_ENVIRONMENT, common.pickIpMode(flags), siteKey);
 	}).catch(() => void 0);
@@ -51,20 +55,26 @@ var implicitRender = async () => {
 		const web3 = firstElement.getAttribute("data-web3");
 		const ipv4 = firstElement.getAttribute("data-ipv4") === "true";
 		const ipv6 = firstElement.getAttribute("data-ipv6") === "true";
+		const startMode = require_startMode.resolveStartMode(void 0, firstElement);
 		if (!siteKey) {
 			console.error("No site key found");
 			return;
 		}
 		startDetectorPrefetch(siteKey, {
 			ipv4,
-			ipv6
+			ipv6,
+			startMode
 		});
 		const implicitRenderOptions = {
 			siteKey,
 			ipv4,
-			ipv6
+			ipv6,
+			startMode
 		};
-		registerWidgets(await widgetFactory.createWidgets(elements, implicitRenderOptions, !(web3 === "true")), elements, implicitRenderOptions, !(web3 === "true"), false);
+		registerWidgets(await widgetFactory.createWidgets(elements, implicitRenderOptions, !(web3 === "true")), elements, implicitRenderOptions, !(web3 === "true"), false).forEach((id, index) => {
+			const selector = (0, _prosopo_util.at)(elements, index).getAttribute("data-bind");
+			if (selector) bindTrigger(id, selector);
+		});
 	}
 	const invisibleButtons = Array.from(document.getElementsByClassName("procaptcha")).filter((button) => button.tagName.toLowerCase() === "button");
 	if (invisibleButtons.length) for (const button of invisibleButtons) {
@@ -72,20 +82,23 @@ var implicitRender = async () => {
 		const callback = button.getAttribute("data-callback") || "";
 		const ipv4 = button.getAttribute("data-ipv4") === "true";
 		const ipv6 = button.getAttribute("data-ipv6") === "true";
+		const startMode = require_startMode.resolveStartMode(void 0, button);
 		startDetectorPrefetch(siteKey, {
 			ipv4,
-			ipv6
+			ipv6,
+			startMode
 		});
 		const buttonRenderOptions = {
 			siteKey,
 			callback,
 			ipv4,
-			ipv6
+			ipv6,
+			startMode
 		};
-		registerWidgets(await widgetFactory.createWidgets([button], buttonRenderOptions, true, true), [button], buttonRenderOptions, true, true);
+		const [id] = registerWidgets(await widgetFactory.createWidgets([button], buttonRenderOptions, true, true), [button], buttonRenderOptions, true, true);
 		button.addEventListener("click", async (event) => {
 			event.preventDefault();
-			execute();
+			execute(id);
 		});
 	}
 };
@@ -99,11 +112,16 @@ var implicitRender = async () => {
 * factory legitimately yields nothing for an element it cannot mount into.
 */
 var render = async (element, renderOptions) => {
-	startDetectorPrefetch(renderOptions.siteKey, renderOptions);
+	startDetectorPrefetch(renderOptions.siteKey, {
+		...renderOptions,
+		startMode: require_startMode.resolveStartMode(renderOptions, element)
+	});
 	const hasInvisibleSize = Object.prototype.hasOwnProperty.call(renderOptions, "size") && renderOptions.size === "invisible";
 	const isWeb2 = !renderOptions.web3;
 	const invisible = hasInvisibleSize || element.tagName.toLowerCase() === "button";
-	return registerWidgets(await widgetFactory.createWidgets([element], renderOptions, isWeb2, invisible), [element], renderOptions, isWeb2, invisible)[0];
+	const id = registerWidgets(await widgetFactory.createWidgets([element], renderOptions, isWeb2, invisible), [element], renderOptions, isWeb2, invisible)[0];
+	if (id && renderOptions.bind) bindTrigger(id, renderOptions.bind);
+	return id;
 };
 function ready(fn) {
 	if (document && document.readyState !== "loading") {
@@ -118,8 +136,18 @@ function ready(fn) {
 		});
 	}
 }
-var execute = () => {
-	const containers = findProcaptchaContainers();
+/**
+* Starts verification. With no id the event goes to `document` and every
+* widget responds; with an id (as returned by `render()`) only that widget
+* runs.
+*/
+var execute = (widgetId) => {
+	const targeted = void 0 === widgetId ? void 0 : procaptchaWidgets.get(widgetId);
+	if (void 0 !== widgetId && !targeted) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+	const containers = targeted ? [targeted.element] : findProcaptchaContainers();
 	if (containers.length === 0) {
 		console.error("No Procaptcha containers found for execution");
 		return;
@@ -130,11 +158,59 @@ var execute = () => {
 			containerCount: containers.length,
 			timestamp: Date.now()
 		},
-		bubbles: true,
+		bubbles: !targeted,
 		cancelable: true
 	});
+	if (targeted) {
+		targeted.target.dispatchEvent(executeEvent);
+		return;
+	}
 	document.dispatchEvent(executeEvent);
 };
+/**
+* The click's default is prevented so a submit button does not post the form
+* before a token exists.
+*/
+var bindTrigger = (widgetId, selector) => {
+	const entry = procaptchaWidgets.get(widgetId);
+	if (!entry) {
+		console.error(`No Procaptcha widget found with id ${widgetId}`);
+		return;
+	}
+	const trigger = document.querySelector(selector);
+	if (!trigger) {
+		console.error(`Procaptcha: no element matches bind selector ${selector}`);
+		return;
+	}
+	entry.unbindTrigger?.();
+	const onClick = (event) => {
+		event.preventDefault();
+		execute(widgetId);
+	};
+	trigger.addEventListener("click", onClick);
+	entry.unbindTrigger = () => trigger.removeEventListener("click", onClick);
+};
+/** Starts a `startMode: "manual"` widget; omit the id to start all of them. */
+var start = (widgetId) => {
+	const ids = void 0 === widgetId ? Array.from(procaptchaWidgets.keys()) : [widgetId];
+	if (ids.length === 0) {
+		console.error("No Procaptcha widgets found to start");
+		return;
+	}
+	for (const id of ids) {
+		const entry = procaptchaWidgets.get(id);
+		if (!entry) {
+			console.error(`No Procaptcha widget found with id ${id}`);
+			continue;
+		}
+		const detail = { element: entry.element };
+		document.dispatchEvent(new CustomEvent(_prosopo_types.PROCAPTCHA_START_EVENT, {
+			detail,
+			bubbles: true,
+			cancelable: false
+		}));
+	}
+};
 function findProcaptchaContainers() {
 	const containers = [];
 	const invisibleContainers = Array.from(document.querySelectorAll("[data-size=\"invisible\"]"));
@@ -145,7 +221,7 @@ function findProcaptchaContainers() {
 	for (const container of idContainers) if (!containers.includes(container)) containers.push(container);
 	return containers;
 }
-var start = () => {
+var boot = () => {
 	const { onloadUrlCallback, renderExplicit } = require_config.extractParams(BUNDLE_NAMES);
 	let readyCalled = false;
 	if (renderExplicit !== "explicit") {
@@ -167,7 +243,7 @@ var start = () => {
 * 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
+* unmounted every root and then called `boot()`, 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
@@ -175,7 +251,7 @@ var start = () => {
 * 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
+* `boot()` 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.
 */
@@ -185,10 +261,11 @@ var reset = async (widgetId) => {
 		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, {
+		const [widget] = await widgetFactory.createWidgets([current.element], current.renderOptions, current.isWeb2, current.invisible);
+		if (widget) procaptchaWidgets.set(id, {
 			...current,
-			root
+			root: widget.root,
+			target: widget.container
 		});
 		else procaptchaWidgets.delete(id);
 	}
@@ -204,6 +281,7 @@ var remove = (widgetId) => {
 	for (const id of ids) {
 		const entry = procaptchaWidgets.get(id);
 		if (!entry) continue;
+		entry.unbindTrigger?.();
 		entry.root.unmount();
 		entry.element.innerHTML = "";
 		procaptchaWidgets.delete(id);
@@ -214,7 +292,8 @@ window.procaptcha = {
 	render,
 	reset,
 	remove,
-	execute
+	execute,
+	start
 };
 var procaptchaReadyEvent = new CustomEvent(PROCAPTCHA_READY_EVENT, {
 	detail: { timestamp: Date.now() },
@@ -222,10 +301,11 @@ var procaptchaReadyEvent = new CustomEvent(PROCAPTCHA_READY_EVENT, {
 	cancelable: false
 });
 document.dispatchEvent(procaptchaReadyEvent);
-start();
+boot();
 //#endregion
 exports.default = ready;
 exports.execute = execute;
 exports.remove = remove;
 exports.render = render;
 exports.reset = reset;
+exports.start = start;

package/dist/cjs/util/captcha/captchaRenderer.cjs

@@ -1,18 +1,36 @@
 const require_runtime = require("../../_virtual/_rolldown/runtime.cjs");
+const require_startMode = require("../startMode.cjs");
 const require_language = require("../language.cjs");
 const require_clientSession = require("../clientSession.cjs");
 const require_configCreator = require("../configCreator.cjs");
 const require_timeout = require("../timeout.cjs");
 const require_bundleCaptcha = require("./components/bundleCaptcha.cjs");
+let _prosopo_types = require("@prosopo/types");
 let _emotion_cache = require("@emotion/cache");
 _emotion_cache = require_runtime.__toESM(_emotion_cache, 1);
 let _emotion_react = require("@emotion/react");
 let react_dom_client = require("react-dom/client");
 let react_jsx_runtime = require("react/jsx-runtime");
 //#region src/util/captcha/captchaRenderer.tsx
+var resolveRequestedPlacement = (element, renderOptions) => {
+	const requested = renderOptions.placement ?? element.getAttribute("data-placement");
+	if (!requested) return void 0;
+	const parsed = _prosopo_types.Placement.safeParse(requested);
+	return parsed.success ? parsed.data : void 0;
+};
 var CaptchaRenderer = class {
 	renderCaptcha(settings, container, renderOptions, callbacks, isWeb2, i18n, invisible, widgetContainer, sourceElement) {
-		const config = require_configCreator.createConfig(renderOptions.siteKey, renderOptions.theme, renderOptions.language, isWeb2, invisible, renderOptions.userAccountAddress, renderOptions.ipv4, renderOptions.ipv6);
+		const config = require_configCreator.createConfig({
+			siteKey: renderOptions.siteKey,
+			theme: renderOptions.theme,
+			language: renderOptions.language,
+			web2: isWeb2,
+			invisible,
+			placement: resolveRequestedPlacement(sourceElement || container, renderOptions),
+			userAccountAddress: renderOptions.userAccountAddress,
+			ipv4: renderOptions.ipv4,
+			ipv6: renderOptions.ipv6
+		});
 		this.readAndValidateSettings(sourceElement || container, config, renderOptions);
 		const reactRoot = this.createReactRoot(container, settings.identifierPrefix);
 		const emotionCache = this.makeEmotionCache(settings.emotionCacheKey, container);
@@ -29,6 +47,7 @@ var CaptchaRenderer = class {
 		require_timeout.setValidChallengeLength(renderOptions, element, config);
 		require_language.setLanguage(renderOptions, element, config);
 		require_clientSession.setClientSessionId(renderOptions, element, config);
+		require_startMode.setStartMode(renderOptions, element, config);
 	}
 	makeEmotionCache(cacheKey, container) {
 		return (0, _emotion_cache.default)({

package/dist/cjs/util/configCreator.cjs

@@ -1,7 +1,8 @@
 let _prosopo_types = require("@prosopo/types");
 //#region src/util/configCreator.ts
-function createConfig(siteKey, theme = "light", language, web2 = true, invisible = false, userAccountAddress, ipv4 = false, ipv6 = false) {
-	if (!siteKey) siteKey = process.env.PROSOPO_SITE_KEY || "";
+function createConfig(options = {}) {
+	const { theme = "light", language, web2 = true, invisible = false, placement, userAccountAddress, ipv4 = false, ipv6 = false } = options;
+	const siteKey = options.siteKey || process.env.PROSOPO_SITE_KEY || "";
 	return _prosopo_types.ProcaptchaConfigSchema.parse({
 		defaultEnvironment: process.env.PROSOPO_DEFAULT_ENVIRONMENT ? _prosopo_types.EnvironmentTypesSchema.parse(process.env.PROSOPO_DEFAULT_ENVIRONMENT) : _prosopo_types.EnvironmentTypesSchema.enum.development,
 		userAccountAddress: userAccountAddress || "",
@@ -10,6 +11,7 @@ function createConfig(siteKey, theme = "light", language, web2 = true, invisible
 		mongoAtlasUri: process.env.PROSOPO_MONGO_EVENTS_URI || "",
 		web2,
 		mode: invisible ? "invisible" : "visible",
+		placement: (0, _prosopo_types.resolvePlacement)(placement, invisible),
 		theme,
 		language,
 		ipv4,

package/dist/cjs/util/startMode.cjs

@@ -0,0 +1,20 @@
+let _prosopo_types = require("@prosopo/types");
+//#region src/util/startMode.ts
+var START_MODE_ATTRIBUTE = "data-start-mode";
+var resolveStartMode = (renderOptions, element) => {
+	const requested = renderOptions?.startMode || element.getAttribute("data-start-mode");
+	if (!requested) return _prosopo_types.StartModeEnum.auto;
+	const parsed = _prosopo_types.StartModeSchema.safeParse(requested);
+	if (!parsed.success) {
+		console.error(`Ignoring unknown start mode "${requested}"; expected one of ${_prosopo_types.StartModeSchema.options.join(", ")}`);
+		return _prosopo_types.StartModeEnum.auto;
+	}
+	return parsed.data;
+};
+var setStartMode = (renderOptions, element, config) => {
+	config.startMode = resolveStartMode(renderOptions, element);
+};
+//#endregion
+exports.START_MODE_ATTRIBUTE = START_MODE_ATTRIBUTE;
+exports.resolveStartMode = resolveStartMode;
+exports.setStartMode = setStartMode;