feat(expo): simplify native client sync engine

[mikepitre]

Description

Replaces the @clerk/expo JS <-> native client sync engine (nativeClientSync.tsx, nativeClientSyncCoordinator.ts, useNativeClientEvents) with a much smaller one in provider/nativeClientSync.ts. Stacked on #9954, whose behavior suite now runs against this engine.

The server is the source of truth. The two SDKs share only:

1. Identity: one device token, owned by native storage. clerk-js reads the client JWT from getDeviceToken(), and a rotated token from a response is written with setDeviceToken(token, requestToken), a compare-and-set against the token that request was sent with (recorded per request in createClerkInstance). The effective token is mirrored into the app's tokenCache so it stays usable without native.
2. A payload-free "client changed" signal: when the JS client fingerprint (client, sessions, active user; nothing token related) changes, JS calls refreshClient(); when native emits clerkNativeClientInvalidated, JS refetches its own client and follows native's active session. Both directions are single-flight with one trailing rerun, and a native pull records the fingerprint it applied so it is not echoed back.

No state is pushed across the bridge, and the source-id tags, suppression counters, generation counters and token rollback are gone. configureNative is local setup only and runs once per publishable key before clerk-js's first request; native keeps its own stored token and only adopts the seed from tokenCache when it has none. If it fails or takes longer than 3s, sync stays off for the session and clerk-js keeps using tokenCache directly, which is also what happens without the native module or with __experimental_disableNativeClientSync.

Other pieces:

• A handleUnauthenticated guard refetches the client first and only signs out when no signed-in session remains. The updateClient interception still hides clerk-js's transient signed-out emission while another session is activated.
• Biometric flows use the new idle() and pullFromNative() barriers. idle() rejects with the latest native refresh failure until a later refresh succeeds, and with environment_unavailable after 5s.
• A behavior change: when native moves to a different client on its own, JS now follows it instead of rejecting a foreign sessionless client and restoring its previous token. Native owns the identity, and the startup case that check guarded against is covered by configureNative keeping native's own token.

New ClerkExpo contract: configureNative(publishableKey, seedDeviceToken), getDeviceToken(), setDeviceToken(token, expected): Promise<boolean>, refreshClient(), and the clerkNativeClientInvalidated event. This PR is JS only. It depends on the native bridge PR (link to follow), which is backed by clerk/clerk-ios#583 and clerk/clerk-android#964.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 1b59ac3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/expo	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 28, 2026 8:26pm UTC
swingset	Ready	Preview	Sep 28, 2026 8:26pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[mikepitre]

Superseded by #9956 (comment) (re-recorded so sheet and modal animations are captured).

[mikepitre]

Superseded by #9956 (comment) (re-recorded from a plain create-expo-app app with no native workarounds).

[mikepitre]

Native ↔ JS sync round trip from a plain app: a fresh create-expo-app (SDK 57) with Clerk set up per the docs (@clerk/expo + @clerk/expo-native-components), Expo's own ios.enableSceneSupport for Xcode 27, and a stock expo run:ios build, with no native edits. Packages from the top of the stack. iPhone Air simulator (iOS 27), full-frame-rate capture; only long still stretches between steps were shortened. JS signs in with a test-mode email code.

1. JS sign-in → the native UserButton appears in the header (JS → native)
2. Sign out from the UserButton account sheet → JS signs out (native → JS)
3. JS sign-in, then JS sign-out → the sign-in screen's AuthView asks for sign-in (JS → native)

roundtrip-final.mp4