@rozie-ui/captcha-react 0.1.3 → 0.1.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dan Krieger and Rozie.js contributors
+Copyright (c) 2026 One Learning Community LTD
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.cjs

@@ -131,7 +131,6 @@ const Captcha = (0, react.forwardRef)(function Captcha(_props, ref) {
 		const { provider, sitekey, token, theme, size, tabindex, options, defaultValue, onTokenChange, defaultToken, ...rest } = _props;
 		return rest;
 	})();
-	const disposed = (0, react.useRef)(false);
 	const api = (0, react.useRef)(null);
 	const widgetId = (0, react.useRef)(null);
 	const [token, setToken] = (0, _rozie_runtime_react.useControllableState)({
@@ -185,9 +184,9 @@ const Captcha = (0, react.forwardRef)(function Captcha(_props, ref) {
 		return widgetId.current != null && api.current && typeof api.current.getResponse === "function" ? api.current.getResponse(widgetId.current) : "";
 	}
 	(0, react.useEffect)(() => {
-		disposed.current = false;
+		let disposed = false;
 		loadCaptchaApi(props.provider).then((a) => {
-			if (disposed.current) return;
+			if (disposed) return;
 			api.current = a;
 			widgetId.current = api.current.render(widgetEl.current, buildConfig());
 		}).catch((err) => {
@@ -197,7 +196,7 @@ const Captcha = (0, react.forwardRef)(function Captcha(_props, ref) {
 			});
 		});
 		return () => {
-			disposed.current = true;
+			disposed = true;
 			if (widgetId.current == null || !api.current) return;
 			if (typeof api.current.remove === "function") api.current.remove(widgetId.current);
 			else if (typeof api.current.reset === "function") api.current.reset(widgetId.current);
@@ -315,7 +314,7 @@ const RecaptchaV3 = (0, react.forwardRef)(function RecaptchaV3(_props, ref) {
 		defaultValue: props.defaultToken ?? "",
 		onValueChange: props.onTokenChange
 	});
-	function execute$1(action = null) {
+	function execute$1(action) {
 		const a = action != null ? action : props.action;
 		return loadRecaptchaV3(props.sitekey).then(() => execute(props.sitekey, { action: a })).then((tok) => {
 			if (disposed.current) return tok;

package/dist/index.d.cts

@@ -2,14 +2,37 @@ import * as React from "react";
 
 //#region src/Captcha.d.ts
 interface CaptchaProps {
+  /**
+   * Which widget to render: `recaptcha` (Google reCAPTCHA v2), `hcaptcha`, `turnstile` (Cloudflare), or `friendly` (Friendly Captcha). The first three share a near-identical explicit-render API; Friendly Captcha rides an internal `adapt()` bridge onto the same surface. Construction-time — re-key the component to switch it live.
+   */
   provider?: string;
+  /**
+   * Required. The public site key from your provider dashboard. Identifies your site to the chosen provider.
+   */
   sitekey: string;
+  /**
+   * The verified response token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written by the widget on success and cleared on expire/reset, so reading it gives you the live response to send to your server for form submission.
+   * @example
+   * <Captcha r-model:token="token" provider="recaptcha" sitekey="…" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (next: string) => void;
+  /**
+   * Widget color theme: `light` or `dark` (all three core providers), or `auto` (Turnstile only). Construction-time — re-key the component to change it live.
+   */
   theme?: string;
+  /**
+   * Widget size. reCAPTCHA/hCaptcha accept `normal`/`compact`/`invisible`; Turnstile accepts `normal`/`compact`/`flexible`. A no-op for Friendly Captcha (its `startMode` analog rides through the `options` escape hatch instead). Construction-time.
+   */
   size?: string;
+  /**
+   * Optional tab index forwarded to the rendered widget. Omitted from the render config when left unset (`null`).
+   */
   tabindex?: (number) | null;
+  /**
+   * Escape hatch — provider-specific render options merged last (e.g. Turnstile `action`/`cData`/`retry`, hCaptcha `hl`, reCAPTCHA `badge`, Friendly Captcha `startMode`). Lets you reach keys this component does not promote to first-class props.
+   */
   options?: Record<string, unknown>;
   onVerify?: (...args: unknown[]) => void;
   onExpire?: (...args: unknown[]) => void;
@@ -24,11 +47,25 @@ declare const Captcha: React.ForwardRefExoticComponent<CaptchaProps & React.RefA
 //#endregion
 //#region src/RecaptchaV3.d.ts
 interface RecaptchaV3Props {
+  /**
+   * Required. The public reCAPTCHA v3 site key from your Google admin console.
+   */
   sitekey: string;
+  /**
+   * The default action label reported to reCAPTCHA's risk analysis (e.g. `submit`, `login`). Overridable per call via `execute(action)`.
+   */
   action?: string;
+  /**
+   * The latest verification token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written on each successful `execute()` — read it to attach the fresh token to your request.
+   * @example
+   * <RecaptchaV3 r-model:token="token" sitekey="…" action="signup" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (next: string) => void;
+  /**
+   * Opt in to running one `execute()` at mount and emitting `@verify` with the initial token. Off by default — v3 is imperative-first and tokens are short-lived (~2 min), so fetch one at the moment of submission rather than eagerly at mount.
+   */
   executeOnMount?: boolean;
   onError?: (...args: unknown[]) => void;
   onVerify?: (...args: unknown[]) => void;

package/dist/index.d.mts

@@ -2,14 +2,37 @@ import * as _$react from "react";
 
 //#region src/Captcha.d.ts
 interface CaptchaProps {
+  /**
+   * Which widget to render: `recaptcha` (Google reCAPTCHA v2), `hcaptcha`, `turnstile` (Cloudflare), or `friendly` (Friendly Captcha). The first three share a near-identical explicit-render API; Friendly Captcha rides an internal `adapt()` bridge onto the same surface. Construction-time — re-key the component to switch it live.
+   */
   provider?: string;
+  /**
+   * Required. The public site key from your provider dashboard. Identifies your site to the chosen provider.
+   */
   sitekey: string;
+  /**
+   * The verified response token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written by the widget on success and cleared on expire/reset, so reading it gives you the live response to send to your server for form submission.
+   * @example
+   * <Captcha r-model:token="token" provider="recaptcha" sitekey="…" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (token: string) => void;
+  /**
+   * Widget color theme: `light` or `dark` (all three core providers), or `auto` (Turnstile only). Construction-time — re-key the component to change it live.
+   */
   theme?: string;
+  /**
+   * Widget size. reCAPTCHA/hCaptcha accept `normal`/`compact`/`invisible`; Turnstile accepts `normal`/`compact`/`flexible`. A no-op for Friendly Captcha (its `startMode` analog rides through the `options` escape hatch instead). Construction-time.
+   */
   size?: string;
+  /**
+   * Optional tab index forwarded to the rendered widget. Omitted from the render config when left unset (`null`).
+   */
   tabindex?: (number) | null;
+  /**
+   * Escape hatch — provider-specific render options merged last (e.g. Turnstile `action`/`cData`/`retry`, hCaptcha `hl`, reCAPTCHA `badge`, Friendly Captcha `startMode`). Lets you reach keys this component does not promote to first-class props.
+   */
   options?: Record<string, any>;
   onVerify?: (...args: any[]) => void;
   onExpire?: (...args: any[]) => void;
@@ -24,11 +47,25 @@ declare const Captcha: _$react.ForwardRefExoticComponent<CaptchaProps & _$react.
 //#endregion
 //#region src/RecaptchaV3.d.ts
 interface RecaptchaV3Props {
+  /**
+   * Required. The public reCAPTCHA v3 site key from your Google admin console.
+   */
   sitekey: string;
+  /**
+   * The default action label reported to reCAPTCHA's risk analysis (e.g. `submit`, `login`). Overridable per call via `execute(action)`.
+   */
   action?: string;
+  /**
+   * The latest verification token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written on each successful `execute()` — read it to attach the fresh token to your request.
+   * @example
+   * <RecaptchaV3 r-model:token="token" sitekey="…" action="signup" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (token: string) => void;
+  /**
+   * Opt in to running one `execute()` at mount and emitting `@verify` with the initial token. Off by default — v3 is imperative-first and tokens are short-lived (~2 min), so fetch one at the moment of submission rather than eagerly at mount.
+   */
   executeOnMount?: boolean;
   onError?: (...args: any[]) => void;
   onVerify?: (...args: any[]) => void;

package/dist/index.mjs

@@ -127,7 +127,6 @@ const Captcha = forwardRef(function Captcha(_props, ref) {
 		const { provider, sitekey, token, theme, size, tabindex, options, defaultValue, onTokenChange, defaultToken, ...rest } = _props;
 		return rest;
 	})();
-	const disposed = useRef(false);
 	const api = useRef(null);
 	const widgetId = useRef(null);
 	const [token, setToken] = useControllableState({
@@ -181,9 +180,9 @@ const Captcha = forwardRef(function Captcha(_props, ref) {
 		return widgetId.current != null && api.current && typeof api.current.getResponse === "function" ? api.current.getResponse(widgetId.current) : "";
 	}
 	useEffect(() => {
-		disposed.current = false;
+		let disposed = false;
 		loadCaptchaApi(props.provider).then((a) => {
-			if (disposed.current) return;
+			if (disposed) return;
 			api.current = a;
 			widgetId.current = api.current.render(widgetEl.current, buildConfig());
 		}).catch((err) => {
@@ -193,7 +192,7 @@ const Captcha = forwardRef(function Captcha(_props, ref) {
 			});
 		});
 		return () => {
-			disposed.current = true;
+			disposed = true;
 			if (widgetId.current == null || !api.current) return;
 			if (typeof api.current.remove === "function") api.current.remove(widgetId.current);
 			else if (typeof api.current.reset === "function") api.current.reset(widgetId.current);
@@ -311,7 +310,7 @@ const RecaptchaV3 = forwardRef(function RecaptchaV3(_props, ref) {
 		defaultValue: props.defaultToken ?? "",
 		onValueChange: props.onTokenChange
 	});
-	function execute$1(action = null) {
+	function execute$1(action) {
 		const a = action != null ? action : props.action;
 		return loadRecaptchaV3(props.sitekey).then(() => execute(props.sitekey, { action: a })).then((tok) => {
 			if (disposed.current) return tok;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rozie-ui/captcha-react",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "private": false,
   "license": "MIT",
-  "description": "Idiomatic React Captcha — one Rozie source compiled to React.",
+  "description": "Idiomatic React CAPTCHA — Google reCAPTCHA (v2 + v3), hCaptcha, Cloudflare Turnstile & Friendly Captcha from one Rozie source.",
   "keywords": [
     "rozie",
     "rozie-ui",
@@ -45,7 +45,7 @@
     "src"
   ],
   "dependencies": {
-    "@rozie/runtime-react": "0.1.1"
+    "@rozie/runtime-react": "0.2.1"
   },
   "peerDependencies": {
     "react": "^18.2 || ^19",

package/src/Captcha.d.ts

@@ -3,14 +3,37 @@ import type { ForwardRefExoticComponent, RefAttributes } from 'react';
 import type * as React from 'react';
 
 export interface CaptchaProps {
+  /**
+   * Which widget to render: `recaptcha` (Google reCAPTCHA v2), `hcaptcha`, `turnstile` (Cloudflare), or `friendly` (Friendly Captcha). The first three share a near-identical explicit-render API; Friendly Captcha rides an internal `adapt()` bridge onto the same surface. Construction-time — re-key the component to switch it live.
+   */
   provider?: string;
+  /**
+   * Required. The public site key from your provider dashboard. Identifies your site to the chosen provider.
+   */
   sitekey: string;
+  /**
+   * The verified response token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written by the widget on success and cleared on expire/reset, so reading it gives you the live response to send to your server for form submission.
+   * @example
+   * <Captcha r-model:token="token" provider="recaptcha" sitekey="…" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (next: string) => void;
+  /**
+   * Widget color theme: `light` or `dark` (all three core providers), or `auto` (Turnstile only). Construction-time — re-key the component to change it live.
+   */
   theme?: string;
+  /**
+   * Widget size. reCAPTCHA/hCaptcha accept `normal`/`compact`/`invisible`; Turnstile accepts `normal`/`compact`/`flexible`. A no-op for Friendly Captcha (its `startMode` analog rides through the `options` escape hatch instead). Construction-time.
+   */
   size?: string;
+  /**
+   * Optional tab index forwarded to the rendered widget. Omitted from the render config when left unset (`null`).
+   */
   tabindex?: (number) | null;
+  /**
+   * Escape hatch — provider-specific render options merged last (e.g. Turnstile `action`/`cData`/`retry`, hCaptcha `hl`, reCAPTCHA `badge`, Friendly Captcha `startMode`). Lets you reach keys this component does not promote to first-class props.
+   */
   options?: Record<string, unknown>;
   onVerify?: (...args: unknown[]) => void;
   onExpire?: (...args: unknown[]) => void;

package/src/Captcha.tsx

@@ -7,20 +7,41 @@ import { clsx, useControllableState } from '@rozie/runtime-react';
 import { loadCaptchaApi } from './internal/loadCaptchaApi';
 
 // Live widget handle. Top-level lets → React hoists to useRef (setup-once).
-// `disposed` MUST be top-level (not declared inside $onMount): the Solid emitter
-// extracts the teardown into a separate onCleanup() whose scope can't see a
-// mount-body local, so a `let disposed` inside $onMount is out of scope in the
-// teardown (TS2304). Top-level — like api/widgetId — is visible to both.
+// `api`/`widgetId` MUST be top-level — reset()/execute()/getResponse() (the
+// $expose'd imperative handle, callable any time) read them outside $onMount.
 
 interface CaptchaProps {
+  /**
+   * Which widget to render: `recaptcha` (Google reCAPTCHA v2), `hcaptcha`, `turnstile` (Cloudflare), or `friendly` (Friendly Captcha). The first three share a near-identical explicit-render API; Friendly Captcha rides an internal `adapt()` bridge onto the same surface. Construction-time — re-key the component to switch it live.
+   */
   provider?: string;
+  /**
+   * Required. The public site key from your provider dashboard. Identifies your site to the chosen provider.
+   */
   sitekey: string;
+  /**
+   * The verified response token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written by the widget on success and cleared on expire/reset, so reading it gives you the live response to send to your server for form submission.
+   * @example
+   * <Captcha r-model:token="token" provider="recaptcha" sitekey="…" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (token: string) => void;
+  /**
+   * Widget color theme: `light` or `dark` (all three core providers), or `auto` (Turnstile only). Construction-time — re-key the component to change it live.
+   */
   theme?: string;
+  /**
+   * Widget size. reCAPTCHA/hCaptcha accept `normal`/`compact`/`invisible`; Turnstile accepts `normal`/`compact`/`flexible`. A no-op for Friendly Captcha (its `startMode` analog rides through the `options` escape hatch instead). Construction-time.
+   */
   size?: string;
+  /**
+   * Optional tab index forwarded to the rendered widget. Omitted from the render config when left unset (`null`).
+   */
   tabindex?: (number) | null;
+  /**
+   * Escape hatch — provider-specific render options merged last (e.g. Turnstile `action`/`cData`/`retry`, hCaptcha `hl`, reCAPTCHA `badge`, Friendly Captcha `startMode`). Lets you reach keys this component does not promote to first-class props.
+   */
   options?: Record<string, any>;
   onVerify?: (...args: any[]) => void;
   onExpire?: (...args: any[]) => void;
@@ -48,7 +69,6 @@ const Captcha = forwardRef<CaptchaHandle, CaptchaProps>(function Captcha(_props:
     void provider; void sitekey; void token; void theme; void size; void tabindex; void options; void defaultValue; void onTokenChange; void defaultToken;
     return rest;
   })();
-  const disposed = useRef(false);
   const api = useRef<any>(null);
   const widgetId = useRef<any>(null);
   const [token, setToken] = useControllableState({
@@ -109,9 +129,15 @@ const Captcha = forwardRef<CaptchaHandle, CaptchaProps>(function Captcha(_props:
   }
 
   useEffect(() => {
-    disposed.current = false;
+    // Mount-local (not top-level) — read only by this closure's own async
+    // .then()/.catch() and the returned teardown below. Emitter-hardening
+    // backlog item #2 (project_emitter_hardening_backlog): every target keeps
+    // a $onMount setup-local in scope for its own returned teardown, so this
+    // no longer needs the prior TOP-LEVEL-`let` workaround (unlike `api`/
+    // `widgetId` above, which stay top-level for the unrelated $expose reason).
+    let disposed = false;
     loadCaptchaApi(props.provider).then((a: any) => {
-      if (disposed.current) return;
+      if (disposed) return;
       api.current = a;
       widgetId.current = api.current.render(widgetEl.current!, buildConfig());
     }).catch((err: any) => {
@@ -121,7 +147,7 @@ const Captcha = forwardRef<CaptchaHandle, CaptchaProps>(function Captcha(_props:
       });
     });
     return () => {
-      disposed.current = true;
+      disposed = true;
       if (widgetId.current == null || !api.current) return;
       // Turnstile fully removes a widget; reCAPTCHA/hCaptcha only reset.
       if (typeof api.current.remove === 'function') api.current.remove(widgetId.current);else if (typeof api.current.reset === 'function') api.current.reset(widgetId.current);

package/src/RecaptchaV3.d.ts

@@ -3,11 +3,25 @@ import type { ForwardRefExoticComponent, RefAttributes } from 'react';
 import type * as React from 'react';
 
 export interface RecaptchaV3Props {
+  /**
+   * Required. The public reCAPTCHA v3 site key from your Google admin console.
+   */
   sitekey: string;
+  /**
+   * The default action label reported to reCAPTCHA's risk analysis (e.g. `submit`, `login`). Overridable per call via `execute(action)`.
+   */
   action?: string;
+  /**
+   * The latest verification token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written on each successful `execute()` — read it to attach the fresh token to your request.
+   * @example
+   * <RecaptchaV3 r-model:token="token" sitekey="…" action="signup" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (next: string) => void;
+  /**
+   * Opt in to running one `execute()` at mount and emitting `@verify` with the initial token. Off by default — v3 is imperative-first and tokens are short-lived (~2 min), so fetch one at the moment of submission rather than eagerly at mount.
+   */
   executeOnMount?: boolean;
   onError?: (...args: unknown[]) => void;
   onVerify?: (...args: unknown[]) => void;

package/src/RecaptchaV3.tsx

@@ -6,18 +6,34 @@ import { clsx, useControllableState } from '@rozie/runtime-react';
 // codegen copies src/internal/ into every leaf, so this import resolves ×6.
 import { loadRecaptchaV3, execute as v3Execute } from './internal/loadRecaptchaV3';
 
-// `disposed` MUST be top-level (not declared inside $onMount): the Solid emitter
-// extracts the teardown into a separate onCleanup() whose scope can't see a
-// mount-body local, so a `let disposed` inside $onMount is out of scope in the
-// teardown. Top-level — visible to both the mount body and the teardown. It also
-// guards a late execute() resolve that fires after the component unmounts.
+// `disposed` MUST be top-level (not $onMount-local): the exported `execute()`
+// below — callable any time via `$expose({ execute })`, including after
+// unmount — reads it to guard a late resolve that fires post-unmount. That
+// cross-function visibility (not a per-target emitter limitation) is why this
+// one stays top-level even after emitter-hardening backlog item #2 landed
+// (contrast Captcha.rozie's `disposed`, which IS $onMount-local — its
+// exposed handle functions don't read it).
 
 interface RecaptchaV3Props {
+  /**
+   * Required. The public reCAPTCHA v3 site key from your Google admin console.
+   */
   sitekey: string;
+  /**
+   * The default action label reported to reCAPTCHA's risk analysis (e.g. `submit`, `login`). Overridable per call via `execute(action)`.
+   */
   action?: string;
+  /**
+   * The latest verification token (two-way `r-model`). As the sole `model: true` prop it drives the Angular `ControlValueAccessor`. Written on each successful `execute()` — read it to attach the fresh token to your request.
+   * @example
+   * <RecaptchaV3 r-model:token="token" sitekey="…" action="signup" />
+   */
   token?: string;
   defaultToken?: string;
   onTokenChange?: (token: string) => void;
+  /**
+   * Opt in to running one `execute()` at mount and emitting `@verify` with the initial token. Off by default — v3 is imperative-first and tokens are short-lived (~2 min), so fetch one at the moment of submission rather than eagerly at mount.
+   */
   executeOnMount?: boolean;
   onError?: (...args: any[]) => void;
   onVerify?: (...args: any[]) => void;
@@ -52,14 +68,13 @@ const RecaptchaV3 = forwardRef<RecaptchaV3Handle, RecaptchaV3Props>(function Rec
   // ref named `token`, and a same-named param shadows it (`token.value = token`
   // would write the param). Use `tok` (mirrors Captcha.rozie's `response`).
   //
-  // `action = null` (an explicit DEFAULT, not a bare `action`) makes the param
-  // OPTIONAL — required so the no-arg call in $onMount's executeOnMount path
-  // (`execute()`) typechecks. The type-neutralizer otherwise lowers a bare param
-  // to a REQUIRED `action: any`, which Vue's strict declaration emit (vue-tsc)
-  // rejects at the `execute()` call (TS2554) — the other five targets don't
-  // body-typecheck the emitted leaf, so the issue is Vue-only but real. The
-  // default is logic-neutral: the body already guards `action != null`.
-  function execute(action = null) {
+  // A bare `action` (no author default) is fine — the emitter now lowers a
+  // TRAILING `$expose` verb param optional (`action?: any`) whenever it sees a
+  // fewer-arg internal call to the SAME verb, which the no-arg
+  // executeOnMount path (`execute()`) below is (emitter-hardening backlog
+  // item #5). The `action = null` author-side default this comment used to
+  // require is gone — the compiler owns the arity now, not this source.
+  function execute(action?: any) {
     const a = action != null ? action : props.action;
     return loadRecaptchaV3(props.sitekey).then(() => v3Execute(props.sitekey, {
       action: a