fix(electron,shared,ui): keep Clerk navigation inside the Electron renderer

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;

.changeset/electron-virtual-router-navigation.md

@@ -0,0 +1,9 @@
+---
+'@clerk/electron': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Keep Clerk's navigation inside the renderer. `ClerkProvider` now always supplies `routerPush`/`routerReplace`, so Clerk routes through your application's router when you provide one, and never navigates the window to an internal `/CLERK-ROUTER/VIRTUAL/...` path — which no custom protocol handler can serve, and which reloaded the renderer and dropped the user out of sign-in.
+
+Applications that worked around this by passing no-op router functions, or by filtering `CLERK-ROUTER/VIRTUAL` out themselves, can remove those workarounds.

.changeset/signin-transport-transfer-next-step.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Route an OAuth transfer to the sign-up continue step when sign-in uses a native OAuth transport. The callback previously navigated with hash-style URLs (`<sign-up-url>#/continue`) that the in-place component router cannot resolve, landing transferred sign-ups on the start card where submitting created a fresh sign-up without the verified external account.

integration/templates/electron-vite/src/main.tsx

@@ -12,8 +12,8 @@ function App() {
  <ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  __internal_clerkUIUrl={CLERK_UI_URL}
- routerPush={() => {}}
- routerReplace={() => {}}
+ routerPush={(to: string) => window.history.pushState(null, '', to)}
+ routerReplace={(to: string) => window.history.replaceState(null, '', to)}
  >
  <main data-testid='electron-app'>
  <Show when='signed-out'>

integration/tests/electron/basic.test.ts

@@ -10,6 +10,7 @@ type ElectronWindow = Window & {
  tokenCache?: Partial<Record<'clearToken' | 'getToken' | 'saveToken', unknown>>;
  oauthTransport?: Partial<Record<'getRedirectUrl' | 'open', unknown>>;
  };
+ __hardNavigations?: string[];
 };
 
 test.describe('electron basic auth @electron', () => {
@@ -74,4 +75,24 @@ test.describe('electron basic auth @electron', () => {
  test('keeps the signed-out state after relaunch', async ({ electronPage }) => {
  await expect(electronPage.locator('.cl-signIn-root')).toBeVisible({ timeout: 30_000 });
  });
+
+ test('never hard navigates the renderer during sign-in', async ({ electronPage }) => {
+ const { signIn } = createPageObjects({ page: electronPage, useTestingToken: false });
+
+ await electronPage.evaluate(() => {
+ (window as ElectronWindow).__hardNavigations = [];
+ addEventListener('clerk:beforeunload', () => {
+ (window as ElectronWindow).__hardNavigations?.push(location.href);
+ });
+ });
+
+ await signIn.waitForMounted();
+ await signIn.setIdentifier(fakeUser.email!);
+ await signIn.continue();
+ await signIn.setPassword(fakeUser.password);
+ await signIn.continue();
+
+ await expect(electronPage.locator('[data-testid="user-id"]')).toHaveText(/^user_/, { timeout: 30_000 });
+ await expect(electronPage.evaluate(() => (window as ElectronWindow).__hardNavigations)).resolves.toEqual([]);
+ });
 });

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -99,6 +99,77 @@ describe('Electron ClerkProvider', () => {
  });
  });
 
+ describe('router handlers', () => {
+ const renderWithRouter = (props: Record<string, unknown> = {}) => {
+ renderToStaticMarkup(
+ <ClerkProvider
+ publishableKey='pk_test_provider'
+ {...props}
+ >
+ <span>App</span>
+ </ClerkProvider>,
+ );
+
+ return {
+ routerPush: capturedProviderProps?.routerPush as (to: string, metadata?: unknown) => void,
+ routerReplace: capturedProviderProps?.routerReplace as (to: string, metadata?: unknown) => void,
+ };
+ };
+
+ it('always supplies both handlers so clerk-js never falls back to a window navigation', () => {
+ const { routerPush, routerReplace } = renderWithRouter();
+
+ expect(routerPush).toBeTypeOf('function');
+ expect(routerReplace).toBeTypeOf('function');
+ });
+
+ it('absorbs virtual router paths instead of forwarding them to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+ routerReplace('/CLERK-ROUTER/VIRTUAL/sign-in#/factor-two', { windowNavigate });
+
+ expect(push).not.toHaveBeenCalled();
+ expect(replace).not.toHaveBeenCalled();
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('absorbs virtual router paths even without an application router', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/CLERK-ROUTER/VIRTUAL/sign-up#/continue', { windowNavigate });
+
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('forwards real destinations to the application router', () => {
+ const push = vi.fn();
+ const replace = vi.fn();
+ const windowNavigate = vi.fn();
+ const { routerPush, routerReplace } = renderWithRouter({ routerPush: push, routerReplace: replace });
+
+ routerPush('/settings/connections', { windowNavigate });
+ routerReplace('/dashboard', { windowNavigate });
+
+ expect(push).toHaveBeenCalledWith('/settings/connections', { windowNavigate });
+ expect(replace).toHaveBeenCalledWith('/dashboard', { windowNavigate });
+ expect(windowNavigate).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the host navigation for real destinations when no application router is provided', () => {
+ const windowNavigate = vi.fn();
+ const { routerPush } = renderWithRouter();
+
+ routerPush('/settings/connections', { windowNavigate });
+
+ expect(windowNavigate).toHaveBeenCalledWith('/settings/connections');
+ });
+ });
+
  it('defaults allowedRedirectProtocols to the renderer custom scheme', () => {
  stubWindowProtocol('clerk:');
 

packages/electron/src/react/index.tsx

@@ -1,5 +1,6 @@
 import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
 import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { isVirtualRouterPath } from '@clerk/shared/internal/clerk-js/url';
 import { ALLOWED_PROTOCOLS } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
@@ -79,6 +80,30 @@ function createOAuthTransport(): ClerkOAuthTransport | undefined {
  };
 }
 
+type ClerkRouterFn = NonNullable<ReactClerkProviderProps['routerPush']>;
+
+/** Always supplied, so clerk-js never reaches `window.location` and reloads the renderer. */
+function createRouterHandlers(
+ routerPush: ClerkRouterFn | undefined,
+ routerReplace: ClerkRouterFn | undefined,
+): { routerPush: ClerkRouterFn; routerReplace: ClerkRouterFn } {
+ const wrap =
+ (delegate: ClerkRouterFn | undefined): ClerkRouterFn =>
+ (to, metadata) => {
+ if (isVirtualRouterPath(to)) {
+ return;
+ }
+
+ if (delegate) {
+ return delegate(to, metadata);
+ }
+
+ metadata?.windowNavigate(to);
+ };
+
+ return { routerPush: wrap(routerPush), routerReplace: wrap(routerReplace) };
+}
+
 /**
  * Infer the custom renderer scheme registered with `createClerkBridge({ renderer })`.
  * Built-in Clerk protocols and local file renderers are not inferred.
@@ -98,15 +123,19 @@ export function ClerkProvider({
  publishableKey,
  passkeys,
  allowedRedirectProtocols,
+ routerPush,
+ routerReplace,
  ...props
 }: ClerkProviderProps): JSX.Element {
  const clerk = createClerkInstance(publishableKey, passkeys);
  const oauthTransport = createOAuthTransport();
  const clerkUI = loadClerkUI(publishableKey, props);
+ const routerHandlers = createRouterHandlers(routerPush, routerReplace);
 
  return (
  <ReactClerkProvider
  {...props}
+ {...routerHandlers}
  Clerk={clerk}
  __internal_oauthTransport={oauthTransport}
  allowedRedirectProtocols={allowedRedirectProtocols ?? defaultAllowedRedirectProtocols()}

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

@@ -398,6 +398,13 @@ export const pathFromFullPath = (fullPath: string) => {
  return fullPath.replace(/CLERK-ROUTER\/(.*?)\//, '');
 };
 
+export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+/**
+ * Whether `to` addresses the in-memory component router rather than a real application route.
+ */
+export const isVirtualRouterPath = (to: string): boolean => to.includes(VIRTUAL_ROUTER_BASE_PATH);
+
 const frontendApiRedirectPathsWithUserInput: string[] = [
  '/oauth/authorize', // OAuth2 identify provider flow
 ];

packages/ui/src/components/SignIn/__tests__/buildOAuthCallbackParams.test.ts

@@ -55,22 +55,72 @@ describe('buildSignInOAuthTransportCallbackParams', () => {
  unsafeMetadata: { a: 1 },
  } as any;
 
+ const origin = window.location.origin;
+
  expect(buildSignInOAuthTransportCallbackParams(ctx)).toEqual({
  signUpUrl: '/sign-up',
  signInUrl: '/sign-in',
  signInForceRedirectUrl: '/after-in',
  signUpForceRedirectUrl: '/after-up',
- continueSignUpUrl: '/continue',
  transferable: true,
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
- // Relative to the SignIn start route; the sign-up gate URL stays absolute (combined-aware).
  signInProtectCheckUrl: 'protect-check',
- signUpProtectCheckUrl: '/sign-up-protect-check',
+ // Sign-up steps are path routes on the sign-up component; hash-style URLs would lose their
+ // hash in the virtual router and land a transferred sign-up on the start card.
+ continueSignUpUrl: `${origin}/sign-up/continue`,
+ verifyEmailAddressUrl: `${origin}/sign-up/verify-email-address`,
+ verifyPhoneNumberUrl: `${origin}/sign-up/verify-phone-number`,
+ signUpProtectCheckUrl: `${origin}/sign-up/protect-check`,
  unsafeMetadata: { a: 1 },
  });
  });
+
+ it('targets the virtual sign-up routes for modal transport callbacks', () => {
+ const ctx = {
+ signUpUrl: '/CLERK-ROUTER/VIRTUAL/sign-up',
+ signInUrl: '/CLERK-ROUTER/VIRTUAL/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/CLERK-ROUTER/VIRTUAL/sign-up/protect-check`);
+ });
+
+ it('drops a hash fragment from signUpUrl when building sign-up step URLs', () => {
+ const ctx = {
+ signUpUrl: '/sign-up#/continue',
+ signInUrl: '/sign-in',
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+ const origin = window.location.origin;
+
+ expect(params.continueSignUpUrl).toBe(`${origin}/sign-up/continue`);
+ expect(params.verifyEmailAddressUrl).toBe(`${origin}/sign-up/verify-email-address`);
+ expect(params.verifyPhoneNumberUrl).toBe(`${origin}/sign-up/verify-phone-number`);
+ expect(params.signUpProtectCheckUrl).toBe(`${origin}/sign-up/protect-check`);
+ });
+
+ it('targets the embedded create subtree in the combined flow', () => {
+ const ctx = {
+ signUpUrl: '/sign-in#/create',
+ signInUrl: '/sign-in',
+ isCombinedFlow: true,
+ } as any;
+
+ const params = buildSignInOAuthTransportCallbackParams(ctx);
+
+ expect(params.continueSignUpUrl).toBe('create/continue');
+ expect(params.verifyEmailAddressUrl).toBe('create/verify-email-address');
+ expect(params.verifyPhoneNumberUrl).toBe('create/verify-phone-number');
+ expect(params.signUpProtectCheckUrl).toBe('create/protect-check');
+ });
 });
 
 describe('buildSignUpOAuthCallbackParams', () => {

packages/ui/src/components/SignIn/buildOAuthCallbackParams.ts

@@ -1,3 +1,4 @@
+import { buildURL, trimTrailingSlash } from '@clerk/shared/internal/clerk-js/url';
 import type { HandleOAuthCallbackParams } from '@clerk/shared/types';
 
 import type { SignInContextType } from '../../contexts/components/SignIn';
@@ -23,12 +24,27 @@ export function buildSignInOAuthCallbackParams(ctx: SignInContextType): HandleOA
 }
 
 export function buildSignInOAuthTransportCallbackParams(ctx: SignInContextType): HandleOAuthCallbackParams {
+ // Path form, not `#/step`: the in-place component router matches on pathname only and would drop the hash.
+ const signUpStepUrl = (step: string): string => {
+ if (ctx.isCombinedFlow) {
+ return `create/${step}`;
+ }
+ const url = buildURL({ base: ctx.signUpUrl }, { stringify: false });
+ url.pathname = `${trimTrailingSlash(url.pathname)}/${step}`;
+ url.hash = '';
+ return url.href;
+ };
+
  return {
  ...buildSignInOAuthCallbackParams(ctx),
  firstFactorUrl: 'factor-one',
  secondFactorUrl: 'factor-two',
  resetPasswordUrl: 'reset-password',
  signInProtectCheckUrl: 'protect-check',
+ continueSignUpUrl: signUpStepUrl('continue'),
+ verifyEmailAddressUrl: signUpStepUrl('verify-email-address'),
+ verifyPhoneNumberUrl: signUpStepUrl('verify-phone-number'),
+ signUpProtectCheckUrl: signUpStepUrl('protect-check'),
  };
 }
 

packages/ui/src/router/VirtualRouter.tsx

@@ -1,9 +1,11 @@
+import { VIRTUAL_ROUTER_BASE_PATH } from '@clerk/shared/internal/clerk-js/url';
 import { useClerk } from '@clerk/shared/react';
 import React, { useEffect } from 'react';
 
 import { useClerkModalStateParams } from '../hooks';
 import { BaseRouter } from './BaseRouter';
-export const VIRTUAL_ROUTER_BASE_PATH = 'CLERK-ROUTER/VIRTUAL';
+
+export { VIRTUAL_ROUTER_BASE_PATH };
 
 interface VirtualRouterProps {
  startPath: string;