feat(ui): spotlight interactive captcha during sign-in/sign-up

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });

.changeset/captcha-inline-spotlight.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+When an interactive bot-protection challenge appears during sign-in or sign-up, the card now brings the challenge to the foreground — hiding the other fields and buttons until it's solved — so it's clear the "Verify you are human" check must be completed. Invisible challenges are unaffected.

.changeset/captcha-spotlight-compat.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Fix the inline captcha spotlight to expand correctly when an older clerk-js runtime is paired with a newer UI that expects the `data-cl-interactive` attribute — the challenge now falls back to the `maxHeight` heuristic so the spotlight still fires across version skews.

packages/clerk-js/sandbox/app.ts

@@ -186,6 +186,31 @@ function assertClerkIsLoaded(c: ClerkType | undefined): asserts c is ClerkType {
  }
 }
 
+/**
+ * Sandbox-only demo aid: force an interactive Cloudflare Turnstile challenge so the inline captcha
+ * "spotlight" can be exercised without changing instance settings. Enable with `?captcha=interactive`.
+ *
+ * Overrides the loaded environment (never `src/`) to use Cloudflare's documented test sitekey
+ * `3x00000000000000000000FF` (which always escalates to interactive), render it inline, and disable
+ * the OAuth bypass so the "Continue with …" path also hits the challenge. Remove the query param to
+ * get the normal (mostly invisible) behavior back.
+ */
+function applyCaptchaSandboxOverrides() {
+ if (new URL(window.location.href).searchParams.get('captcha') !== 'interactive') {
+ return;
+ }
+ const env = (Clerk as unknown as { __internal_environment?: any })?.__internal_environment;
+ if (!env) {
+ console.warn('[sandbox] captcha=interactive: environment not loaded, skipping override');
+ return;
+ }
+ env.displayConfig.captchaPublicKey = '3x00000000000000000000FF'; // forces an interactive challenge
+ env.displayConfig.captchaWidgetType = 'smart'; // render inline into #clerk-captcha
+ env.displayConfig.captchaOauthBypass = []; // also exercise the OAuth ("Continue with …") path
+ env.userSettings.signUp.captcha_enabled = true; // ensure the widget actually runs
+ console.info('[sandbox] Forcing interactive captcha (test sitekey 3x…FF).');
+}
+
 function mountIndex(element: HTMLDivElement) {
  assertClerkIsLoaded(Clerk);
  const user = Clerk.user;
@@ -507,6 +532,7 @@ void (async () => {
  },
  localization: l[initialLocale as keyof typeof l],
  });
+ applyCaptchaSandboxOverrides();
  renderCurrentRoute();
  const { pane } = await initControls();
 

packages/clerk-js/src/utils/captcha/__tests__/turnstile.test.ts

@@ -0,0 +1,64 @@
+import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from '@clerk/shared/internal/clerk-js/constants';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTurnstileToken } from '../turnstile';
+
+/**
+ * Regression guard for the inline "spotlight": the spotlight keys off
+ * `#clerk-captcha`'s `style.maxHeight !== '0'`. The common invisible flow (~99% of
+ * challenges) must never create or mutate `#clerk-captcha`, so its `maxHeight` stays
+ * `'0'` and no spotlight is ever triggered. This pins that existing behavior.
+ */
+describe('getTurnstileToken — invisible flow', () => {
+ let renderConfig: Record<string, any> | undefined;
+
+ beforeEach(() => {
+ renderConfig = undefined;
+ (window as any).turnstile = {
+ render: vi.fn((_selector: string, config: Record<string, any>) => {
+ renderConfig = config;
+ // Real Turnstile returns the widget id, then fires the callback asynchronously.
+ // Invisible challenges resolve without ever escalating to interactive, so the
+ // `before-interactive-callback` (the only code that expands #clerk-captcha) never fires.
+ setTimeout(() => config.callback('mock_token'), 0);
+ return 'mock_widget_id';
+ }),
+ remove: vi.fn(),
+ reset: vi.fn(),
+ };
+ });
+
+ afterEach(() => {
+ document.body.innerHTML = '';
+ delete (window as any).turnstile;
+ vi.restoreAllMocks();
+ });
+
+ it('renders into its own throwaway container, never #clerk-captcha', async () => {
+ // An inline #clerk-captcha may coexist on the page (e.g. a Start card is mounted),
+ // but an invisible challenge must never touch it.
+ const inline = document.createElement('div');
+ inline.id = CAPTCHA_ELEMENT_ID;
+ inline.style.maxHeight = '0';
+ document.body.appendChild(inline);
+
+ const result = await getTurnstileToken({
+ captchaProvider: 'turnstile',
+ siteKey: 'visible-key',
+ invisibleSiteKey: 'invisible-key',
+ widgetType: 'invisible',
+ });
+
+ expect(result).toEqual({ captchaToken: 'mock_token', captchaWidgetType: 'invisible' });
+
+ // The invisible flow targets its own `.clerk-invisible-captcha` div with the invisible key.
+ expect((window as any).turnstile.render).toHaveBeenCalledWith(`.${CAPTCHA_INVISIBLE_CLASSNAME}`, expect.anything());
+ expect(renderConfig?.sitekey).toBe('invisible-key');
+
+ // The spotlight signal on #clerk-captcha is untouched throughout → no spotlight.
+ expect(inline.style.maxHeight || '0').toBe('0');
+
+ // The temporary invisible container is created then cleaned up in `finally`.
+ expect(document.querySelector(`.${CAPTCHA_INVISIBLE_CLASSNAME}`)).toBeNull();
+ });
+});

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -177,6 +177,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  // and then expands to the correct height
  visibleWidget.style.minHeight = captchaSize === 'compact' ? '140px' : '68px';
  visibleWidget.style.marginBottom = '1.5rem';
+ visibleWidget.dataset.clInteractive = 'true';
  }
  }
  },
@@ -242,6 +243,7 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
  if (captchaTypeUsed === 'smart') {
  const visibleWidget = document.getElementById(CAPTCHA_ELEMENT_ID);
  if (visibleWidget) {
+ delete visibleWidget.dataset.clInteractive;
  visibleWidget.style.maxHeight = '0';
  visibleWidget.style.minHeight = 'unset';
  visibleWidget.style.marginBottom = 'unset';

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -158,6 +158,9 @@ function SignInStartInternal(): JSX.Element {
  const hasSocialOrWeb3Buttons =
  !!authenticatableSocialStrategies.length || !!web3FirstFactors.length || !!alternativePhoneCodeChannels.length;
  const [shouldAutofocus, setShouldAutofocus] = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = useState(false);
  const textIdentifierField = useFormControl('identifier', initialValues[identifierAttribute] || '', {
  ...currentIdentifier,
  isRequired: true,
@@ -597,6 +600,13 @@ function SignInStartInternal(): JSX.Element {
  <Col
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {hasSocialOrWeb3Buttons && (
@@ -629,24 +639,27 @@ function SignInStartInternal(): JSX.Element {
  />
  </Col>
  <Col center>
- <CaptchaElement />
  <Form.SubmitButton hasArrow />
  </Col>
  </Form.Root>
  ) : null}
  </SocialButtonsReversibleContainerWithDivider>
- {!standardFormAttributes.length && <CaptchaElement />}
- {userSettings.attributes.passkey?.enabled &&
- userSettings.passkeySettings.show_sign_in_button &&
- isWebSupported && (
- <Card.Action elementId={'usePasskey'}>
- <Card.ActionLink
- localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
- onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
- />
- </Card.Action>
- )}
  </Col>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
+ {/* Kept outside descriptors.main so the spotlight's `inert` leaves this alternative action reachable. */}
+ {userSettings.attributes.passkey?.enabled &&
+ userSettings.passkeySettings.show_sign_in_button &&
+ isWebSupported && (
+ <Card.Action elementId={'usePasskey'}>
+ <Card.ActionLink
+ localizationKey={localizationKeys('signIn.start.actionLink__use_passkey')}
+ onClick={() => authenticateWithPasskey({ flow: 'discoverable' })}
+ />
+ </Card.Action>
+ )}
  </Card.Content>
  <Card.Footer>
  {userSettings.signUp.mode === SIGN_UP_MODES.PUBLIC && !isCombinedFlow && (

packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx

@@ -1,9 +1,11 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignInResource } from '@clerk/shared/types';
 import { waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, mockWebAuthn, render, screen } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -761,4 +763,67 @@ describe('SignInStart', () => {
  );
  });
  });
+
+ describe('Captcha', () => {
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+ });
+
+ describe('Captcha spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignInStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ // The captcha widget and the header stay outside the inert subtree.
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+
+ mockWebAuthn(() => {
+ it('keeps the passkey action available (outside the inert subtree) during the spotlight', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress();
+ f.withPasskey();
+ f.withPasskeySettings({
+ allow_autofill: false,
+ show_sign_in_button: true,
+ });
+ });
+ render(<SignInStart />, { wrapper });
+
+ simulateCaptchaInteractive(getCaptcha());
+ // Spotlight is active (the form is inert)...
+ await waitFor(() => expect(screen.getByText(/email address/i).closest('[inert]')).not.toBeNull());
+ // ...but the passkey action remains reachable.
+ expect(screen.getByText('Use passkey instead').closest('[inert]')).toBeNull();
+ });
+ });
+ });
 });

packages/ui/src/components/SignUp/SignUpForm.tsx

@@ -5,7 +5,6 @@ import { LegalCheckbox } from '@/ui/elements/LegalConsentCheckbox';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 
 import { Col, localizationKeys, useAppearance } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
 import { mqu } from '../../styledSystem';
 import type { ActiveIdentifier, Fields } from './signUpFormHelpers';
 
@@ -116,7 +115,6 @@ export const SignUpForm = (props: SignUpFormProps) => {
  </Col>
  )}
  <Col center>
- <CaptchaElement />
  <Col
  gap={6}
  sx={{

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -65,6 +65,9 @@ function SignUpStartInternal(): JSX.Element {
  );
 
  const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
+ // When the captcha escalates to an interactive challenge, spotlight it by collapsing/inerting the
+ // rest of the card (see the descriptors.main column below).
+ const [captchaIsInteractive, setCaptchaIsInteractive] = React.useState(false);
 
  const {
  userSettings: { passwordSettings, usernameSettings },
@@ -442,6 +445,13 @@ function SignUpStartInternal(): JSX.Element {
  direction='col'
  elementDescriptor={descriptors.main}
  gap={6}
+ // @ts-ignore - `inert` is not yet in the installed React types
+ inert={captchaIsInteractive ? '' : undefined}
+ // `display:none` (not `visibility:hidden`) so the collapsed column leaves flex flow and
+ // contributes no `gap` gutter to `Card.Content` — otherwise it injects empty space above
+ // the spotlighted captcha. Subtree stays mounted (form state preserved); `inert` is then
+ // redundant-but-harmless.
+ sx={captchaIsInteractive ? { display: 'none' } : undefined}
  >
  <SocialButtonsReversibleContainerWithDivider>
  {(showOauthProviders || showWeb3Providers || showAlternativePhoneCodeProviders) && (
@@ -464,8 +474,11 @@ function SignUpStartInternal(): JSX.Element {
  />
  )}
  </SocialButtonsReversibleContainerWithDivider>
- {!shouldShowForm && <CaptchaElement />}
  </Flex>
+ <CaptchaElement
+ gapless
+ onInteractiveChange={setCaptchaIsInteractive}
+ />
  </Card.Content>
 
  <Card.Footer>

packages/ui/src/components/SignUp/__tests__/SignUpStart.test.tsx

@@ -1,8 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
+import { CAPTCHA_ELEMENT_ID } from '@clerk/shared/internal/clerk-js/constants';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import type { SignUpResource } from '@clerk/shared/types';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { simulateCaptchaInteractive, simulateCaptchaResolved } from '@/test/captcha';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { fireEvent, render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
@@ -523,4 +525,55 @@ describe('SignUpStart', () => {
  await waitFor(() => screen.getByText(/create your account/i));
  });
  });
+
+ describe('Captcha', () => {
+ // The ticket tests above mutate window.location and don't restore it (no afterEach in this
+ // suite); reset to a clean URL so the ticket flow doesn't fire during these renders.
+ beforeEach(() => {
+ Object.defineProperty(window, 'location', {
+ writable: true,
+ value: new URL('http://localhost/sign-up'),
+ });
+ });
+
+ it('renders the captcha widget in the form (email) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ it('renders the captcha widget in the social-only (no form) config', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+ expect(document.getElementById(CAPTCHA_ELEMENT_ID)).not.toBeNull();
+ });
+
+ describe('spotlight', () => {
+ const getCaptcha = () => document.getElementById(CAPTCHA_ELEMENT_ID) as HTMLElement;
+
+ it('inerts the form/social subtree while interactive — never the captcha or header — and restores', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.withEmailAddress({ required: true });
+ f.withSocialProvider({ provider: 'google' });
+ });
+ render(<SignUpStart />, { wrapper });
+
+ const google = screen.getByText(/continue with google/i);
+ expect(google.closest('[inert]')).toBeNull();
+
+ simulateCaptchaInteractive(getCaptcha());
+
+ await waitFor(() => expect(google.closest('[inert]')).not.toBeNull());
+ expect(getCaptcha().closest('[inert]')).toBeNull();
+ expect(screen.getByRole('heading').closest('[inert]')).toBeNull();
+
+ simulateCaptchaResolved(getCaptcha());
+ await waitFor(() => expect(google.closest('[inert]')).toBeNull());
+ });
+ });
+ });
 });