fix(shared): improve single-session sign-in/sign-up dev warning wording

.changeset/single-session-warning-wording.md

@@ -0,0 +1,5 @@
+---
+"@clerk/shared": patch
+---
+
+Improved the `cannot_render_single_session_enabled` dev warning to use friendlier wording. The message now clearly states that the behavior is expected and points developers to the Clerk Dashboard to enable multi-session mode if needed.

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { warnings } from '../warnings';
+
+describe('warnings', () => {
+  describe('cannotOpenSignInOrSignUp', () => {
+    it('explains that the behavior is expected', () => {
+      expect(warnings.cannotOpenSignInOrSignUp).toContain('expected behavior');
+    });
+
+    it('mentions single-session mode', () => {
+      expect(warnings.cannotOpenSignInOrSignUp).toContain('single-session mode');
+    });
+
+    it('mentions multi-session as the resolution', () => {
+      expect(warnings.cannotOpenSignInOrSignUp).toContain('multi-session mode');
+    });
+
+    it('includes the development notice', () => {
+      expect(warnings.cannotOpenSignInOrSignUp).toContain('This notice only appears in development');
+    });
+  });
+});

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

@@ -53,7 +53,7 @@ const warnings = {
   cannotOpenCheckout:
     'The Checkout drawer cannot render unless a user is signed in. Since no user is signed in, this is no-op.',
   cannotOpenSignInOrSignUp:
-    'The SignIn or SignUp modals do not render when a user is already signed in, unless the application allows multiple sessions. Since a user is signed in and this application only allows a single session, this is no-op.',
+    'The <SignIn/> and <SignUp/> modals are hidden because a user is already signed in and this application is configured for single-session mode. This is expected behavior — no action is needed. To allow rendering while signed in, enable multi-session mode in your Clerk Dashboard.',
   cannotRenderAPIKeysComponent:
     'The <APIKeys/> component cannot be rendered when API keys is disabled. Since API keys is disabled, this is no-op.',
   cannotRenderAPIKeysComponentForOrgWhenUnauthorized: