From faf4955d9cf4e7d41a544c12f2e6a2de4df6bf20 Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Mon, 16 Nov 2026 22:18:54 -0700 Subject: [PATCH 1/6] refactor(shared): split the sign-in and sign-up next step types getSignInNextStep and getSignUpNextStep now return SignInNextStep and SignUpNextStep, so a sign-up caller can switch over its steps exhaustively without handling sign-in steps it never receives. NextStep stays as their union. --- .../shared/src/internal/clerk-js/nextStep.ts | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/packages/shared/src/internal/clerk-js/nextStep.ts b/packages/shared/src/internal/clerk-js/nextStep.ts index 05123c9f3e2..757dd14310a 100644 --- a/packages/shared/src/internal/clerk-js/nextStep.ts +++ b/packages/shared/src/internal/clerk-js/nextStep.ts @@ -1,20 +1,28 @@ import type { ProtectCheckResource, SignUpField, SignUpIdentificationField, VerificationResource } from '../../types'; -export type NextStep = +type SharedNextStep = + | { type: 'protect' } + | { type: 'transfer' } + | { type: 'complete'; createdSessionId: string | null } + | { type: 'unknown' }; + +export type SignInNextStep = + | SharedNextStep | { type: 'identifier' } | { type: 'first_factor'; strategy: string | null; sent: boolean } | { type: 'second_factor'; strategy: string | null; sent: boolean } | { type: 'client_trust' } - | { type: 'new_password' } - | { type: 'protect' } - | { type: 'transfer' } + | { type: 'new_password' }; + +export type SignUpNextStep = + | SharedNextStep | { type: 'start' } | { type: 'enterprise_sso' } | { type: 'fields'; fields: SignUpField[] } | { type: 'verify_email'; target: string | null; sent: boolean } - | { type: 'verify_phone'; target: string | null; sent: boolean } - | { type: 'complete'; createdSessionId: string | null } - | { type: 'unknown' }; + | { type: 'verify_phone'; target: string | null; sent: boolean }; + +export type NextStep = SignInNextStep | SignUpNextStep; type VerificationInput = Pick; @@ -48,7 +56,7 @@ export type SignUpNextStepInput = { * * @internal */ -export function getSignInNextStep(signIn: SignInNextStepInput): NextStep { +export function getSignInNextStep(signIn: SignInNextStepInput): SignInNextStep { if (signIn.protectCheck) { return { type: 'protect' }; } @@ -81,7 +89,7 @@ export function getSignInNextStep(signIn: SignInNextStepInput): NextStep { * * @internal */ -export function getSignUpNextStep(signUp: SignUpNextStepInput): NextStep { +export function getSignUpNextStep(signUp: SignUpNextStepInput): SignUpNextStep { if (!signUp.id) { return { type: 'start' }; } From 5502afb99baf5cb12dfb9bdf8ca4b99d5dbb22b5 Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Mon, 16 Nov 2026 22:18:59 -0700 Subject: [PATCH 2/6] fix(shared): verify the sign-up email and phone before collecting missing fields getSignUpNextStep followed navigateToNextStepSignUp's order, which only the OAuth return and sign-up-if-missing paths use. It now follows completeSignUpFlow, the order the sign-up forms use. --- packages/mosaic/docs/internals/sign-in-sign-up-flow.md | 2 +- .../src/internal/clerk-js/__tests__/nextStep.test.ts | 10 +++++----- packages/shared/src/internal/clerk-js/nextStep.ts | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md index 6b4c55f02cf..5bedeb5f8a5 100644 --- a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md +++ b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md @@ -64,9 +64,9 @@ Sign-up: - `start` → `start` - `protect` → `protectCheck` - `enterprise_sso` → `enterpriseConnections`, which goes straight to the IdP unless there are several connections to pick from -- `fields` (`fields`) → `continue` - `verify_email` (`target`, `sent`) → `verifyEmail` - `verify_phone` (`target`, `sent`) → `verifyPhone` +- `fields` (`fields`) → `continue` `identifier` and `start` are what Mosaic shows before the resource exists; a sign-in with no status and a sign-up not yet created both return them. `sent` means a code or link is out, so a reload on the same `:factor` doesn't send another. Picking a different factor always sends, because `sent` can't tell two targets with the same strategy apart (see [Bridge](#bridge)). diff --git a/packages/shared/src/internal/clerk-js/__tests__/nextStep.test.ts b/packages/shared/src/internal/clerk-js/__tests__/nextStep.test.ts index 8c8f43e9b8b..8a102950167 100644 --- a/packages/shared/src/internal/clerk-js/__tests__/nextStep.test.ts +++ b/packages/shared/src/internal/clerk-js/__tests__/nextStep.test.ts @@ -168,11 +168,11 @@ describe('getSignUpNextStep', () => { }); }); - it('collects missing fields before verifying the email', () => { - expect(getSignUpNextStep(signUp({ missingFields: ['username'], unverifiedFields: ['email_address'] }))).toEqual({ - type: 'fields', - fields: ['username'], - }); + it('verifies the email before collecting missing fields', () => { + const step = getSignUpNextStep( + signUp({ missingFields: ['username'], unverifiedFields: ['email_address'], emailAddress: 'ada@example.com' }), + ); + expect(step).toEqual({ type: 'verify_email', target: 'ada@example.com', sent: false }); }); it('verifies the email before the phone', () => { diff --git a/packages/shared/src/internal/clerk-js/nextStep.ts b/packages/shared/src/internal/clerk-js/nextStep.ts index 757dd14310a..50440203288 100644 --- a/packages/shared/src/internal/clerk-js/nextStep.ts +++ b/packages/shared/src/internal/clerk-js/nextStep.ts @@ -108,9 +108,6 @@ export function getSignUpNextStep(signUp: SignUpNextStepInput): SignUpNextStep { if (signUp.missingFields.includes('enterprise_sso')) { return { type: 'enterprise_sso' }; } - if (signUp.missingFields.length > 0) { - return { type: 'fields', fields: signUp.missingFields }; - } if (signUp.unverifiedFields.includes('email_address')) { return { type: 'verify_email', @@ -125,6 +122,9 @@ export function getSignUpNextStep(signUp: SignUpNextStepInput): SignUpNextStep { sent: signUp.verifications.phoneNumber.nextAction === 'needs_attempt', }; } + if (signUp.missingFields.length > 0) { + return { type: 'fields', fields: signUp.missingFields }; + } return { type: 'unknown' }; } From a311415fa919800c1fe8177ce5d4dee849aff5a5 Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Mon, 16 Nov 2026 22:19:05 -0700 Subject: [PATCH 3/6] chore(shared): note the sign-up requirement FAPI does not send --- packages/shared/src/internal/clerk-js/nextStep.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/shared/src/internal/clerk-js/nextStep.ts b/packages/shared/src/internal/clerk-js/nextStep.ts index 50440203288..618f201bc30 100644 --- a/packages/shared/src/internal/clerk-js/nextStep.ts +++ b/packages/shared/src/internal/clerk-js/nextStep.ts @@ -125,6 +125,8 @@ export function getSignUpNextStep(signUp: SignUpNextStepInput): SignUpNextStep { if (signUp.missingFields.length > 0) { return { type: 'fields', fields: signUp.missingFields }; } + // TODO: FAPI computes `MissingRequirements` in `checkStatus` but does not serialize it, so a sign-up blocked only + // by an unmet identifier requirement lands here. Return `fields` from `missing_requirements` once FAPI sends it. return { type: 'unknown' }; } From 396b143234152c3da0552eedae9bd0ecc356052d Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Tue, 17 Nov 2026 11:40:56 -0700 Subject: [PATCH 4/6] docs(mosaic): name the order sign-up follows until FAPI sends one --- packages/mosaic/docs/internals/sign-in-sign-up-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md index 5bedeb5f8a5..d75cb457bc2 100644 --- a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md +++ b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md @@ -92,6 +92,6 @@ The controller calls these model callbacks on `start`, then `next(step)`. `getSignInNextStep` and `getSignUpNextStep` (`shared/src/internal/clerk-js/nextStep.ts`) compute the step from today's fields, and return FAPI's `nextStep` once it is sent. They can't compute three things, so FAPI must send them: -- The sign-up order. +- The sign-up order. Until FAPI sends it, `getSignUpNextStep` follows `ui`'s order (`shared/src/internal/clerk-js/completeSignUpFlow.ts`): verify the email, then the phone, then collect the missing fields. - `target` for sign-in. Nothing says which email or phone a code went to. - `sent` per target for sign-in. `first_factor_verification` has no identification, so after a code to one email, a second email with the same strategy also reads as sent. From 3b1d6d945d7a209a51b9ed6cb36798cdfb6c5033 Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Tue, 17 Nov 2026 17:06:34 -0700 Subject: [PATCH 5/6] chore(repo): add an empty changeset for the sign-up step order --- .changeset/shared-sign-up-next-step-order.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .changeset/shared-sign-up-next-step-order.md diff --git a/.changeset/shared-sign-up-next-step-order.md b/.changeset/shared-sign-up-next-step-order.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/shared-sign-up-next-step-order.md @@ -0,0 +1,2 @@ +--- +--- From eeeeacaefa1040e49a10c8876ae39528e69d1c6c Mon Sep 17 00:00:00 2001 From: austincalvelage Date: Tue, 17 Nov 2026 17:23:51 -0700 Subject: [PATCH 6/6] docs(mosaic): clarify who chooses the next sign-up step --- packages/mosaic/docs/internals/sign-in-sign-up-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md index d75cb457bc2..876f616570e 100644 --- a/packages/mosaic/docs/internals/sign-in-sign-up-flow.md +++ b/packages/mosaic/docs/internals/sign-in-sign-up-flow.md @@ -4,7 +4,7 @@ How sign-in and sign-up decide which screen to show, from the step FAPI says com ## The model -A step is a step of the auth flow, not a screen. FAPI owns the step, the order of steps, and whether a code is already sent. Mosaic owns the routes, the layout and copy, and when to send a code. +FAPI tracks which requirements are outstanding and whether a code has been sent. When several sign-up requirements are outstanding, the shared client picks which one comes next. Mosaic maps the step to a screen and owns the routes, layout, copy, and when to send a code. Today FAPI sends `status`, `missing_fields` and `unverified_fields`, not a step. Until it sends `nextStep`, `getSignInNextStep` and `getSignUpNextStep` in `shared` compute it from those fields (see [Bridge](#bridge)).