@reblu/site-next 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @reblu/site-next
 
+## 1.12.0
+
+### Minor Changes
+
+- baa36cf: Add a plug-and-play `ShopFilters` component so a SITE never hand-builds shop
+  filter UI again (REB-809) — the gap that made the dermamedicin SITE hardcode
+  `BRAND_AXIS = 'brand'` while that tenant's real axis key is `marca`.
+
+  `@reblu/site-blocks` exports `ShopFilters` (root entry, RSC-safe): one
+  fieldset per non-empty `facets.taxonomies` axis (single-select, with a
+  click-to-clear toggle on the active term — see the component's doc comment
+  for why single-select, given the current `taxonomy[<key>]` query contract), a
+  multi-select fieldset per filterable attribute, a price-band fieldset
+  (`priceBands` prop, sensible EUR defaults, also click-to-clear), and an
+  on-sale toggle. A filter selection that collapses every facet to empty still
+  renders "Clear filters" rather than nothing — also exported as the standalone
+  predicate `shouldRenderShopFilters(facets, active)`, so a consuming page can
+  gate its own wrapping landmark on the identical decision. Every option always
+  renders a real `<a href>`; `onChange` is strictly additive for a Client
+  Component caller. Price-band labels ("Under €25", "€25 – €50", "€100+") come
+  from three overridable `ShopFiltersLabels` templates (`priceUnder`,
+  `priceOver`, `priceRange`), not hardcoded English, plus `currencyCode`/
+  `locale` props matching `ProductCard`'s. Tokens only, fieldset/legend
+  semantics, `aria-current` on the active option(s), zero accessibility
+  violations (`jest-axe`).
+
+  `@reblu/site-next` exports the URL glue from two new subpaths:
+  `./shop-server` (`parseShopSearchParams`, `serializeShopParams`,
+  `toURLSearchParams`, `buildShopFilterHrefs`, `getShopCollection` — all
+  server-safe, no `'use client'`) and `./shop` (adds the client-reactive
+  `useShopFilterLinks` hook). `parseShopSearchParams`/`serializeShopParams`
+  mirror base-api's own `parseListParams` bracket shape and MVP
+  single-value-per-taxonomy-axis collapse, so a URL this SDK builds is exactly
+  the URL the server parses back — including hardening against
+  prototype-pollution-shaped bracket keys (`taxonomy[__proto__]` and friends)
+  and strict digit-only numeric parsing, while `taxonomy`/`attr` on the
+  returned `ShopProductsParams` are always guaranteed PLAIN objects (never the
+  null-prototype accumulator used internally for that hardening) — React
+  Flight refuses a null-prototype prop crossing the Server→Client Component
+  boundary, and a Client Component caller passing `active={params}` into
+  `ShopFilters`' `onChange` mode is exactly the documented usage this
+  guarantees stays safe. `toURLSearchParams` converts Next's `searchParams`
+  route prop into a `URLSearchParams`, preserving a repeated key as a repeated
+  entry (the native `URLSearchParams` constructor does not). `getShopCollection`
+  fetches products and facets with the identical params, in parallel — a
+  products failure propagates, a facets failure degrades to an empty
+  `ShopFacets` so the listing survives rather than one upstream outage taking
+  both down, logs once (`console.warn('[getShopCollection] …')`) so the
+  degradation is never silent, and the resolved `ShopCollection` carries
+  `facetsStatus: 'ok' | 'unavailable'` so a caller can tell "no filterable axes
+  configured" apart from "facets endpoint is down" without parsing a log line.
+
+### Patch Changes
+
+- Updated dependencies [baa36cf]
+  - @reblu/site-contracts@1.3.0
+
+## 1.11.0
+
+### Minor Changes
+
+- 604d464: Add `@reblu/site-next/recaptcha-provider` (REB-793): `<DeferredRecaptchaProvider>` and `useDeferredRecaptcha()` fix a defect in the REB-588 deferred-load pattern where wiring `deferredRecaptchaKey`'s return value directly into `<GoogleReCaptchaProvider reCaptchaKey={...}>` loaded Google's script with the correct site key but kept calling `executeRecaptcha` with the stale empty key from before arming — `react-google-recaptcha-v3@1.11.0` captures `reCaptchaKey` in a `useRef` on first mount and never re-reads it for invisible v3. Every token mint threw, so every contact-form submission silently failed to reach base-api. `DeferredRecaptchaProvider` applies the same validated key as both the `key` and the `reCaptchaKey` prop, forcing a full remount of the vendor provider on arm instead of a prop swap, while republishing `executeRecaptcha` through a stable context so the SITE's own form (and any in-flight submit) never remounts. `deferredRecaptchaKey` (`./recaptcha`) stays exported and unchanged — now documented `@deprecated` for direct use with `<GoogleReCaptchaProvider>` — and `react-google-recaptcha-v3` remains the consuming SITE's own optional peer dependency, never bundled into the SDK.
+
 ## 1.10.0
 
 ### Minor Changes

package/README.md

@@ -15,13 +15,18 @@ intentionally Next-coupled so the lower SDK layers —
    factory that proxies them to base-api's `/api/site/auth/*`.
 4. **`<JsonLd>`** (`./json-ld`) — safe `application/ld+json` `<script>`
    rendering; see "Structured data (JSON-LD)" below.
-5. **reCAPTCHA v3** (`./recaptcha`) — the SITE's half of the contact-form
-   captcha contract: the canonical action, the render gate, and the
-   interaction-mount key. See "reCAPTCHA v3" below.
+5. **reCAPTCHA v3** (`./recaptcha`, `./recaptcha-provider`) — the SITE's half
+   of the contact-form captcha contract: the canonical action, the render
+   gate, and a defect-fixed (REB-793) interaction-mount provider,
+   `<DeferredRecaptchaProvider>`. See "reCAPTCHA v3" below.
 6. **Academy** (`./academy`, `./academy-server`) — `AcademyEnrollmentForm`,
    the anonymous enrollment-request form, plus `deriveValidationFields` to
    build its per-tenant validation fields from course/config data. See
    "Academy" below.
+7. **Shop filters** (`./shop`, `./shop-server`) — URL ↔ `ShopProductsParams`
+   glue for `@reblu/site-blocks`'s `ShopFilters`: parse/serialize, a server
+   helper that fetches products + facets with identical params, and a
+   client-reactive navigation hook. See "Shop filters" below.
 
 ## Install
 
@@ -29,7 +34,9 @@ intentionally Next-coupled so the lower SDK layers —
 pnpm add @reblu/site-next @reblu/site-client @reblu/site-contracts @reblu/site-ui next-themes
 ```
 
-Peer deps: `react >=19`, `next >=16`, `@reblu/site-ui`, `next-themes`.
+Peer deps: `react >=19`, `next >=16`, `@reblu/site-ui`, `next-themes`, and
+optionally `react-google-recaptcha-v3` (only if you use
+`@reblu/site-next/recaptcha-provider` — see "reCAPTCHA v3" below).
 
 `next-themes` is required by the `./auth` entry as a whole, not only by
 `AuthLogo`: `tsup.config.ts` builds `auth.js`/`auth.cjs` as ONE
@@ -240,6 +247,71 @@ maps each `fieldErrors` key onto the matching input (`email`, or a
 `details`, or a `429` — renders as a single form-level error instead. No
 reCAPTCHA: the route is IP rate-limited server-side.
 
+## Shop filters
+
+`./shop-server` and `./shop` (REB-809) are the URL glue behind
+`@reblu/site-blocks`'s `ShopFilters` — see that package's README for the full
+example. Two subpaths, same split reasoning as `./academy`/`./academy-server`:
+
+| Export | Subpath | Needs `'use client'`? |
+| ------ | ------- | ---------------------- |
+| `parseShopSearchParams(searchParams): ShopProductsParams` | both | No |
+| `serializeShopParams(params): URLSearchParams` | both | No |
+| `toURLSearchParams(nextSearchParams): URLSearchParams` | both | No |
+| `buildShopFilterHrefs(current, pathname): ShopFilterHrefs` | both | No |
+| `getShopCollection(client, params?)` | both | No |
+| `useShopFilterLinks(): ShopFilterHrefs` | `./shop` only | **Yes** |
+
+`toURLSearchParams(searchParams)` converts Next's route `searchParams` prop —
+`Record<string, string | string[] | undefined>`, a repeated query key already
+grouped into an array — into the `URLSearchParams` `parseShopSearchParams`
+expects, preserving every repeated key as a repeated entry. Use it, not
+`new URLSearchParams(await searchParams)`: the native constructor only
+accepts `Record<string, string>`, so handed an array value it calls
+`String()` on it and produces ONE entry (`attr[color]=red,blue`) instead of
+two repeated ones — silently breaking `parseShopSearchParams`'s
+repeat-count-based array/scalar distinction for every multi-value
+`attr[<key>]` filter. See `@reblu/site-blocks`'s README for the full
+Server Component recipe built on this.
+
+`parseShopSearchParams`/`serializeShopParams` are a deliberate MIRROR of
+base-api's own `parseListParams`
+(`apps/base-api/src/lib/shop/catalogue-query.ts`) — same bracket shape
+(`taxonomy[<key>]=<slug>`, `attr[<key>]=<value>`, repeatable for `attr`), same
+MVP collapse of a repeated `taxonomy[<key>]` to its first value. A URL this
+module builds is exactly the URL the server parses back to the same params —
+there is no second, drifting parser. `serializeShopParams` round-trips
+through `parseShopSearchParams` for any canonical input; a single-element
+`attr` array is the one documented exception — see `params.test.ts` — because
+one `attr[key]=value` occurrence is indistinguishable from a plain scalar
+once serialized (the array/scalar distinction is carried entirely by repeat
+count). Reading it back with `Array.isArray(...) ? value : [value]` (exactly
+what `ShopFilters` does) makes the distinction invisible to a consumer.
+
+`getShopCollection(client, params)` fetches `client.shop.products(params)`
+and `client.shop.facets(params)` **with the identical params object**, in
+parallel — the seam that keeps a collection page correct. A hand-rolled page
+that calls the two endpoints with separately-derived params is exactly how a
+facet count and its product list drift apart.
+
+`products` and `facets` are not equally critical: a products failure
+propagates (`getShopCollection` rejects — there is no listing without
+products), while a facets failure degrades to an empty `ShopFacets` so the
+listing still renders, just without filter UI. That degradation is never
+silent: it logs `console.warn('[getShopCollection] facets fetch failed, …')`
+once, and the resolved `ShopCollection` carries `facetsStatus: 'ok' |
+'unavailable'` so a caller that wants to act on it (retry, surface a banner)
+can tell "this tenant configured no filterable axes" apart from "the facets
+endpoint is down right now" without parsing a log line.
+
+`buildShopFilterHrefs(current, pathname)` is pure (no `next/navigation`) — a
+Server Component calls it directly with its own `searchParams` prop and
+route pathname. Every returned href preserves every OTHER current param and
+resets pagination (`page`) — a filter change is never silently stuck on page
+4 of a now-smaller result set. `useShopFilterLinks()` is the same logic bound
+reactively to `usePathname()`/`useSearchParams()`, for a filter bar that is
+its own Client Component.
+
 ## Structured data (JSON-LD)
 
 `@reblu/site-next/json-ld` (REB-622, server-only, dependency-free) renders one
@@ -328,33 +400,76 @@ the way out of `/api/site/analytics`, or in the response contract.
 ### Load Google only when someone actually uses the form
 
 ```tsx
-import { RECAPTCHA_ACTION, deferredRecaptchaKey } from '@reblu/site-next/recaptcha'
+import { RECAPTCHA_ACTION } from '@reblu/site-next/recaptcha'
+import { DeferredRecaptchaProvider, useDeferredRecaptcha } from '@reblu/site-next/recaptcha-provider'
 
 const [armed, setArmed] = useState(false)
 
-<GoogleReCaptchaProvider reCaptchaKey={deferredRecaptchaKey(siteKey, armed)}>
+<DeferredRecaptchaProvider siteKey={siteKey} armed={armed}>
   <form onFocusCapture={() => setArmed(true)}>…</form>
-</GoogleReCaptchaProvider>
+</DeferredRecaptchaProvider>
 
-// at submit: await executeRecaptcha(RECAPTCHA_ACTION)
+// inside the form, instead of react-google-recaptcha-v3's own useGoogleReCaptcha():
+const { executeRecaptcha } = useDeferredRecaptcha()
+// at submit: await executeRecaptcha?.(RECAPTCHA_ACTION)
 ```
 
 `GoogleReCaptchaProvider` loads `api.js` the moment it mounts, so mounting it
-with the form means every visitor who merely lands on the page to read the phone
-number has contacted Google. `deferredRecaptchaKey` returns `''` until `armed`,
-and an empty key mounts the provider while injecting nothing; swapping the real
-key in re-runs the library's effect and injects it then, **without remounting
-the children** — so the visitor never loses focus or a half-typed word.
-
-Both of those are claims about the vendor's code, so they are pinned by
-`tests/recaptcha-deferred-oracle.test.tsx`, which drives the real
-`react-google-recaptcha-v3` and counts script tags in the DOM. If a future
-version injects eagerly, that test goes red rather than this README quietly
-becoming false.
+with the form means every visitor who merely lands on the page to read the
+phone number has contacted Google. `DeferredRecaptchaProvider` withholds a real
+key until `armed`, exactly like `deferredRecaptchaKey` (below) did — but see
+**REB-793** for why it does not stop there.
+
+> **REB-793 — do not wire `deferredRecaptchaKey` straight into
+> `<GoogleReCaptchaProvider>`.** That was this section's guidance before
+> REB-793 and it is a confirmed defect: `react-google-recaptcha-v3@1.11.0`
+> captures `reCaptchaKey` in a `useRef` on the FIRST render and only ever
+> reassigns it through a callback the library wires when a visible widget
+> `container` is configured — invisible v3 (no `container`, the only mode any
+> Reblu SITE uses) never triggers that path. Swapping the prop from `''` to
+> the real key therefore loads `api.js` with the correct key while
+> `executeRecaptcha` keeps sending `''` to `grecaptcha.execute` forever —
+> every token mint throws, every submission silently dies. Found 29-Sep in the
+> first real contact-form test on dermamedicin preprod: zero requests reached
+> `/api/site/contact-form`. `deferredRecaptchaKey` stays exported (see its own
+> `@deprecated` doc) because `DeferredRecaptchaProvider` calls it internally
+> and removing it would be a breaking change — but do not call it directly
+> against `<GoogleReCaptchaProvider>` yourself.
+
+`DeferredRecaptchaProvider` fixes this by applying that same validated key as
+BOTH the `key` prop and the `reCaptchaKey` prop on the vendor's
+`GoogleReCaptchaProvider`. A `key` change forces React to unmount the
+empty-key instance (which never loaded anything) and mount a brand-new one
+whose `useRef` captures the real key from its very first render — never a
+stale prop swap on a live instance. That remount is contained to an internal,
+invisible bridge component; **the SITE's own `children` — the form — never
+remounts**, because they render as a sibling under a separate, stable context
+that `useDeferredRecaptcha()` reads. A visitor's typed fields, and an
+in-flight submit awaiting `executeRecaptcha` (demo-site's own arm-on-submit
+fallback for a visitor who tabs straight to the button), both survive arming.
+
+Both the vendor's mount-vs-inject behaviour and this fix's own claims about
+key-vs-execute correctness are pinned by real end-to-end tests, not prose:
+`tests/recaptcha-deferred-oracle.test.tsx` drives the real
+`react-google-recaptcha-v3` and counts script tags in the DOM (the original
+REB-588 oracle); `tests/recaptcha-provider.test.tsx` goes one step further and
+actually calls `executeRecaptcha`, asserting `grecaptcha.execute` was invoked
+with the ARMED site key — including a negative control that reproduces the
+REB-793 bug directly against the vendor library, so this suite is proven to
+catch it if it ever comes back. If a future library version injects eagerly,
+or stops honoring `key`-based remounts, these tests go red rather than this
+README quietly becoming false.
 
 **This is not cookie consent.** Deferring the script narrows the exposure; it
 does not gate it on a lawful basis. That is REB-642.
 
+`DeferredRecaptchaProvider`/`useDeferredRecaptcha` live in their own subpath
+(`./recaptcha-provider`), separate from `./recaptcha` above, because they
+import React and `react-google-recaptcha-v3` — see "Which half lives where" —
+so `react-google-recaptcha-v3` is an OPTIONAL peer dependency of this package:
+install it yourself alongside `@reblu/site-next` (it already is, if you
+followed "Install" above).
+
 `RECAPTCHA_ACTION` is exported because reCAPTCHA v3 scores **per action**: two
 SITEs calling `executeRecaptcha('submit_form')` and `'contact_form'` build two
 unrelated score histories for the same feature.

package/dist/recaptcha-provider.cjs

@@ -0,0 +1,86 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/recaptcha-provider.tsx
+var recaptcha_provider_exports = {};
+__export(recaptcha_provider_exports, {
+  DeferredRecaptchaProvider: () => DeferredRecaptchaProvider,
+  useDeferredRecaptcha: () => useDeferredRecaptcha
+});
+module.exports = __toCommonJS(recaptcha_provider_exports);
+var import_react = require("react");
+var import_react_google_recaptcha_v3 = require("react-google-recaptcha-v3");
+
+// src/recaptcha.ts
+var RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+function isSafeRecaptchaSiteKey(value) {
+  return typeof value === "string" && RECAPTCHA_SITE_KEY_PATTERN.test(value);
+}
+function trimmed(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return text.length > 0 ? text : null;
+}
+function deferredRecaptchaKey(siteKey, armed) {
+  if (!armed) return "";
+  const key = trimmed(siteKey);
+  return key && isSafeRecaptchaSiteKey(key) ? key : "";
+}
+
+// src/recaptcha-provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var UNARMED = { executeRecaptcha: void 0 };
+var DeferredRecaptchaContext = (0, import_react.createContext)(UNARMED);
+function ExecuteBridge({
+  onChange
+}) {
+  const { executeRecaptcha } = (0, import_react_google_recaptcha_v3.useGoogleReCaptcha)();
+  (0, import_react.useEffect)(() => {
+    onChange(executeRecaptcha);
+  }, [executeRecaptcha, onChange]);
+  return null;
+}
+function DeferredRecaptchaProvider({
+  siteKey,
+  armed,
+  children,
+  ...providerProps
+}) {
+  const reCaptchaKey = deferredRecaptchaKey(siteKey, armed);
+  const [executeRecaptcha, setExecuteRecaptcha] = (0, import_react.useState)(void 0);
+  const handleChange = (0, import_react.useCallback)(
+    (fn) => setExecuteRecaptcha(() => fn),
+    []
+  );
+  const contextValue = (0, import_react.useMemo)(() => ({ executeRecaptcha }), [executeRecaptcha]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(DeferredRecaptchaContext.Provider, { value: contextValue, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_google_recaptcha_v3.GoogleReCaptchaProvider, { reCaptchaKey, ...providerProps, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ExecuteBridge, { onChange: handleChange }) }, reCaptchaKey),
+    children
+  ] });
+}
+function useDeferredRecaptcha() {
+  return (0, import_react.useContext)(DeferredRecaptchaContext);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DeferredRecaptchaProvider,
+  useDeferredRecaptcha
+});
+//# sourceMappingURL=recaptcha-provider.cjs.map

package/dist/recaptcha-provider.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recaptcha-provider.tsx","../src/recaptcha.ts"],"sourcesContent":["'use client'\n\n/**\n * `@reblu/site-next/recaptcha-provider` — the FIX for REB-793.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * THE BUG THIS EXISTS TO CLOSE\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `deferredRecaptchaKey` (`./recaptcha`, REB-588) returns `''` until `armed`,\n * on the documented claim that `<GoogleReCaptchaProvider reCaptchaKey={...}>`\n * swaps the key in later without remounting. That claim is only half true.\n * Verified directly in `react-google-recaptcha-v3@1.11.0`'s own dist\n * (`dist/react-google-recaptcha-v3.esm.js`):\n *\n *     var x = useRef(reCaptchaKey)           // captured ONCE, on first mount\n *     …\n *     window[onLoadCallbackName] = () => { x.current = grecaptcha.render(…) }\n *     …\n *     executeRecaptcha = () => grecaptcha.execute(x.current, { action })\n *\n * `x.current` is reassigned ONLY inside the `onLoadCallbackName` global the\n * library wires into the script URL's `&onload=` query param — and that param\n * is only added when `render === 'explicit'`, i.e. when a visible widget\n * `container` is configured. Invisible v3 (no `container`, the ONLY mode this\n * SDK or any Reblu SITE uses) never sets that param, so `x.current` never\n * updates: every `executeRecaptcha()` call keeps sending the EMPTY first-mount\n * key to `grecaptcha.execute('', { action })`, which throws, which the SITE's\n * submit handler swallows into \"reCAPTCHA no está disponible\" — no token,\n * every submission dead on arrival. Found 29-Sep in the first real\n * contact-form test on dermamedicin preprod: zero requests ever reached\n * `/api/site/contact-form`.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * THE FIX — REMOUNT THE VENDOR, NOT THE SITE'S FORM\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `useRef`'s initial value is captured on FIRST MOUNT and nothing short of\n * unmounting-and-remounting the element changes that — the vendor gives us no\n * other hook. So the element that eventually loads Google's script must never\n * have been mounted with any key other than the real one: `key={reCaptchaKey}`\n * on `<GoogleReCaptchaProvider>` does exactly that. React treats a `key`\n * change as a different element identity and discards the old subtree instead\n * of re-rendering it, so arming does not swap a prop on a live instance — it\n * unmounts the empty-key instance (which never loaded anything, so there is\n * nothing to tear down) and mounts a BRAND NEW one whose `useRef` captures the\n * real key from its very first render.\n *\n * A first version of this fix put the SITE's own `children` directly inside\n * that keyed element. It closes the ref bug, but it also means the SITE's\n * form — every typed field, and any in-flight submit closure reading\n * `executeRecaptcha` — gets unmounted and remounted at the exact moment arming\n * happens. For the common case (arm on first focus, before any text exists)\n * that only costs a moment of focus. For demo-site's actual \"visitor tabs\n * straight to submit\" fallback (`waitForRecaptchaReady` in\n * `contact-form.section.tsx`) it is fatal: arming happens FROM INSIDE the\n * form's own submit handler, so remounting the form destroys the very\n * component instance that is awaiting the result — the typed values vanish\n * and the poll never resolves, reproduced by\n * `contact-form.section.recaptcha-submit.test.tsx` going red under that\n * design.\n *\n * So the vendor `<GoogleReCaptchaProvider>` here wraps ONLY an invisible\n * bridge component, never the SITE's `children`. The bridge reads the\n * vendor's `useGoogleReCaptcha()` — correct by construction, because it lives\n * inside the freshly, correctly keyed instance — and republishes\n * `executeRecaptcha` into `DeferredRecaptchaContext`, a context on a STABLE\n * element that is never keyed and never remounts. `children` renders as a\n * SIBLING of the vendor provider, under that stable context, and consumes the\n * function via `useDeferredRecaptcha()` (this module's own replacement for\n * the vendor's `useGoogleReCaptcha()`). Arming remounts the invisible bridge;\n * it never touches the SITE's form.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY THIS IS A SEPARATE SUBPATH, NOT PART OF `./recaptcha`\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `./recaptcha` is guarded by `tests/recaptcha-subpath-isolation.test.ts` to\n * import NOTHING — not React, not `react-google-recaptcha-v3` — so a Server\n * Component can call `resolveContactFormAvailability` without paying for\n * Google's loader library. This component unavoidably imports both. Same R4\n * rule as `auth`/`academy`/`consent`: a `'use client'` directive is only\n * preserved by esbuild when the ENTRY FILE itself declares it, never when\n * merely re-exported — so this file is tsup's OWN entry (`recaptcha-provider`\n * in `../tsup.config.ts`), not folded into `./recaptcha` or the root barrel.\n *\n * `react-google-recaptcha-v3` stays the consuming SITE's OWN dependency\n * (an optional `peerDependencies` entry here, exactly as `./recaptcha`'s\n * README section already promises) — this package never bundles it.\n */\nimport {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ComponentProps,\n  type ReactNode,\n} from 'react'\nimport { GoogleReCaptchaProvider, useGoogleReCaptcha } from 'react-google-recaptcha-v3'\n\nimport { deferredRecaptchaKey } from './recaptcha'\n\n/** The one thing a SITE needs, in the same shape the vendor's own hook returns it. */\nexport interface DeferredRecaptchaContextValue {\n  /** `undefined` until Google's script has loaded under the ARMED key. */\n  executeRecaptcha: ((action?: string) => Promise<string>) | undefined\n}\n\nconst UNARMED: DeferredRecaptchaContextValue = { executeRecaptcha: undefined }\n\nconst DeferredRecaptchaContext = createContext<DeferredRecaptchaContextValue>(UNARMED)\n\n/**\n * Lives INSIDE the keyed vendor provider — the only place the vendor's own\n * `executeRecaptcha` is ever correct — and republishes it to the stable\n * context above. Renders nothing; it is pure plumbing.\n */\nfunction ExecuteBridge({\n  onChange,\n}: {\n  onChange: (fn: DeferredRecaptchaContextValue['executeRecaptcha']) => void\n}) {\n  const { executeRecaptcha } = useGoogleReCaptcha()\n  useEffect(() => {\n    onChange(executeRecaptcha)\n  }, [executeRecaptcha, onChange])\n  return null\n}\n\ntype ProviderPassthroughProps = Omit<\n  ComponentProps<typeof GoogleReCaptchaProvider>,\n  'reCaptchaKey' | 'children'\n>\n\nexport interface DeferredRecaptchaProviderProps extends ProviderPassthroughProps {\n  /** The tenant's public reCAPTCHA site key — `resolveContactFormAvailability`'s `recaptchaSiteKey`. */\n  siteKey: string\n  /** Whether the visitor has interacted with the form yet (REB-588 arming signal). */\n  armed: boolean\n  children: ReactNode\n}\n\n/**\n * Drop-in replacement for wiring `deferredRecaptchaKey` directly into\n * `<GoogleReCaptchaProvider reCaptchaKey={...}>` — see the module docs above\n * for why that direct wiring never mints a real token. Pair with\n * `useDeferredRecaptcha()` instead of the vendor's `useGoogleReCaptcha()`.\n *\n * ```tsx\n * <DeferredRecaptchaProvider siteKey={siteKey} armed={armed}>\n *   <form onFocusCapture={arm} onPointerDown={arm}>…</form>\n * </DeferredRecaptchaProvider>\n * ```\n */\nexport function DeferredRecaptchaProvider({\n  siteKey,\n  armed,\n  children,\n  ...providerProps\n}: DeferredRecaptchaProviderProps) {\n  const reCaptchaKey = deferredRecaptchaKey(siteKey, armed)\n  const [executeRecaptcha, setExecuteRecaptcha] =\n    useState<DeferredRecaptchaContextValue['executeRecaptcha']>(undefined)\n\n  // No separate \"reset to undefined on key change\" effect is needed here,\n  // and deliberately so: `reCaptchaKey` changing remounts `ExecuteBridge`\n  // (it lives inside the keyed `GoogleReCaptchaProvider`), and a FRESH bridge\n  // instance's very first effect run already reports the fresh instance's\n  // own `executeRecaptcha` — `undefined` until that instance's own script has\n  // loaded, never a value carried over from the instance that just unmounted.\n  // An extra reset effect on THIS component was tried and reverted: as the\n  // parent, its effects fire AFTER its children's on the same commit, so it\n  // clobbered the bridge's own report back to `undefined` on every mount —\n  // caught by `contact-form.section.test.tsx`, whose mocked\n  // `useGoogleReCaptcha()` reports a working function synchronously.\n  const handleChange = useCallback(\n    (fn: DeferredRecaptchaContextValue['executeRecaptcha']) => setExecuteRecaptcha(() => fn),\n    [],\n  )\n\n  // Memoized so every consumer of `useDeferredRecaptcha()` re-renders only\n  // when `executeRecaptcha` itself actually changes, not on every render of\n  // this provider (e.g. from an unrelated `providerProps` change).\n  const contextValue = useMemo(() => ({ executeRecaptcha }), [executeRecaptcha])\n\n  return (\n    <DeferredRecaptchaContext.Provider value={contextValue}>\n      <GoogleReCaptchaProvider key={reCaptchaKey} reCaptchaKey={reCaptchaKey} {...providerProps}>\n        <ExecuteBridge onChange={handleChange} />\n      </GoogleReCaptchaProvider>\n      {children}\n    </DeferredRecaptchaContext.Provider>\n  )\n}\n\n/**\n * The SITE's replacement for `react-google-recaptcha-v3`'s own\n * `useGoogleReCaptcha()` when the form is wrapped in\n * `<DeferredRecaptchaProvider>`. Same shape (`{ executeRecaptcha }`), but\n * reads the STABLE context republished by `ExecuteBridge`, which never\n * remounts on arm — unlike the vendor's own context, which lives on the\n * element `DeferredRecaptchaProvider` deliberately keys and remounts.\n */\nexport function useDeferredRecaptcha(): DeferredRecaptchaContextValue {\n  return useContext(DeferredRecaptchaContext)\n}\n","/**\n * reCAPTCHA v3 — the SITE's half of the contract (REB-588).\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHICH HALF LIVES WHERE, AND WHY\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * reCAPTCHA is two secrets and two steps, and they are deliberately split across\n * a trust boundary:\n *\n *   SITE KEY  — public by design. It ships to the browser inside the script URL,\n *               so the tenant serves it from `/api/site/analytics`. This module\n *               handles it.\n *   SECRET    — never leaves base-api. It is stored per tenant in\n *               `site_integration_config.recaptchaSecretKey` and read only by\n *               `serverCaptchaVerify` when `POST /api/site/contact-form` runs.\n *\n * **Nothing in this module, in this package, or anywhere in the `@reblu/site-*`\n * SDK ever sees the secret, and nothing here calls Google's `siteverify`.** A\n * SITE holding the secret would be a SITE that could be tricked into approving\n * its own tokens, and a distributable SDK is the worst possible place to put a\n * credential. Verification is base-api's job and already works: the SITE mints a\n * token, posts it as `ContactFormInput.captcha`, and base-api decides.\n *\n * That is also why this module is NOT \"reCAPTCHA support\" in the round. It is\n * the three decisions every SITE was otherwise making alone and differently:\n * which action to name, whether a form may be shown at all, and when Google's\n * script is allowed to load.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHY IT IS IN THE SDK AT ALL\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * Because it was already being written four times. `apps/base-api`,\n * `apps/demo-site` and the external `reblu-site-dermamedicin` each grew their\n * own copy of this flow, and they had already drifted — different action\n * strings, different mount timing, a retry loop in one of them. A score that\n * reCAPTCHA reports per action is not comparable across SITEs that name the\n * action differently, and a defect fixed in one copy stays live in the other\n * two. The SDK is where a decision gets made once.\n *\n * This module has ZERO runtime dependencies and imports nothing — not React, not\n * `next`, not `react-google-recaptcha-v3`, not `@reblu/site-ui`. It is pure\n * functions over plain data, callable from a Server Component deciding whether\n * to render a form and from the Client Component that renders it. The subpath is\n * kept dependency-free by `tests/recaptcha-subpath-isolation.test.ts`.\n */\n\nimport type { Analytics, ContactFormMode } from '@reblu/site-contracts'\n\n/**\n * The action name every Reblu SITE mints its contact-form token under.\n *\n * reCAPTCHA v3 scores PER ACTION, and a score is only interpretable against a\n * stable one: Google's own admin console charts each action separately, and a\n * threshold tuned on one action says nothing about another. Two SITEs calling\n * `executeRecaptcha('submit_form')` and `executeRecaptcha('contact_form')` are\n * building two unrelated score histories for the same feature — which is exactly\n * the state the repo was in before this constant existed.\n *\n * `contact_form` over `submit_form` because it names the form, not the verb;\n * a second protected form would need its own action, and `submit_form` would\n * have nothing left to call it.\n *\n * ── WHAT THIS CONSTANT DOES **NOT** BUY, STATED PLAINLY ──\n *\n * It buys comparable scores. It does NOT bind a token to this form, because\n * `serverCaptchaVerify` in base-api checks only `success` and `score`, and never\n * reads the `action` field Google returns. A token minted for any other action\n * on the same site verifies here exactly as well. Making the action load-bearing\n * requires base-api to assert `action === RECAPTCHA_ACTION` on verify; until it\n * does, do not read this constant as a security control.\n */\nexport const RECAPTCHA_ACTION = 'contact_form'\n\n/**\n * The shape a site key must have before this SDK will hand it to Google.\n *\n * ── WHAT THIS IS, AND EMPHATICALLY WHAT IT IS NOT ──\n *\n * It is a SINK-SAFETY guard, not a guess at Google's key format. The key is\n * interpolated into the loader's script URL as a query parameter, so what\n * matters here is that it cannot carry a space, a quote, a newline, an `&`, or a\n * `#` — characters that make a URL mean something other than what was intended.\n * The base64url alphabet Google actually issues from (`A-Z a-z 0-9 - _`) is a\n * strict subset of \"safe\", so a real key passes by construction.\n *\n * The length bounds are deliberately far wider than any key Google issues\n * (theirs are 40 characters). A bound tight enough to be a real format check\n * would be a bound tight enough to take a WORKING tenant's contact form offline\n * the day Google changes its key length — which is strictly worse than the\n * malformed key it was meant to catch. If you are tempted to tighten this,\n * the thing to tighten is the nexus write path, where an owner can still see\n * and fix the error, not this read path where they cannot.\n *\n * ── WHY THE SDK RE-VALIDATES AT ALL ──\n *\n * Same reason `@reblu/site-next/analytics` re-checks `gaId` and `clarityId`\n * (REB-617): base-api is not the only thing a SITE ever talks to, and the layer\n * that owns the value is not the layer that suffers from it being wrong. As of\n * REB-588 this column has NO validation anywhere — not in the nexus form, not on\n * the way out of `/api/site/analytics`, not in the response contract, which is\n * the one asymmetry `gaId`/`clarityId` do not share. Until that is fixed\n * upstream, this is the only guard between a mistyped key and a contact form\n * that renders, looks live, and silently eats every enquiry.\n */\nexport const RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/\n\n/**\n * Whether `value` is a site key safe to put in the loader's script URL.\n *\n * Takes `unknown` on purpose: the value arrives over HTTP, so the contract's\n * `string | null` is a promise about the shape, not a guarantee about the bytes.\n */\nexport function isSafeRecaptchaSiteKey(value: unknown): value is string {\n  return typeof value === 'string' && RECAPTCHA_SITE_KEY_PATTERN.test(value)\n}\n\n/**\n * The modes in which base-api will actually accept a submission.\n *\n * An ALLOW-LIST, never `mode !== 'DISABLED'`. The three differ only in what\n * base-api DOES with the payload — a row, a webhook, an email — and the SITE\n * must not care and must never learn the destination: a webhook URL or a Resend\n * key is a tenant secret with no business in a public site.\n *\n * The deny-list version of this is a real incident, not a hypothetical: a page\n * that hid the form on `DISABLED` and rendered it otherwise rendered it for\n * `NOT_CONFIGURED` too — which is what EVERY freshly provisioned tenant carries\n * until someone finishes the wizard (REB-586). A visitor typed out a medical\n * enquiry, pressed send, and got `503 Contact form is disabled`. They learned\n * the clinic could not be reached only after writing to it.\n */\nexport const CONTACT_FORM_OPERATIONAL_MODES = ['DB_ONLY', 'WEBHOOK', 'RESEND'] as const\n\n/** A mode in which the form may be shown. */\nexport type ContactFormOperationalMode = (typeof CONTACT_FORM_OPERATIONAL_MODES)[number]\n\n/**\n * The modes deliberately declined. A TYPE, never a value: the runtime must never\n * read it, because an allow-list must not be expressible as \"everything except\n * this list\", and this subpath's defining property is that it ships nothing it\n * does not need. It exists only to feed {@link ContactFormModeExhaustiveCheck}.\n */\ntype DeclinedMode = 'NOT_CONFIGURED' | 'DISABLED'\n\n/**\n * Compile-time exhaustiveness guard over `ContactFormMode`.\n *\n * `Missing` is constrained to `never` and DEFAULTS to the contract modes that\n * are neither accepted nor explicitly declined, so a default violating its own\n * constraint breaks the build the moment `@reblu/site-contracts` gains a mode.\n *\n * At runtime a new mode already fails closed, which is correct but SILENT — and\n * silence is how a tenant switches their form on in nexus and watches nothing\n * appear. This forces a human to make the call in a diff instead.\n *\n * Exported so it is never reported as an unused symbol.\n */\nexport type ContactFormModeExhaustiveCheck<\n  Missing extends never = Exclude<ContactFormMode, ContactFormOperationalMode | DeclinedMode>,\n> = Missing\n\n/** Why the form is not being shown. Drives diagnostics, never visitor-facing copy. */\nexport type ContactFormUnavailableReason =\n  /** The analytics read failed or was never made — no answer at all. */\n  | 'unreadable'\n  /** The tenant's mode is not one base-api accepts submissions in. */\n  | 'mode-not-operational'\n  /** Accepting mode, but no site key: the browser cannot mint a token. */\n  | 'missing-recaptcha-key'\n  /** A site key is present but cannot be a key — see {@link RECAPTCHA_SITE_KEY_PATTERN}. */\n  | 'malformed-recaptcha-key'\n\nexport type ContactFormAvailability =\n  /**\n   * Confirmed: base-api accepts submissions AND a usable site key exists. The\n   * key travels inside the `available` case on purpose — a component that has\n   * proven the form may render should not have to re-read (and re-null-check)\n   * the payload to find out what to render it WITH.\n   */\n  | { state: 'available'; mode: ContactFormOperationalMode; recaptchaSiteKey: string }\n  | { state: 'unavailable'; reason: ContactFormUnavailableReason }\n\n/** Whitespace-only is absent — a key someone saved blank is not a key. */\nfunction trimmed(value: unknown): string | null {\n  if (typeof value !== 'string') return null\n  const text = value.trim()\n  return text.length > 0 ? text : null\n}\n\nfunction isOperationalMode(mode: unknown): mode is ContactFormOperationalMode {\n  // Widened to `unknown` deliberately: see isSafeRecaptchaSiteKey. A base-api\n  // newer than this SDK sends a string TypeScript has never heard of, and it\n  // must fail closed rather than be assumed accepting.\n  return (CONTACT_FORM_OPERATIONAL_MODES as readonly string[]).includes(mode as string)\n}\n\n/**\n * Resolve whether a contact form may be rendered for this tenant.\n *\n * We offer what we can CONFIRM, never what we have merely failed to disprove: an\n * unknown mode, a mode from a runtime newer than this build, and a config read\n * that threw all resolve to the same answer — no form. The page still shows the\n * phone, the email and the address, so a hidden form costs a visitor one extra\n * glance; a form that eats their message costs them the message.\n *\n * Order matters. The mode is checked BEFORE the key, because \"the tenant has not\n * switched the form on\" is the actionable half of a double failure — a site key\n * for a form nobody enabled is not the problem to fix first.\n */\nexport function resolveContactFormAvailability(\n  analytics: Analytics | null | undefined,\n): ContactFormAvailability {\n  if (!analytics) return { state: 'unavailable', reason: 'unreadable' }\n\n  const mode = analytics.contactFormMode\n  if (!isOperationalMode(mode)) return { state: 'unavailable', reason: 'mode-not-operational' }\n\n  // `ContactFormInput.captcha` is REQUIRED and base-api verifies it, so an\n  // accepting mode with no usable key is still a form whose every submission is\n  // dead on arrival. \"Missing\" and \"malformed\" are separated because they call\n  // for different fixes by different people: one owner never filled the field,\n  // the other filled it with the wrong thing.\n  const recaptchaSiteKey = trimmed(analytics.recaptchaSiteKey)\n  if (!recaptchaSiteKey) return { state: 'unavailable', reason: 'missing-recaptcha-key' }\n  if (!isSafeRecaptchaSiteKey(recaptchaSiteKey)) {\n    return { state: 'unavailable', reason: 'malformed-recaptcha-key' }\n  }\n\n  return { state: 'available', mode, recaptchaSiteKey }\n}\n\n/** Narrowing helper — the single question a renderer should ask. */\nexport function isContactFormAvailable(\n  availability: ContactFormAvailability,\n): availability is Extract<ContactFormAvailability, { state: 'available' }> {\n  return availability.state === 'available'\n}\n\n/**\n * The key to hand `GoogleReCaptchaProvider` on this render — `''` until `armed`.\n *\n * @deprecated **Wiring this return value directly into\n * `<GoogleReCaptchaProvider reCaptchaKey={deferredRecaptchaKey(siteKey, armed)}>`\n * is the exact REB-793 bug**: `react-google-recaptcha-v3@1.11.0` captures\n * `reCaptchaKey` in a `useRef` on FIRST MOUNT and never re-reads the prop for\n * invisible v3 (no visible `container`), so `executeRecaptcha` keeps sending\n * the STALE `''` from before arming to `grecaptcha.execute` forever — the\n * script loads with the right key, but every token mint throws, and every\n * contact-form submission is silently dead on arrival. Verified on\n * dermamedicin preprod 29-Sep: zero requests ever reached\n * `/api/site/contact-form`. Use `DeferredRecaptchaProvider` from\n * `@reblu/site-next/recaptcha-provider` instead — it applies this exact same\n * value as BOTH the `key` and the `reCaptchaKey` prop, which forces a full\n * remount on arm instead of a prop swap, so the mounted instance's `useRef`\n * never sees any key but the real one. This function stays exported,\n * unchanged, because `DeferredRecaptchaProvider` calls it internally and\n * external SITEs may already depend on its signature for other purposes\n * (e.g. rendering their own diagnostics) — this is a documentation-only\n * deprecation, not a behavior or breaking change.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * WHAT THIS BUYS\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `GoogleReCaptchaProvider` loads Google's `api.js` the moment it MOUNTS. Mount\n * it with the form and every visitor who merely lands on the page to read the\n * phone number has contacted Google — on a clinic's contact page, a third-party\n * request nobody asked for, on a route whose whole subject is personal data.\n *\n * Arming on first interaction with the form (focus, first keystroke) means\n * Google is contacted only for a visitor who is actually about to submit, which\n * is the only visitor whose token is worth anything. It is a smaller page, a\n * faster one, and a materially smaller consent surface.\n *\n * **This is NOT a cookie-consent implementation.** Deferring the script narrows\n * the exposure; it does not gate it on a lawful basis. Full consent gating for\n * third parties is REB-642 and has its own owner.\n *\n * ─────────────────────────────────────────────────────────────────────────────\n * HOW, WITHOUT A HACK — MEASURED, NOT ASSUMED\n * ─────────────────────────────────────────────────────────────────────────────\n *\n * `react-google-recaptcha-v3` injects the script from an effect shaped\n *\n *     useEffect(() => { if (reCaptchaKey) { …inject…; return cleanup } … },\n *               [ …, reCaptchaKey, … ])\n *\n * Two facts fall out, and together they are the whole mechanism:\n *\n *   1. An EMPTY key mounts the provider and injects NOTHING.\n *   2. `reCaptchaKey` is a dependency, so swapping the real key in later re-runs\n *      the effect and injects the script then.\n *\n * Crucially the provider element never leaves the tree, so its children are\n * never remounted merely because `reCaptchaKey` changed on a LIVE instance:\n * no imperative script injection, no reaching into the DOM, no fork.\n *\n * **This describes script LOADING only, not token MINTING.** REB-793 found\n * the gap: the same swapped prop that safely re-runs this effect is also\n * where `react-google-recaptcha-v3` caches `reCaptchaKey` in a `useRef` — set\n * once, on first mount, and (for invisible v3) never reassigned. The script\n * loads with the swapped-in real key; `executeRecaptcha` keeps sending the\n * key from BEFORE the swap. Wiring this function's return value straight\n * into `<GoogleReCaptchaProvider reCaptchaKey={...}>`, the pattern this\n * whole comment used to recommend, is exactly that bug — see the\n * `@deprecated` note above and `@reblu/site-next/recaptcha-provider`'s\n * `DeferredRecaptchaProvider`, which fixes it by forcing a real remount\n * instead of relying on this same prop swap.\n *\n * Both facts are pinned by `tests/recaptcha-deferred-oracle.test.tsx`, which\n * drives the REAL library and counts script tags in the DOM. They are claims\n * about someone else's code, so prose asserting them is not enough — if a future\n * version of the library injects eagerly, that test goes red and this whole\n * optimisation is known to be void.\n *\n * ── THE ONE COST, MEASURED ──\n *\n * On the empty-key render the library calls its own warn helper, which is\n * written inverted, so the warning fires in PRODUCTION and stays silent in\n * development. A visitor who opens devtools before touching a field sees one\n * `\"<GoogleReCaptchaProvider /> recaptcha key not provided\"`. Cosmetic console\n * noise, traded against a third-party request on every view of the page. Worth\n * it, and recorded here so the next reader knows it is expected.\n *\n * ── AND NO FALLBACK KEY, EVER ──\n *\n * `''` for a blank OR malformed key however armed. There is no hardcoded\n * fallback anywhere in this module, because a captcha key that is not the\n * tenant's fails Google's verification while LOOKING configured — converting a\n * visible gap an owner can fix in nexus into a silent one nobody can.\n * {@link resolveContactFormAvailability} hides the form in that case; this is\n * the second lock on the same door.\n */\nexport function deferredRecaptchaKey(siteKey: string, armed: boolean): string {\n  if (!armed) return ''\n  const key = trimmed(siteKey)\n  return key && isSafeRecaptchaSiteKey(key) ? key : ''\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0FA,mBASO;AACP,uCAA4D;;;ACMrD,IAAM,6BAA6B;AAQnC,SAAS,uBAAuB,OAAiC;AACtE,SAAO,OAAO,UAAU,YAAY,2BAA2B,KAAK,KAAK;AAC3E;AAqEA,SAAS,QAAQ,OAA+B;AAC9C,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,OAAO,MAAM,KAAK;AACxB,SAAO,KAAK,SAAS,IAAI,OAAO;AAClC;AAkJO,SAAS,qBAAqB,SAAiB,OAAwB;AAC5E,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,MAAM,QAAQ,OAAO;AAC3B,SAAO,OAAO,uBAAuB,GAAG,IAAI,MAAM;AACpD;;;ADvJI;AA9EJ,IAAM,UAAyC,EAAE,kBAAkB,OAAU;AAE7E,IAAM,+BAA2B,4BAA6C,OAAO;AAOrF,SAAS,cAAc;AAAA,EACrB;AACF,GAEG;AACD,QAAM,EAAE,iBAAiB,QAAI,qDAAmB;AAChD,8BAAU,MAAM;AACd,aAAS,gBAAgB;AAAA,EAC3B,GAAG,CAAC,kBAAkB,QAAQ,CAAC;AAC/B,SAAO;AACT;AA2BO,SAAS,0BAA0B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAmC;AACjC,QAAM,eAAe,qBAAqB,SAAS,KAAK;AACxD,QAAM,CAAC,kBAAkB,mBAAmB,QAC1C,uBAA4D,MAAS;AAavE,QAAM,mBAAe;AAAA,IACnB,CAAC,OAA0D,oBAAoB,MAAM,EAAE;AAAA,IACvF,CAAC;AAAA,EACH;AAKA,QAAM,mBAAe,sBAAQ,OAAO,EAAE,iBAAiB,IAAI,CAAC,gBAAgB,CAAC;AAE7E,SACE,6CAAC,yBAAyB,UAAzB,EAAkC,OAAO,cACxC;AAAA,gDAAC,4DAA2C,cAA6B,GAAG,eAC1E,sDAAC,iBAAc,UAAU,cAAc,KADX,YAE9B;AAAA,IACC;AAAA,KACH;AAEJ;AAUO,SAAS,uBAAsD;AACpE,aAAO,yBAAW,wBAAwB;AAC5C;","names":[]}

package/dist/recaptcha-provider.d.cts

@@ -0,0 +1,41 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentProps, ReactNode } from 'react';
+import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
+
+/** The one thing a SITE needs, in the same shape the vendor's own hook returns it. */
+interface DeferredRecaptchaContextValue {
+    /** `undefined` until Google's script has loaded under the ARMED key. */
+    executeRecaptcha: ((action?: string) => Promise<string>) | undefined;
+}
+type ProviderPassthroughProps = Omit<ComponentProps<typeof GoogleReCaptchaProvider>, 'reCaptchaKey' | 'children'>;
+interface DeferredRecaptchaProviderProps extends ProviderPassthroughProps {
+    /** The tenant's public reCAPTCHA site key — `resolveContactFormAvailability`'s `recaptchaSiteKey`. */
+    siteKey: string;
+    /** Whether the visitor has interacted with the form yet (REB-588 arming signal). */
+    armed: boolean;
+    children: ReactNode;
+}
+/**
+ * Drop-in replacement for wiring `deferredRecaptchaKey` directly into
+ * `<GoogleReCaptchaProvider reCaptchaKey={...}>` — see the module docs above
+ * for why that direct wiring never mints a real token. Pair with
+ * `useDeferredRecaptcha()` instead of the vendor's `useGoogleReCaptcha()`.
+ *
+ * ```tsx
+ * <DeferredRecaptchaProvider siteKey={siteKey} armed={armed}>
+ *   <form onFocusCapture={arm} onPointerDown={arm}>…</form>
+ * </DeferredRecaptchaProvider>
+ * ```
+ */
+declare function DeferredRecaptchaProvider({ siteKey, armed, children, ...providerProps }: DeferredRecaptchaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * The SITE's replacement for `react-google-recaptcha-v3`'s own
+ * `useGoogleReCaptcha()` when the form is wrapped in
+ * `<DeferredRecaptchaProvider>`. Same shape (`{ executeRecaptcha }`), but
+ * reads the STABLE context republished by `ExecuteBridge`, which never
+ * remounts on arm — unlike the vendor's own context, which lives on the
+ * element `DeferredRecaptchaProvider` deliberately keys and remounts.
+ */
+declare function useDeferredRecaptcha(): DeferredRecaptchaContextValue;
+
+export { type DeferredRecaptchaContextValue, DeferredRecaptchaProvider, type DeferredRecaptchaProviderProps, useDeferredRecaptcha };

package/dist/recaptcha-provider.d.ts

@@ -0,0 +1,41 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentProps, ReactNode } from 'react';
+import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
+
+/** The one thing a SITE needs, in the same shape the vendor's own hook returns it. */
+interface DeferredRecaptchaContextValue {
+    /** `undefined` until Google's script has loaded under the ARMED key. */
+    executeRecaptcha: ((action?: string) => Promise<string>) | undefined;
+}
+type ProviderPassthroughProps = Omit<ComponentProps<typeof GoogleReCaptchaProvider>, 'reCaptchaKey' | 'children'>;
+interface DeferredRecaptchaProviderProps extends ProviderPassthroughProps {
+    /** The tenant's public reCAPTCHA site key — `resolveContactFormAvailability`'s `recaptchaSiteKey`. */
+    siteKey: string;
+    /** Whether the visitor has interacted with the form yet (REB-588 arming signal). */
+    armed: boolean;
+    children: ReactNode;
+}
+/**
+ * Drop-in replacement for wiring `deferredRecaptchaKey` directly into
+ * `<GoogleReCaptchaProvider reCaptchaKey={...}>` — see the module docs above
+ * for why that direct wiring never mints a real token. Pair with
+ * `useDeferredRecaptcha()` instead of the vendor's `useGoogleReCaptcha()`.
+ *
+ * ```tsx
+ * <DeferredRecaptchaProvider siteKey={siteKey} armed={armed}>
+ *   <form onFocusCapture={arm} onPointerDown={arm}>…</form>
+ * </DeferredRecaptchaProvider>
+ * ```
+ */
+declare function DeferredRecaptchaProvider({ siteKey, armed, children, ...providerProps }: DeferredRecaptchaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * The SITE's replacement for `react-google-recaptcha-v3`'s own
+ * `useGoogleReCaptcha()` when the form is wrapped in
+ * `<DeferredRecaptchaProvider>`. Same shape (`{ executeRecaptcha }`), but
+ * reads the STABLE context republished by `ExecuteBridge`, which never
+ * remounts on arm — unlike the vendor's own context, which lives on the
+ * element `DeferredRecaptchaProvider` deliberately keys and remounts.
+ */
+declare function useDeferredRecaptcha(): DeferredRecaptchaContextValue;
+
+export { type DeferredRecaptchaContextValue, DeferredRecaptchaProvider, type DeferredRecaptchaProviderProps, useDeferredRecaptcha };

package/dist/recaptcha-provider.js

@@ -0,0 +1,68 @@
+"use client";
+
+// src/recaptcha-provider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import { GoogleReCaptchaProvider, useGoogleReCaptcha } from "react-google-recaptcha-v3";
+
+// src/recaptcha.ts
+var RECAPTCHA_SITE_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+function isSafeRecaptchaSiteKey(value) {
+  return typeof value === "string" && RECAPTCHA_SITE_KEY_PATTERN.test(value);
+}
+function trimmed(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return text.length > 0 ? text : null;
+}
+function deferredRecaptchaKey(siteKey, armed) {
+  if (!armed) return "";
+  const key = trimmed(siteKey);
+  return key && isSafeRecaptchaSiteKey(key) ? key : "";
+}
+
+// src/recaptcha-provider.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var UNARMED = { executeRecaptcha: void 0 };
+var DeferredRecaptchaContext = createContext(UNARMED);
+function ExecuteBridge({
+  onChange
+}) {
+  const { executeRecaptcha } = useGoogleReCaptcha();
+  useEffect(() => {
+    onChange(executeRecaptcha);
+  }, [executeRecaptcha, onChange]);
+  return null;
+}
+function DeferredRecaptchaProvider({
+  siteKey,
+  armed,
+  children,
+  ...providerProps
+}) {
+  const reCaptchaKey = deferredRecaptchaKey(siteKey, armed);
+  const [executeRecaptcha, setExecuteRecaptcha] = useState(void 0);
+  const handleChange = useCallback(
+    (fn) => setExecuteRecaptcha(() => fn),
+    []
+  );
+  const contextValue = useMemo(() => ({ executeRecaptcha }), [executeRecaptcha]);
+  return /* @__PURE__ */ jsxs(DeferredRecaptchaContext.Provider, { value: contextValue, children: [
+    /* @__PURE__ */ jsx(GoogleReCaptchaProvider, { reCaptchaKey, ...providerProps, children: /* @__PURE__ */ jsx(ExecuteBridge, { onChange: handleChange }) }, reCaptchaKey),
+    children
+  ] });
+}
+function useDeferredRecaptcha() {
+  return useContext(DeferredRecaptchaContext);
+}
+export {
+  DeferredRecaptchaProvider,
+  useDeferredRecaptcha
+};
+//# sourceMappingURL=recaptcha-provider.js.map