.changeset/late-results-melt.md (1)

1-8: Expand the changeset note with concrete API surface and migration hints.

Current note is too terse for a minor bump across three packages. Please list the experimental APIs and behavioral changes added in this PR so downstreams understand what shipped:

• SignInFuture: getters isTransferable, existingSession; create({ transfer? }).
• SignUp/SignUpFuture: analogous transfer support and SSO helpers.
• React experimental exports: useSignUpSignal.
• State: SignUp errors now emitted via signUpErrorSignal.

If this feature is gated/undocumented, add a one-liner stating it’s experimental and subject to change, and point to any internal docs or follow-up docs PR.

packages/clerk-js/src/core/state.ts (1)

39-47: Reset fetch status on error to avoid stuck “loading” UIs

On error, we currently only emit the error signal—so if your UI went into fetching, it never returns to idle. To fix this, update the onResourceError handler in packages/clerk-js/src/core/state.ts to also reset the fetch status:

• In onResourceError, after signaling the error, emit the corresponding fetch-idle signal.
• For example:

--- a/packages/clerk-js/src/core/state.ts
+++ b/packages/clerk-js/src/core/state.ts
@@ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
     if (payload.resource instanceof SignIn) {
-      this.signInErrorSignal({ error: payload.error });
+      this.signInErrorSignal({ error: payload.error });
+      this.signInFetchSignal({ status: 'idle' });
     }

     if (payload.resource instanceof SignUp) {
-      this.signUpErrorSignal({ error: payload.error });
+      this.signUpErrorSignal({ error: payload.error });
+      this.signUpFetchSignal({ status: 'idle' });
     }
 };

This ensures that any “loading” state is promptly cleared when an error occurs.

packages/types/src/signIn.ts (1)

132-134: Add JSDoc for new fields on SignInFutureResource.

Document the semantics to keep the public API self-describing:

• isTransferable: true when the first factor supports transfer to an existing session.
• existingSession: present when sign-in failed due to identifier_already_signed_in and contains the sessionId to target for transfer.

This helps IDE hovers and downstream TS users.

packages/clerk-js/src/core/resources/SignIn.ts (3)

486-667: Add focused tests for the new Future surface (unit or integration).

Please add tests covering:

• isTransferable toggling based on firstFactorVerification.status.
• existingSession extraction when error.code === 'identifier_already_signed_in'.
• create({ transfer: true }) passes through and results in expected server interaction.
• sso() + create path remains unaffected by transfer unless explicitly set.

Happy to scaffold test cases using your preferred test runner; say the word and I’ll draft them.

---

512-523: Add inline JSDoc to the existingSession getter

The error code string "identifier_already_signed_in" is used consistently across the codebase (in both UI and core logic, as well as tests), so documenting its meaning here will improve maintainability and help future refactors.

• File: packages/clerk-js/src/core/resources/SignIn.ts
Lines: 512–523

Suggested diff:

   /**
-   * Present when sign-in failed because the identifier is already signed in elsewhere.
-   * Contains the { sessionId } that may be targeted for transfer.
+   * Returns the session ID when sign-in failed with code
+   * `"identifier_already_signed_in"` and the payload includes a `sessionId`.
+   * This indicates the identifier is already signed in; the returned
+   * `{ sessionId }` may be used to transfer or resume that session.
+   *
+   * @returns {{ sessionId: string } | undefined}
   */
    get existingSession() {
      if (
        this.resource.firstFactorVerification.status === 'failed' &&
        this.resource.firstFactorVerification.error?.code === 'identifier_already_signed_in' &&
        this.resource.firstFactorVerification.error?.meta?.sessionId
      ) {
        return { sessionId: this.resource.firstFactorVerification.error.meta.sessionId };
      }

      return undefined;
    }

---

508-511: Add JSDoc for isTransferable (status literal confirmed valid)

I’ve confirmed that "transferable" is a member of VerificationStatus (see packages/types/src/verification.ts:26) and is consistently used for first-factor flows throughout the codebase. Adding a short JSDoc here will clarify when this flag flips to true and how callers (e.g., custom UIs) should handle it.

• Location: packages/clerk-js/src/core/resources/SignIn.ts around line 508
• Status literal verified in:

• packages/types/src/verification.ts:26
• Multiple usage sites in hooks, machines, SignUp/SignIn resources, and tests

Suggested inline JSDoc:

   /**
+  * Returns true when the user’s first-factor verification status is
+  * “transferable”, indicating the flow can be continued on an existing session.
+  * Callers can use this to prompt a “Continue on existing session” UI path.
   */
   get isTransferable() {
     return this.resource.firstFactorVerification.status === 'transferable';
   }

packages/types/src/signUp.ts (2)

125-127: Document new fields and harden param typing (readonly) on create()

Add concise JSDoc for the new Future fields and mark the transfer param as readonly to signal immutability at the call site. This also satisfies the “All public APIs must be documented with JSDoc” guideline.

 export interface SignUpFutureResource {
   status: SignUpStatus | null;
   unverifiedFields: SignUpIdentificationField[];
-  isTransferable: boolean;
-  existingSession?: { sessionId: string };
-  create: (params: { transfer?: boolean }) => Promise<{ error: unknown }>;
+  /**
+   * True when the external account can be transferred into this sign-up flow.
+   * Derived from backend verification signals for external accounts.
+   */
+  isTransferable: boolean;
+  /**
+   * Present when the identifier is already signed in elsewhere (e.g. SSO already used).
+   * Use to prompt "Continue with existing session".
+   */
+  existingSession?: { readonly sessionId: string };
+  /**
+   * Starts the sign-up. When `transfer` is true, the backend may attempt to transfer
+   * a matched external account into the new sign-up.
+   */
+  create: (params: { readonly transfer?: boolean }) => Promise<{ error: unknown }>;

---

133-135: Narrow SSO strategy typing to known strategy unions

strategy: string is too loose for a public API. Tightening to the existing strategy unions improves DX and catches mistakes at compile time.

-  sso: (params: { strategy: string; redirectUrl: string; redirectUrlComplete: string }) => Promise<{ error: unknown }>;
+  /**
+   * Initiate SSO during sign-up using OAuth/SAML/Enterprise strategies.
+   */
+  sso: (params: {
+    strategy: OAuthStrategy | SamlStrategy | EnterpriseSSOStrategy;
+    redirectUrl: string;
+    redirectUrlComplete: string;
+  }) => Promise<{ error: unknown }>;

packages/clerk-js/src/core/resources/SignUp.ts (5)

117-120: Guard access to firstFactorVerification.strategy in transfer path

Avoid potential undefined access; only set params.strategy when available. Keeps this path resilient in atypical client states.

-    if (params.transfer && this.shouldBypassCaptchaForAttempt(params)) {
-      params.strategy = SignUp.clerk.client?.signIn.firstFactorVerification.strategy;
-    }
+    if (params.transfer && this.shouldBypassCaptchaForAttempt(params)) {
+      const strategy = SignUp.clerk.client?.signIn?.firstFactorVerification?.strategy;
+      if (strategy) {
+        params.strategy = strategy;
+      }
+    }

---

498-509: Return a typed session object only when sessionId is a string

Minor robustness: ensure we never return { sessionId: undefined } if the meta shape changes.

-  get existingSession() {
-    if (
-      (this.resource.verifications.externalAccount.status === 'failed' ||
-        this.resource.verifications.externalAccount.status === 'unverified') &&
-      this.resource.verifications.externalAccount.error?.code === 'identifier_already_signed_in' &&
-      this.resource.verifications.externalAccount.error?.meta?.sessionId
-    ) {
-      return { sessionId: this.resource.verifications.externalAccount.error?.meta?.sessionId };
-    }
-
-    return undefined;
-  }
+  get existingSession() {
+    const v = this.resource.verifications.externalAccount;
+    const code = v.error?.code;
+    const sessionId = v.error?.meta?.sessionId;
+    if ((v.status === 'failed' || v.status === 'unverified') && code === 'identifier_already_signed_in') {
+      return typeof sessionId === 'string' ? { sessionId } : undefined;
+    }
+    return undefined;
+  }

---

526-534: Deduplicate captcha logic: delegate to SignUp.create and add captcha-retry fallback

SignUpFuture.create reimplements captcha handling that already exists in SignUp.create and misses the environment-reload retry used elsewhere. Delegate to create for consistency and add the same retry. Fewer moving parts, less drift.

-  async create({ transfer }: { transfer?: boolean }): Promise<{ error: unknown }> {
-    return runAsyncResourceTask(this.resource, async () => {
-      const { captchaToken, captchaWidgetType, captchaError } = await this.getCaptchaToken();
-      await this.resource.__internal_basePost({
-        path: this.resource.pathRoot,
-        body: { transfer, captchaToken, captchaWidgetType, captchaError },
-      });
-    });
-  }
+  async create({ transfer }: { transfer?: boolean }): Promise<{ error: unknown }> {
+    return runAsyncResourceTask(this.resource, async () => {
+      try {
+        await this.resource.create({ transfer });
+      } catch (e) {
+        if (isClerkAPIResponseError(e) && isCaptchaError(e)) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          await SignUp.clerk.__unstable__environment!.reload();
+          await this.resource.create({ transfer });
+        } else {
+          throw e;
+        }
+      }
+    });
+  }

---

572-604: Reuse create() and mirror captcha-retry behavior in SSO flow

This mirrors authenticateWithRedirectOrPopup’s resilience (captcha environment reload) and avoids duplicating captcha plumbing by delegating to create. Also maps redirectUrlComplete to actionCompleteRedirectUrl which create already understands.

-  async sso({
-    strategy,
-    redirectUrl,
-    redirectUrlComplete,
-  }: {
-    strategy: string;
-    redirectUrl: string;
-    redirectUrlComplete: string;
-  }): Promise<{ error: unknown }> {
-    return runAsyncResourceTask(this.resource, async () => {
-      const { captchaToken, captchaWidgetType, captchaError } = await this.getCaptchaToken();
-      await this.resource.__internal_basePost({
-        path: this.resource.pathRoot,
-        body: {
-          strategy,
-          redirectUrl: SignUp.clerk.buildUrlWithAuth(redirectUrl),
-          redirectUrlComplete,
-          captchaToken,
-          captchaWidgetType,
-          captchaError,
-        },
-      });
-
-      const { status, externalVerificationRedirectURL } = this.resource.verifications.externalAccount;
-
-      if (status === 'unverified' && !!externalVerificationRedirectURL) {
-        windowNavigate(externalVerificationRedirectURL);
-      } else {
-        clerkInvalidFAPIResponse(status, SignUp.fapiClient.buildEmailAddress('support'));
-      }
-    });
-  }
+  async sso({
+    strategy,
+    redirectUrl,
+    redirectUrlComplete,
+  }: {
+    strategy: string;
+    redirectUrl: string;
+    redirectUrlComplete: string;
+  }): Promise<{ error: unknown }> {
+    return runAsyncResourceTask(this.resource, async () => {
+      const redirectUrlWithAuth = SignUp.clerk.buildUrlWithAuth(redirectUrl);
+      const createWithSSO = () =>
+        this.resource.create({
+          strategy,
+          redirectUrl: redirectUrlWithAuth,
+          actionCompleteRedirectUrl: redirectUrlComplete,
+        });
+
+      try {
+        await createWithSSO();
+      } catch (e) {
+        if (isClerkAPIResponseError(e) && isCaptchaError(e)) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          await SignUp.clerk.__unstable__environment!.reload();
+          await createWithSSO();
+        } else {
+          throw e;
+        }
+      }
+
+      const { status, externalVerificationRedirectURL } = this.resource.verifications.externalAccount;
+      if (status === 'unverified' && !!externalVerificationRedirectURL) {
+        windowNavigate(externalVerificationRedirectURL);
+      } else {
+        clerkInvalidFAPIResponse(status, SignUp.fapiClient.buildEmailAddress('support'));
+      }
+    });
+  }

Happy to push a follow-up commit if you want this refactor applied across the analogous SignInFuture flow as well.

---

526-534: Add tests for transfer and SSO “Future” flows

No tests are shown in this PR. Please add focused unit/integration coverage for:

• SignUpFuture.isTransferable: true only when externalAccount.status === 'transferable' and error.code === 'external_account_exists'.
• SignUpFuture.existingSession: returns sessionId when error.code === 'identifier_already_signed_in' and meta.sessionId present; otherwise undefined.
• SignUpFuture.create: calls SignUp.create with { transfer }, and retries after environment reload on captcha error.
• SignUpFuture.sso:
  • Posts with buildUrlWithAuth(redirectUrl) and maps redirectUrlComplete -> actionCompleteRedirectUrl when delegating to create.
  • Navigates to externalVerificationRedirectURL on 'unverified'; throws via clerkInvalidFAPIResponse otherwise.
• SignUp.create (transfer path): when bypass applies, sets strategy from client.signIn.firstFactorVerification if present.

I can draft the tests (Jest + msw) and a small helper to fabricate SignUp.verifications.externalAccount snapshots if you’d like.

Also applies to: 572-604, 491-497, 498-509

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/clerk-js/src/core/state.ts (1)

45-45: Correct fix: route SignUp errors to the error signal.

This aligns SignUp with SignIn and prevents polluting the resource signal with error payloads.

packages/types/src/signIn.ts (1)

139-140: LGTM: create accepts transfer?: boolean.

Type surface matches the runtime support added in SignInFuture.create.

packages/clerk-js/src/core/resources/SignIn.ts (1)

570-576: LGTM: create now forwards transfer to the API.

Matches the types and the feature intent.

packages/react/src/experimental.ts (1)

4-4: Good fix: export useSignUpSignal.

Restores parity with useSignInSignal and makes the experimental API discoverable.

packages/clerk-js/src/core/resources/SignUp.ts (1)

491-497: Transferability check looks correct

The predicate matches the described backend states for transferability. Nice and explicit.

packages/clerk-js/bundlewatch.config.json (1)

1-35: Add tests for new Signal transfer and error-routing behavior introduced by this PR.

This config change accompanies new runtime features (transfer flag, new getters, SignUp.sso, and error signal routing). Ensure unit/integration coverage exists for:

• SignInFuture/SignUpFuture isTransferable and existingSession getters.
• create({ transfer }) flows for both sign-in and sign-up, including captcha paths.
• SignUp.sso(...) external-account redirect and error propagation to the dedicated sign-up error signal.
• react: experimental re-export of useSignUpSignal.
  I can help draft test cases if needed.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/clerk-js/bundlewatch.config.json (1)

5-5: Build artifact missing – please generate and measure gzip/brotli sizes

It looks like packages/clerk-js/dist/clerk.legacy.browser.js isn’t present in the repo, so we can’t verify the bundle size automatically. To tighten your bundle budget and avoid masking unintended growth:

• Run the project build (e.g., pnpm build) to emit dist/clerk.legacy.browser.js.
• Execute the sizing script from your repo root to record raw, gzip, and brotli outputs.
• In packages/clerk-js/bundlewatch.config.json, set maxSize to the measured gzip size plus ~0.5 KB headroom.
• Investigate why the legacy bundle grew (likely new polyfills for transfer/SSO); consider deferring or lazy-loading these in the legacy build.

Once you’ve measured and updated the threshold, please confirm here.