From 60056adad625b868fac2b0ca0f7e3c30ef6250fe Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Fri, 13 Mar 2026 17:06:26 -0600
Subject: [PATCH] Add initial setup

---
 .typedoc/custom-plugin.mjs                 | 17 +++++++++++++++
 packages/react/src/hooks/useClerkSignal.ts |  8 +++----
 packages/shared/src/types/state.ts         | 25 ++++++++++++++++------
 3 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs
index aca8cc799fe..68a56cd9f1c 100644
--- a/.typedoc/custom-plugin.mjs
+++ b/.typedoc/custom-plugin.mjs
@@ -52,7 +52,11 @@ const LINK_REPLACEMENTS = [
   ['session-resource', '/docs/reference/objects/session'],
   ['signed-in-session-resource', '/docs/reference/objects/session'],
   ['sign-in-resource', '/docs/reference/objects/sign-in'],
+  ['sign-in-future-resource', '/docs/reference/objects/sign-in-future'],
+  ['sign-in-errors', '/docs/reference/javascript/types/errors'],
   ['sign-up-resource', '/docs/reference/objects/sign-up'],
+  ['sign-up-future-resource', '/docs/reference/objects/sign-up-future'],
+  ['sign-up-errors', '/docs/reference/javascript/types/errors'],
   ['user-resource', '/docs/reference/objects/user'],
   ['session-status-claim', '/docs/reference/types/session-status'],
   ['user-organization-invitation-resource', '/docs/reference/types/user-organization-invitation'],
@@ -157,6 +161,15 @@ function getCatchAllReplacements() {
       pattern: /(?<![\[\w`])`?SignInResource`?(?![\]\w`])/g,
       replace: '[`SignInResource`](/docs/reference/objects/sign-in)',
     },
+    {
+      pattern: /(?<![\[\w`])`?((?:SignIn|SignUp)Errors)`?(?![\]\w`])/g,
+      replace: (/** @type {string} */ _match, /** @type {string} */ type) =>
+        `[${type}](/docs/reference/javascript/types/errors)`,
+    },
+    {
+      pattern: /(?<![\[\w`])`?SignInFutureResource`?(?![\]\w`])/g,
+      replace: '[`SignInFutureResource`](/docs/reference/objects/sign-in-future)',
+    },
     {
       pattern: /(?<![\[\w`])`?SignedInSessionResource`?(?![\]\w`])/g,
       replace: '[`SignedInSessionResource`](/docs/reference/objects/session)',
@@ -165,6 +178,10 @@ function getCatchAllReplacements() {
       pattern: /(?<![\[\w`])`?SignUpResource`?(?![\]\w`])/g,
       replace: '[`SignUpResource`](/docs/reference/objects/sign-up)',
     },
+    {
+      pattern: /(?<![\[\w`])`?SignUpFutureResource`?(?![\]\w`])/g,
+      replace: '[`SignUpFutureResource`](/docs/reference/objects/sign-up-future)',
+    },
     {
       pattern: /(?<![\[\w`])`?OrganizationResource`?(?![\]\w`])/g,
       replace: '[`OrganizationResource`](/docs/reference/objects/organization)',
diff --git a/packages/react/src/hooks/useClerkSignal.ts b/packages/react/src/hooks/useClerkSignal.ts
index f2da60a9bf1..44d09e56eee 100644
--- a/packages/react/src/hooks/useClerkSignal.ts
+++ b/packages/react/src/hooks/useClerkSignal.ts
@@ -83,9 +83,9 @@ function useClerkSignal(
  *   //
  * }
  */
-export function useSignIn() {
+export const useSignIn = (): SignInSignalValue => {
   return useClerkSignal('signIn');
-}
+};
 
 /**
  * This hook allows you to access the Signal-based `SignUp` resource.
@@ -98,9 +98,9 @@ export function useSignIn() {
  *   //
  * }
  */
-export function useSignUp() {
+export const useSignUp = (): SignUpSignalValue => {
   return useClerkSignal('signUp');
-}
+};
 
 /**
  * This hook allows you to access the Signal-based `Waitlist` resource.
diff --git a/packages/shared/src/types/state.ts b/packages/shared/src/types/state.ts
index 7c065226454..17d6c289993 100644
--- a/packages/shared/src/types/state.ts
+++ b/packages/shared/src/types/state.ts
@@ -126,19 +126,24 @@ export type SignUpErrors = Errors<SignUpFields>;
 export type WaitlistErrors = Errors<WaitlistFields>;
 
 /**
+ * @inline
+ *
  * The value returned by the `useSignInSignal` hook.
  */
 export interface SignInSignalValue {
   /**
-   * Represents the errors that occurred during the last fetch of the parent resource.
+   * The errors that occurred during the last fetch of the underlying `SignInFuture` resource.
    */
   errors: SignInErrors;
   /**
-   * The fetch status of the underlying `SignIn` resource.
+   * The fetch status of the underlying `SignInFuture` resource.
    */
   fetchStatus: 'idle' | 'fetching';
   /**
-   * An instance representing the currently active `SignIn`, with new APIs designed specifically for custom flows.
+   * An instance representing the currently active `SignInFuture`, with new APIs designed specifically for custom flows.
+   *
+   * > [!IMPORTANT]
+   * > The `SignInFuture` instance referenced by `signIn` does not have a stable identity, and will change as the sign-in flow progresses. Make sure you provide it in dependency arrays when using hooks such as `useEffect`, `useCallback`, or `useMemo`.
    */
   signIn: SignInFutureResource;
 }
@@ -149,17 +154,25 @@ export interface SignInSignal {
   (): NullableSignInSignal;
 }
 
+/**
+ * @inline
+ *
+ * The value returned by the `useSignUpSignal` hook.
+ */
 export interface SignUpSignalValue {
   /**
-   * The errors that occurred during the last fetch of the underlying `SignUp` resource.
+   * The errors that occurred during the last fetch of the underlying `SignUpFuture` resource.
    */
   errors: SignUpErrors;
   /**
-   * The fetch status of the underlying `SignUp` resource.
+   * The fetch status of the underlying `SignUpFuture` resource.
    */
   fetchStatus: 'idle' | 'fetching';
   /**
-   * The underlying `SignUp` resource.
+   * The underlying `SignUpFuture` resource
+   *
+   * > [!IMPORTANT]
+   * > The `SignUpFuture` instance referenced by `signUp` does not have a stable identity, and will change as the sign-up flow progresses. Make sure you provide it in dependency arrays when using hooks such as `useEffect`, `useCallback`, or `useMemo`.
    */
   signUp: SignUpFutureResource;
 }