From 3f38736b750f0d766e467cd44464584712e8cf39 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:54:49 -0500
Subject: [PATCH 1/8] fix(clerk-js): Improve Solana wallet error handling

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .../Web3SelectSolanaWalletScreen.tsx            | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/UserProfile/Web3SelectSolanaWalletScreen.tsx b/packages/clerk-js/src/ui/components/UserProfile/Web3SelectSolanaWalletScreen.tsx
index 707b591f056..cdc2791badb 100644
--- a/packages/clerk-js/src/ui/components/UserProfile/Web3SelectSolanaWalletScreen.tsx
+++ b/packages/clerk-js/src/ui/components/UserProfile/Web3SelectSolanaWalletScreen.tsx
@@ -1,3 +1,4 @@
+import { ClerkRuntimeError } from '@clerk/shared/error';
 import type { Web3Strategy } from '@clerk/shared/types';
 import { lazy, Suspense } from 'react';
 
@@ -6,11 +7,12 @@ import { useCardState } from '@/ui/elements/contexts';
 import { Form } from '@/ui/elements/Form';
 import { FormButtonContainer } from '@/ui/elements/FormButtons';
 import { FormContainer } from '@/ui/elements/FormContainer';
+import { handleError } from '@/ui/utils/errorHandler';
 
 import { Button, descriptors, Flex, localizationKeys, Spinner } from '../../customizables';
 
 const Web3SolanaWalletButtons = lazy(() =>
-  import(/* webpackChunkName: "web3-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
+  import(/* webpackChunkName: "web3-solana-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
     default: m.Web3SolanaWalletButtons,
   })),
 );
@@ -30,9 +32,15 @@ export const Web3SelectSolanaWalletScreen = ({ onConnect }: Web3SelectWalletProp
       card.setIdle();
     } catch (err) {
       card.setIdle();
-      console.error(err);
-    } finally {
-      close();
+      if (err instanceof Error) {
+        handleError(err, [], card.setError);
+      } else {
+        const error = new ClerkRuntimeError('An error occurred while generating the Solana signature.', {
+          code: 'web3_solana_signature_generation_failed',
+          cause: err instanceof Error ? err : undefined,
+        });
+        handleError(error, [], card.setError);
+      }
     }
   };
 
@@ -65,6 +73,7 @@ export const Web3SelectSolanaWalletScreen = ({ onConnect }: Web3SelectWalletProp
         </Suspense>
         <FormButtonContainer>
           <Button
+            type='button'
             variant='ghost'
             onClick={() => {
               close();

From 8f591f440d4808d9160399b2379948d0bb60f328 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:55:03 -0500
Subject: [PATCH 2/8] fix(config): Update max size for clerk.js in bundlewatch
 config

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 packages/clerk-js/bundlewatch.config.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
index 562644e636a..aea3cd9128a 100644
--- a/packages/clerk-js/bundlewatch.config.json
+++ b/packages/clerk-js/bundlewatch.config.json
@@ -1,6 +1,6 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "922.6KB" },
+    { "path": "./dist/clerk.js", "maxSize": "924KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "66KB" },

From a43dbd93ff9ba0ef01d34bfb81efc70990e9e5f9 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:55:53 -0500
Subject: [PATCH 3/8] fix(ui): Correct webpack chunk name for Solana wallet
 buttons

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .../ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx   | 2 +-
 .../src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx b/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
index aa4674a24e7..bff43188ac1 100644
--- a/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
+++ b/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
@@ -10,7 +10,7 @@ import { Header } from '@/ui/elements/Header';
 import { web3CallbackErrorHandler } from '@/ui/utils/web3CallbackErrorHandler';
 
 const Web3SolanaWalletButtons = lazy(() =>
-  import(/* webpackChunkName: "web3-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
+  import(/* webpackChunkName: "web3-solana-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
     default: m.Web3SolanaWalletButtons,
   })),
 );
diff --git a/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx b/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
index ed00e6e3e69..dfd9b7b678a 100644
--- a/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
+++ b/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
@@ -10,7 +10,7 @@ import { Header } from '@/ui/elements/Header';
 import { web3CallbackErrorHandler } from '@/ui/utils/web3CallbackErrorHandler';
 
 const Web3SolanaWalletButtons = lazy(() =>
-  import(/* webpackChunkName: "web3-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
+  import(/* webpackChunkName: "web3-solana-wallet-buttons" */ '@/ui/elements/Web3SolanaWalletButtons').then(m => ({
     default: m.Web3SolanaWalletButtons,
   })),
 );

From 7b0388af873a10a2f919922a57e038a6236c075a Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:56:20 -0500
Subject: [PATCH 4/8] fix(ui): Adjust sign-up and sign-in URLs for Solana
 wallet flow

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .../ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx   | 2 +-
 .../src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx b/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
index bff43188ac1..4a94a0350b9 100644
--- a/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
+++ b/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneSolanaWalletsCard.tsx
@@ -67,7 +67,7 @@ const SignInFactorOneSolanaWalletsCardInner = () => {
                       customNavigate: router.navigate,
                       redirectUrl: ctx.afterSignInUrl || '/',
                       secondFactorUrl: 'factor-two',
-                      signUpContinueUrl: ctx.isCombinedFlow ? '../create/continue' : ctx.signUpContinueUrl,
+                      signUpContinueUrl: ctx.isCombinedFlow ? 'create/continue' : ctx.signUpContinueUrl,
                       strategy: 'web3_solana_signature',
                       walletName,
                     })
diff --git a/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx b/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
index dfd9b7b678a..e8d6bc3196f 100644
--- a/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
+++ b/packages/clerk-js/src/ui/components/SignUp/SignUpStartSolanaWalletsCard.tsx
@@ -66,7 +66,7 @@ const SignUpStartSolanaWalletsCardInner = () => {
                     .authenticateWithWeb3({
                       customNavigate: router.navigate,
                       redirectUrl: ctx.afterSignUpUrl || '/',
-                      signUpContinueUrl: '../continue',
+                      signUpContinueUrl: 'continue',
                       strategy: 'web3_solana_signature',
                       unsafeMetadata: ctx.unsafeMetadata,
                       walletName,

From 36c90cadf7d3cdfe9e1c04a47397ccf4e217c95b Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:56:35 -0500
Subject: [PATCH 5/8] fix(ui): Add aria-label to wallet button for
 accessibility

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx b/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
index ecb0a143fe5..cfa88a47b0b 100644
--- a/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
+++ b/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
@@ -177,6 +177,7 @@ const WalletButtonIcon = forwardRef((props: WalletButtonProps, ref: Ref<HTMLButt
   return (
     <Button
       ref={ref}
+      aria-label={label}
       textVariant='buttonLarge'
       variant='outline'
       colorScheme='neutral'

From 91cd9a19214b4e7c0bf7f1411e506f6ac2c728f8 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:56:41 -0500
Subject: [PATCH 6/8] fix(utils): Prevent re-initialization of injected Solana
 providers

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 packages/clerk-js/src/utils/injectedWeb3SolanaProviders.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/clerk-js/src/utils/injectedWeb3SolanaProviders.ts b/packages/clerk-js/src/utils/injectedWeb3SolanaProviders.ts
index c2514cd78ac..e4d7c58cd4b 100644
--- a/packages/clerk-js/src/utils/injectedWeb3SolanaProviders.ts
+++ b/packages/clerk-js/src/utils/injectedWeb3SolanaProviders.ts
@@ -5,11 +5,16 @@ import type { Wallet } from '@wallet-standard/core';
 
 class InjectedWeb3SolanaProviders {
   #wallets: readonly Wallet[] | undefined = undefined;
+  #initialized: boolean = false;
   static #instance: InjectedWeb3SolanaProviders | null = null;
 
   private constructor() {}
 
   async #initialize() {
+    if (this.#initialized) {
+      return;
+    }
+    this.#initialized = true;
     const wallets = await import('@wallet-standard/core').then(mod => mod.getWallets());
     this.#wallets = wallets.get();
 

From fd20b2eb078b903c84e360ba74e0ca37c61ba744 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 15:57:30 -0500
Subject: [PATCH 7/8] docs: Add JSDoc comments to authenticateWithSolana
 methods for improved end user DX

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .../clerk-js/src/core/resources/SignIn.ts     | 23 ++++++++++---
 .../clerk-js/src/core/resources/SignUp.ts     | 34 +++++++++++++++----
 2 files changed, 47 insertions(+), 10 deletions(-)

diff --git a/packages/clerk-js/src/core/resources/SignIn.ts b/packages/clerk-js/src/core/resources/SignIn.ts
index 9074b69ed93..fdf8b728506 100644
--- a/packages/clerk-js/src/core/resources/SignIn.ts
+++ b/packages/clerk-js/src/core/resources/SignIn.ts
@@ -469,13 +469,28 @@ export class SignIn extends BaseResource implements SignInResource {
     });
   };
 
-  public authenticateWithSolana = async (params: SignInAuthenticateWithSolanaParams): Promise<SignInResource> => {
-    const identifier = await getSolanaIdentifier(params.walletName);
+  /**
+   * Authenticates a user using a Solana Web3 wallet during sign-in.
+   *
+   * @param params - Configuration for Solana authentication
+   * @param params.walletName - The name of the Solana wallet to use for authentication
+   * @returns A promise that resolves to the updated SignIn resource
+   * @throws {ClerkRuntimeError} If walletName is not provided or wallet connection fails
+   *
+   * @example
+   * ```typescript
+   * await signIn.authenticateWithSolana({ walletName: 'phantom' });
+   * ```
+   */
+  public authenticateWithSolana = async ({
+    walletName,
+  }: SignInAuthenticateWithSolanaParams): Promise<SignInResource> => {
+    const identifier = await getSolanaIdentifier(walletName);
     return this.authenticateWithWeb3({
       identifier,
-      generateSignature: p => generateSignatureWithSolana({ ...p, walletName: params.walletName }),
+      generateSignature: p => generateSignatureWithSolana({ ...p, walletName }),
       strategy: 'web3_solana_signature',
-      walletName: params.walletName,
+      walletName,
     });
   };
 
diff --git a/packages/clerk-js/src/core/resources/SignUp.ts b/packages/clerk-js/src/core/resources/SignUp.ts
index 0d9a3ba57b6..8421ecd70f3 100644
--- a/packages/clerk-js/src/core/resources/SignUp.ts
+++ b/packages/clerk-js/src/core/resources/SignUp.ts
@@ -366,15 +366,37 @@ export class SignUp extends BaseResource implements SignUpResource {
     });
   };
 
-  public authenticateWithSolana = async (params: SignUpAuthenticateWithSolanaParams): Promise<SignUpResource> => {
-    const identifier = await getSolanaIdentifier(params.walletName);
+  /**
+   * Authenticates a user using a Solana Web3 wallet during sign-up.
+   *
+   * @param params - Configuration for Solana authentication
+   * @param params.walletName - The name of the Solana wallet to use (e.g., 'phantom')
+   * @param params.unsafeMetadata - Optional unsafe metadata to attach to the user
+   * @param params.legalAccepted - Optional flag indicating legal terms acceptance
+   * @returns A promise that resolves to the updated SignUp resource
+   * @throws {ClerkRuntimeError} If wallet connection fails
+   *
+   * @example
+   * ```typescript
+   * await signUp.authenticateWithSolana({
+   *   walletName: 'phantom',
+   *   legalAccepted: true
+   * });
+   * ```
+   */
+  public authenticateWithSolana = async ({
+    walletName,
+    unsafeMetadata,
+    legalAccepted,
+  }: SignUpAuthenticateWithSolanaParams): Promise<SignUpResource> => {
+    const identifier = await getSolanaIdentifier(walletName);
     return this.authenticateWithWeb3({
       identifier,
-      generateSignature: p => generateSignatureWithSolana({ ...p, walletName: params.walletName }),
-      unsafeMetadata: params?.unsafeMetadata,
+      generateSignature: p => generateSignatureWithSolana({ ...p, walletName }),
+      unsafeMetadata,
       strategy: 'web3_solana_signature',
-      legalAccepted: params?.legalAccepted,
-      walletName: params.walletName,
+      legalAccepted,
+      walletName,
     });
   };
 

From 6c427b35d21445de88dc18eb03c48460a818de32 Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 17 Dec 2025 16:02:12 -0500
Subject: [PATCH 8/8] chore: pnpm changeset:empty

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .changeset/tame-icons-know.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/tame-icons-know.md

diff --git a/.changeset/tame-icons-know.md b/.changeset/tame-icons-know.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/tame-icons-know.md
@@ -0,0 +1,2 @@
+---
+---