fix(ui): hide protect-check spinner while challenge widget is visible

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();

.changeset/protect-check-spinner-widget-visibility.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Polish the Protect check card: the loading spinner now hides while a challenge widget (e.g. Turnstile) is visible instead of spinning alongside it, only appears after a short delay so near-instant checks never flash it, and the card no longer reserves empty space above the spinner before a widget has rendered.

packages/shared/src/internal/clerk-js/__tests__/protectCheck.test.ts

@@ -63,26 +63,30 @@ describe('executeProtectCheck', () => {
  expect(result).toBe('proof-token-123');
  });
 
- it('passes only the spec-defined fields (token, uiHints, signal) — NOT the full resource', async () => {
+ it('passes only the spec-defined fields (token, uiHints, signal, setWidgetVisible) — NOT the full resource', async () => {
  const fn = vi.fn().mockResolvedValue('proof');
  vi.doMock('https://protect.example.com/sdk-args.js', () => ({ default: fn }));
 
  const container = fakeContainer();
  const controller = new AbortController();
+ // The visibility handshake: the script calls this before revealing UI so the host can
+ // drop its own spinner first; the promise resolves once the host has applied the change.
+ const setWidgetVisible = vi.fn().mockResolvedValue(undefined);
  await executeProtectCheck(
  protectCheck({
  sdkUrl: 'https://protect.example.com/sdk-args.js',
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  }),
  container,
- { signal: controller.signal },
+ { signal: controller.signal, setWidgetVisible },
  );
 
  expect(fn).toHaveBeenCalledWith(container, {
  token: 'opaque-challenge-token',
  uiHints: { reason: 'device_new' },
  signal: controller.signal,
+ setWidgetVisible,
  });
  });
  });

packages/shared/src/internal/clerk-js/protectCheck.ts

@@ -2,6 +2,16 @@ import { ClerkRuntimeError } from '../../error';
 import type { ProtectCheckResource } from '../../types';
 
 export interface ExecuteProtectCheckOptions {
+ /**
+ * Host-provided visibility handshake, forwarded to the script verbatim as
+ * `setWidgetVisible` in the init payload. The script calls it right before revealing UI in
+ * the container (and with `false` once its widget is done); the returned promise resolves
+ * only after the host has applied the change to the DOM (e.g. removed its own loading
+ * spinner), so the script can sequence its reveal without a frame of overlap. A script that
+ * knows its widget is imminent may call it immediately to avoid a spinner flash. Scripts
+ * must treat the field as optional — older hosts don't provide it.
+ */
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
  /**
  * Signals that the caller no longer needs the proof token (component unmounted, user
  * navigated away, etc.). When the signal aborts:
@@ -22,6 +32,7 @@ interface ScriptInitOptions {
  token: string;
  uiHints?: Record<string, string>;
  signal?: AbortSignal;
+ setWidgetVisible?: (visible: boolean) => Promise<void>;
 }
 
 type ScriptDefault = (container: HTMLDivElement, init: ScriptInitOptions) => Promise<string>;
@@ -88,7 +99,7 @@ export async function executeProtectCheck(
  container: HTMLDivElement,
  options: ExecuteProtectCheckOptions = {},
 ): Promise<string> {
- const { signal } = options;
+ const { signal, setWidgetVisible } = options;
  const { sdkUrl, token, uiHints } = protectCheck;
 
  const validated = assertValidSdkUrl(sdkUrl);
@@ -123,7 +134,7 @@ export async function executeProtectCheck(
 
  let proofToken: string;
  try {
- proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal });
+ proofToken = await (mod.default as ScriptDefault)(container, { token, uiHints, signal, setWidgetVisible });
  } catch (err) {
  // Distinguish abort-induced rejections from genuine script errors: only relabel as
  // `protect_check_aborted` when the error looks like an abort (`AbortError`), otherwise

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

@@ -18,6 +18,7 @@ import {
  Spinner,
  useLocalizations,
 } from '../../customizables';
+import { useSpinDelay } from '../../hooks';
 import { useProtectCheckRunner } from '../../hooks/useProtectCheckRunner';
 import { useRouter } from '../../router';
 
@@ -63,7 +64,7 @@ function SignInProtectCheckInternal(): JSX.Element {
  const { setActive } = useClerk();
  const { afterSignInUrl, navigateOnSetActive } = useSignInContext();
 
- const { containerRef, isRunning, hasError, retry } = useProtectCheckRunner<SignInResource>({
+ const { containerRef, isRunning, isWidgetVisible, hasError, retry } = useProtectCheckRunner<SignInResource>({
  getProtectCheck: () => signIn.protectCheck,
  getResource: () => signIn,
  reload: () => signIn.reload(),
@@ -88,6 +89,13 @@ function SignInProtectCheckInternal(): JSX.Element {
  },
  });
 
+ // Debounce the spinner's entrance so a near-instant check (or a script that signals its
+ // widget immediately) never flashes it — the card header alone carries the first ~300ms.
+ // The error and widget-visibility gates stay OUTSIDE the delay hook below: its minimum
+ // visible duration must never outrank the handshake's "spinner is gone when the promise
+ // resolves" guarantee, nor keep a spinner next to the retry button.
+ const showSpinner = useSpinDelay(isRunning, { delay: 300 });
+
  return (
  <Flow.Part part='protectCheck'>
  <Card.Root>
@@ -105,21 +113,18 @@ function SignInProtectCheckInternal(): JSX.Element {
  ref={containerRef}
  id='clerk-protect-check'
  aria-busy={isRunning}
- style={{ display: 'block', alignSelf: 'center', minHeight: '60px' }}
+ // Out of flow while empty so the collapsed container adds no reserved height or flex-gap
+ // gutter above the spinner (same idiom as CaptchaElement's `gapless` mode).
+ style={{ display: 'block', alignSelf: 'center', position: isWidgetVisible ? 'static' : 'absolute' }}
  />
- {isRunning && !hasError ? (
- <Flex
- direction='col'
- center
- gap={4}
- aria-live='polite'
- >
+ {showSpinner && !hasError && !isWidgetVisible ? (
+ <Flex center>
  <Spinner
  size='lg'
  colorScheme='primary'
  elementDescriptor={descriptors.spinner}
+ aria-label={t(localizationKeys('signIn.protectCheck.loading'))}
  />
- <Box>{t(localizationKeys('signIn.protectCheck.loading'))}</Box>
  </Flex>
  ) : null}
  {hasError ? (

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

@@ -1,6 +1,6 @@
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
 import type { SignInResource } from '@clerk/shared/types';
-import { waitFor } from '@testing-library/react';
+import { act, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';
@@ -250,6 +250,197 @@ describe('SignInProtectCheck', () => {
  });
  });
 
+ describe('challenge widget visibility', () => {
+ // Visibility is driven by the script, not observed from the DOM: executeProtectCheck hands
+ // the script a `setWidgetVisible` callback in its init payload, and the script calls it
+ // right before revealing UI in the container (and with `false` once the widget is done).
+ const renderWithPendingChallenge = async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ mockExecute.mockImplementation((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise(() => {}); // never resolves; the check stays running
+ });
+ const utils = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+ return { ...utils, container: container!, setWidgetVisible: setWidgetVisible! };
+ };
+
+ it('waits a beat before showing the spinner so near-instant checks never flash it', async () => {
+ const { queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Inside the spin-delay window nothing shows yet (the card header is already
+ // adequate feedback); the spinner only joins once the wait is genuinely long.
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('never shows the spinner for a check that completes before the delay', async () => {
+ const { wrapper, fixtures } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ mockExecute.mockResolvedValue('proof-fast');
+ fixtures.signIn.submitProtectCheck.mockResolvedValue({
+ status: 'needs_first_factor',
+ protectCheck: null,
+ createdSessionId: null,
+ } as unknown as SignInResource);
+
+ const { queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+
+ await waitFor(() => expect(fixtures.router.navigate).toHaveBeenCalledWith('../factor-one'));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ // The delayed timer must not fire the spinner after the run has already ended.
+ await new Promise(resolve => setTimeout(resolve, 400));
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('drops the spinner immediately on failure, minDuration notwithstanding', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute.mockImplementation(
+ () =>
+ new Promise((_, reject) => {
+ rejectRun = reject;
+ }),
+ );
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ // The retry control and the spinner must not coexist — the error gate outranks
+ // the spin-delay's minimum-visible duration.
+ await findByRole('button', { name: /try again/i });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ it('hides the spinner while the script signals a visible widget and restores it on the counter-signal', async () => {
+ const { setWidgetVisible, queryByText, queryByLabelText, findByLabelText } = await renderWithPendingChallenge();
+
+ // Invisible phase (SDK loading / executing): the spinner is the progress indicator.
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ // The label lives on the spinner itself — no visible "Loading" text (design-system
+ // consistency; see the dogfooding thread).
+ expect(queryByText(/loading/i)).not.toBeInTheDocument();
+
+ // The script announces its widget. By the time the promise resolves, the spinner must
+ // ALREADY be out of the DOM — that's the contract that lets the script reveal its UI
+ // without a frame of overlap.
+ let spinnerGoneAtResolve = false;
+ await act(async () => {
+ await setWidgetVisible(true);
+ spinnerGoneAtResolve = queryByLabelText(/loading/i) === null;
+ });
+ expect(spinnerGoneAtResolve).toBe(true);
+
+ // Widget done (e.g. solved, proof verification in flight): spinner takes back over.
+ await act(async () => {
+ await setWidgetVisible(false);
+ });
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('keeps the empty challenge container out of the layout until the script signals visibility', async () => {
+ const { container, setWidgetVisible } = await renderWithPendingChallenge();
+
+ // No reserved height and no flex-gap slot while there is nothing to show.
+ expect(container.style.minHeight).toBe('');
+ expect(container.style.position).toBe('absolute');
+
+ await act(async () => {
+ await setWidgetVisible(true);
+ });
+ expect(container.style.position).toBe('static');
+ });
+
+ it('ignores visibility signals from an abandoned run', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let staleSetWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, _el, opts) => {
+ staleSetWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation(() => new Promise(() => {})); // retry run stays pending
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+
+ // The failed run's script is a zombie (the abort signal is best-effort); a late signal
+ // from it must not flip visibility under the active run.
+ await act(async () => {
+ await staleSetWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('clears leftovers from a failed run so the retry starts with the spinner', async () => {
+ const { wrapper } = await createFixtures(f => {
+ f.startSignInWithProtectCheck();
+ });
+ let container: HTMLDivElement | undefined;
+ let setWidgetVisible: ((visible: boolean) => Promise<void>) | undefined;
+ let rejectRun: ((err: Error) => void) | undefined;
+ mockExecute
+ .mockImplementationOnce((_protectCheck, el, opts) => {
+ container = el as HTMLDivElement;
+ setWidgetVisible = opts?.setWidgetVisible;
+ return new Promise((_, reject) => {
+ rejectRun = reject;
+ });
+ })
+ .mockImplementation((_protectCheck, el) => {
+ container = el as HTMLDivElement;
+ return new Promise(() => {}); // retry run stays pending
+ });
+
+ const { findByRole, findByLabelText, queryByLabelText } = render(<SignInProtectCheck />, { wrapper });
+ await waitFor(() => expect(mockExecute).toHaveBeenCalled());
+
+ // A widget shows, then the run fails (e.g. turnstile error-callback).
+ container!.appendChild(document.createElement('div'));
+ await act(async () => {
+ await setWidgetVisible!(true);
+ });
+ expect(queryByLabelText(/loading/i)).not.toBeInTheDocument();
+ rejectRun!(
+ new ClerkRuntimeError('Protect check script execution failed', { code: 'protect_check_execution_failed' }),
+ );
+
+ const retryButton = await findByRole('button', { name: /try again/i });
+ fireEvent.click(retryButton);
+
+ // The new run owns the container: stale widget removed, spinner back — with no
+ // counter-signal from the dead script.
+ await waitFor(() => expect(mockExecute).toHaveBeenCalledTimes(2));
+ expect(container!.childNodes.length).toBe(0);
+ expect(await findByLabelText(/loading/i)).toBeInTheDocument();
+ });
+ });
+
  it('shows a retry control after a failure and re-runs the challenge when clicked', async () => {
  const { wrapper, fixtures } = await createFixtures(f => {
  f.startSignInWithProtectCheck();