feat(ui): host-owned back stack embedding for the user profile

[mikepitre]

Problem

The embedded-navigation handle (#798) lets a host hide Clerk's top bars and drive the profile's internal stack, but the profile still renders its own navigation container. Native Compose apps should be able to put Clerk's screens inside their own NavDisplay — the Android counterpart of the iOS SDK's public UserProfileView(navigationPath:) embedding — so the host owns transitions, predictive back, and the stack itself.

What this adds

A public ClerkUserProfileRoute key and EntryProviderScope.clerkUserProfileEntries(backStack):

val backStack = rememberNavBackStack(Home)

NavDisplay(
  backStack = backStack,
  entryProvider =
    entryProvider {
      entry<Home> { HomeScreen(onOpenProfile = { backStack.add(ClerkUserProfileRoute) }) }
      clerkUserProfileEntries(backStack)
    },
)

• Clerk's internal destination keys stay internal; hosts interact only with the root key. Internal keys restore in the host's rememberNavBackStack via nav3's reflection-based NavKey serialization.
• The profile removes only its own segment of the stack on exit: root back navigation, sign-out, and account deletion pop through ClerkUserProfileRoute and never touch host entries (UserProfileState.clearBackStack gains a scoped strategy for this).
• The profile root shows a back arrow instead of the dismiss X in this mode.
• navigation3-runtime moves from implementation to api since the new surface exposes its types.
• The existing self-contained UserProfileView shares the same entry registrations (extracted userProfileChildEntries) and is unchanged in behavior.

Verified end to end on an emulator via the new demo in the prebuilt-ui sample: host home → profile root → Security inside one host-owned NavDisplay, with hardware back unwinding one screen at a time and landing on the intact host screen.

Follow-up (intentionally not in this PR): the same treatment for AuthView. Its AuthState carries cross-screen form state, so per-entry providers would break it — the shared-scope design for that is coming separately.

Modules

source/ui and the prebuilt-ui sample.

🤖 Generated with Claude Code

Note

Add host-owned back stack embedding for the Clerk user profile in NavDisplay

• Adds clerkUserProfileEntries extension on EntryProviderScope so apps can register Clerk's user profile destinations inside their own NavDisplay and back stack, with Clerk only removing its own keys on exit.
• Introduces ClerkUserProfileRoute as a serializable NavKey that hosts push onto their NavBackStack to open the profile.
• Adds exitClerkUserProfile and popToClerkUserProfileRoot back stack helpers and a HostEntryChrome wrapper that applies Clerk's theme and providers to hosted entries.
• Refactors userProfileChildEntries out of userProfileEntries so child destinations are shared between self-contained and host-owned setups without changing existing behavior.
• Adds a sample HostStackProfileSample composable in the prebuilt-ui sample app demonstrating the host-owned flow via a full-screen dialog.
• Behavioral Change: libs.androidx.navigation3.runtime is now exposed as api from the source/ui module, making it transitive for library consumers.

^{Macroscope summarized 5a7f419.}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3cd9d365-30f3-4909-9600-89b6db2ebfa3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[mikepitre]

Parking this as a draft deliberately: the Expo integration doesn't use host-stack entries (it drives the profile through the FrameworkIntegrationApi-gated handle), so this public API — and the AuthView counterpart it still needs — can wait for a proper design review while the Expo-critical PRs ship. Written by Claude Code