docs(auth): update docs and add todos for v3

Author: mandarini

packages/core/auth-js/src/GoTrueClient.ts

@@ -53,7 +53,7 @@ import {
   validateExp,
 } from './lib/helpers'
 import { memoryLocalStorageAdapter } from './lib/local-storage'
-import { LockAcquireTimeoutError, navigatorLock, processLock } from './lib/locks'
+import { LockAcquireTimeoutError, processLock } from './lib/locks'
 import { polyfillGlobalThis } from './lib/polyfills'
 import { version } from './lib/version'
 
@@ -2536,7 +2536,7 @@ export default class GoTrueClient {
    * - If the session's access token is expired or is about to expire, this method will use the refresh token to refresh the session.
    * - When using in a browser, or you've called `startAutoRefresh()` in your environment (React Native, etc.) this function always returns a valid access token without refreshing the session itself, as this is done in the background. This function returns very fast.
    * - **IMPORTANT SECURITY NOTICE:** If using an insecure storage medium, such as cookies or request headers, the user object returned by this function **must not be trusted**. Always verify the JWT using `getClaims()` or your own JWT verification library to securely establish the user's identity and access. You can also use `getUser()` to fetch the user object directly from the Auth server for this purpose.
-   * - When using in a browser, this function is synchronized across all tabs using the [LockManager](https://developer.mozilla.org/en-US/docs/Web/API/LockManager) API. In other environments make sure you've defined a proper `lock` property, if necessary, to make sure there are no race conditions while the session is being refreshed.
+   * - This function is synchronized within the current process using an in-process lock. Cross-tab refresh races are handled server-side by GoTrue's refresh token reuse detection. You can opt in to cross-tab serialization via the Web Locks API by passing `lock: navigatorLock` (deprecated) in the client options.
    *
    * @example Get the session data
    * ```js

packages/core/auth-js/src/lib/locks.ts

@@ -42,12 +42,11 @@ export abstract class LockAcquireTimeoutError extends Error {
 /**
  * Error thrown when the browser Navigator Lock API fails to acquire a lock.
  *
- * @example
- * ```ts
- * import { NavigatorLockAcquireTimeoutError } from '@supabase/auth-js'
+ * @deprecated Only thrown by the deprecated {@link navigatorLock}. Scheduled
+ * for removal in the next major version. Use {@link ProcessLockAcquireTimeoutError}
+ * or catch {@link LockAcquireTimeoutError} instead.
  *
- * throw new NavigatorLockAcquireTimeoutError('Lock timed out')
- * ```
+ * TODO(v3): remove along with navigatorLock.
  */
 export class NavigatorLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 /**
@@ -69,6 +68,14 @@ export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
  * throw. Make sure you check availablility before configuring {@link
  * GoTrueClient}.
  *
+ * @deprecated `navigatorLock` is no longer the default browser lock and is kept
+ * only for opt-in use. It is scheduled for removal in the next major version.
+ * The default `processLock` handles within-tab serialization, and cross-tab
+ * refresh races are handled server-side by GoTrue's refresh token reuse
+ * detection. To opt in: `createClient(url, key, { auth: { lock: navigatorLock } })`
+ *
+ * TODO(v3): remove navigatorLock export and all steal-based recovery logic.
+ *
  * You can turn on debugging by setting the `supabase.gotrue-js.locks.debug`
  * local storage item to `true`.
  *
@@ -305,7 +312,8 @@ const PROCESS_LOCKS: { [name: string]: Promise<any> } = {}
  * Useful for environments like React Native or other non-browser
  * single-process (i.e. no concept of "tabs") environments.
  *
- * Use {@link #navigatorLock} in browser environments.
+ * This is the default lock for all environments. Use {@link navigatorLock} only
+ * if you need opt-in cross-tab serialization via the Web Locks API.
  *
  * @param name Name of the lock to be acquired.
  * @param acquireTimeout If negative, no timeout. If 0 an error is thrown if

packages/core/auth-js/src/lib/types.ts

@@ -124,13 +124,16 @@ export type GoTrueClientOptions = {
    * `processLock` (an in-process queue) is used in browser environments when
    * `persistSession` is true. Falls back to a no-op for non-browser environments.
    *
-   * To opt back in to the Web Locks API for cross-tab serialization:
+   * Cross-tab token refresh races are handled server-side: GoTrue allows
+   * concurrent refreshes of the same token (via reuse detection) so both tabs
+   * receive valid tokens without any client-side coordination.
+   *
+   * To opt back in to the Web Locks API for explicit cross-tab serialization
+   * (deprecated, scheduled for removal in the next major version):
    * ```ts
    * import { navigatorLock } from '@supabase/auth-js'
    * createClient(url, key, { auth: { lock: navigatorLock } })
    * ```
-   *
-   * @experimental
    */
   lock?: LockFunc
   /**