feat(ramp): add transparent HEADLESS_ENTRY route (Phase 9.5 Fix #1)

After the Phase 9.5 chrome strip made HeadlessHost invisible, Goktug's
testing showed the user still sees a solid-white screen because the
headless flow enters via RAMP.TOKEN_SELECTION — an opaque V2 stack card
that sits between the consumer screen and the now-transparent Host.

Resolution: add a new outer slot RAMP.HEADLESS_ENTRY in MainNavigator
that mounts the same TokenListRoutes component as TOKEN_SELECTION, but
wraps it in the JS-stack transparent-overlay preset that BridgeModals,
EarnModals, MoneyModals, StakeModals, and PerpsModals already use:

  options={{
    ...clearStackNavigatorOptionsWithTransitionAnimation,
    presentation: 'transparentModal',
  }}

useHeadlessBuy.startHeadlessBuy now navigates to HEADLESS_ENTRY instead
of TOKEN_SELECTION; the nested-screen descriptor that lands directly on
HEADLESS_HOST stays unchanged. UB2's entry through TOKEN_SELECTION is
untouched.

Slack thread:
https://consensys.slack.com/archives/C0AK3NXRM7W/p1778577403631269

Author: saustrie-consensys

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Made the Ramp Headless Host invisible so consumer-rendered loading UI is visible during a headless buy; added a transparent `RAMP.HEADLESS_ENTRY` outer route so the headless flow no longer renders an opaque V2 stack card on top of the consumer screen (Phase 9.5).
+
 ## [7.76.3]
 
 ### Added

app/components/Nav/Main/MainNavigator.js

@@ -1173,6 +1173,14 @@ const MainNavigator = () => {
         name={Routes.RAMP.TOKEN_SELECTION}
         component={TokenListRoutes}
       />
+      <Stack.Screen
+        name={Routes.RAMP.HEADLESS_ENTRY}
+        component={TokenListRoutes}
+        options={{
+          ...clearStackNavigatorOptionsWithTransitionAnimation,
+          presentation: 'transparentModal',
+        }}
+      />
       <Stack.Screen
         name={Routes.RAMP.BUY}
         options={{

app/components/UI/Ramp/headless/PLAN.md

@@ -621,6 +621,33 @@ Driver: [May 6 2026 design thread](https://consensys.slack.com/archives/C0AK3NXR
 
 Deliverable: HeadlessHost is invisible (or bottom-sheet) and MMPay's TPC renders the only user-visible loading UI during a headless buy. Phase 8's dismissal contract continues to work unchanged.
 
+### Phase 9.5 follow-ups (driven by Goktug's May 12 2026 testing feedback)
+
+Goktug tested the chrome-stripped Host on May 12 and filed three complaints in the [follow-up thread](https://consensys.slack.com/archives/C0AK3NXRM7W/p1778577403631269).
+
+#### Fix #1 — Transparent stack wrapper (`RAMP.HEADLESS_ENTRY`)
+
+After the chrome strip, the user still saw a solid-white screen because [MainNavigator.js:1172-1175](../../Nav/Main/MainNavigator.js) mounts the headless flow under `RAMP.TOKEN_SELECTION`, an opaque V2 stack card. The card sits between the consumer screen and the transparent Host.
+
+Resolution: add a new outer slot `RAMP.HEADLESS_ENTRY` (in [Routes.ts](../../../../constants/navigation/Routes.ts)) that mounts the same `TokenListRoutes` component but with the JS-stack transparent-overlay preset:
+
+```js
+<Stack.Screen
+  name={Routes.RAMP.HEADLESS_ENTRY}
+  component={TokenListRoutes}
+  options={{
+    ...clearStackNavigatorOptionsWithTransitionAnimation,
+    presentation: 'transparentModal',
+  }}
+/>
+```
+
+This is the same pattern MainNavigator already uses for `BridgeModals`, `EarnModals`, `MoneyModals`, `StakeModals`, and `PerpsModals`. UB2's entry through `RAMP.TOKEN_SELECTION` stays untouched.
+
+`useHeadlessBuy.startHeadlessBuy` now navigates to `RAMP.HEADLESS_ENTRY` instead of `RAMP.TOKEN_SELECTION`; the nested-screen descriptor (`{ screen: TOKEN_SELECTION, params: { screen: HEADLESS_HOST, ... } }`) is unchanged so it still lands directly on the Host.
+
+Safety net for the unverified `beforeRemove` + `transparentModal` interaction: Phase 8's `useHeadlessSessionDismissal` fires `closeSession({ reason: 'user_dismissed' })` on unmount when `HEADLESS_HOST` is no longer in the navigator tree. `closeSession` idempotency means both paths can fire without producing duplicate `onClose` callbacks.
+
 ---
 
 ## Phase 10 — Implement deferred Phase 5b + playground polish

app/components/UI/Ramp/headless/useHeadlessBuy.test.ts

@@ -35,6 +35,7 @@ jest.mock('../../../../constants/navigation/Routes', () => ({
       BUY: 'RampBuy',
       TOKEN_SELECTION: 'RampTokenSelection',
       HEADLESS_HOST: 'RampHeadlessHost',
+      HEADLESS_ENTRY: 'RampHeadlessEntry',
     },
   },
 }));
@@ -447,7 +448,7 @@ describe('useHeadlessBuy', () => {
       if (!started) {
         throw new Error('startHeadlessBuy did not return a session');
       }
-      expect(mockNavigate).toHaveBeenCalledWith('RampTokenSelection', {
+      expect(mockNavigate).toHaveBeenCalledWith('RampHeadlessEntry', {
         screen: 'RampTokenSelection',
         params: {
           screen: 'RampHeadlessHost',

app/components/UI/Ramp/headless/useHeadlessBuy.ts

@@ -171,16 +171,19 @@ export function useHeadlessBuy(): HeadlessBuyResult {
       // The Headless Host is registered inside the Unified Buy v2 stack
       // (`app/components/UI/Ramp/routes.tsx` → `MainRoutes`) so it lives
       // next to every post-auth reset target (`Checkout`, `BasicInfo`,
-      // `KycWebview`, …). From outside that stack we have to enter the
-      // V2 stack via its outer mount point (`RAMP.TOKEN_SELECTION` in
-      // `MainNavigator.js`, which renders `TokenListRoutes`) and hand
-      // React Navigation a nested-screen descriptor:
-      //   RAMP.TOKEN_SELECTION (outer)
+      // `KycWebview`, …). From outside that stack we enter via the
+      // dedicated transparent-modal mount point — `RAMP.HEADLESS_ENTRY`
+      // in `MainNavigator.js`, which renders the same `TokenListRoutes`
+      // as `RAMP.TOKEN_SELECTION` but wraps it in a transparent overlay
+      // (preset: `clearStackNavigatorOptionsWithTransitionAnimation` +
+      // `presentation: 'transparentModal'`) so the consumer's screen
+      // stays visible behind the headless flow.
+      //   RAMP.HEADLESS_ENTRY (outer transparent modal)
       //     → RAMP.TOKEN_SELECTION (RootStack slot wrapping `MainRoutes`)
       //       → RAMP.HEADLESS_HOST (target screen on the inner stack)
       // Resetting the Host's nearest navigator (the `MainRoutes` inner
       // stack) then resolves all the `useTransakRouting` targets.
-      navigation.navigate(Routes.RAMP.TOKEN_SELECTION, {
+      navigation.navigate(Routes.RAMP.HEADLESS_ENTRY, {
         screen: Routes.RAMP.TOKEN_SELECTION,
         params: {
           screen: Routes.RAMP.HEADLESS_HOST,

app/constants/navigation/Routes.ts

@@ -23,6 +23,7 @@ const Routes = {
     ACTIVATION_KEY_FORM: 'RampActivationKeyForm',
     HEADLESS_PLAYGROUND: 'RampHeadlessPlayground',
     HEADLESS_HOST: 'RampHeadlessHost',
+    HEADLESS_ENTRY: 'RampHeadlessEntry',
     AMOUNT_INPUT: 'RampAmountInput',
     ENTER_EMAIL: 'RampEnterEmail',
     OTP_CODE: 'RampOtpCode',

app/core/NavigationService/types.ts

@@ -265,6 +265,7 @@ export interface RootStackParamList extends ParamListBase {
   RampBuy: RampBuySellParams | undefined;
   RampSell: RampBuySellParams | undefined;
   RampTokenSelection: undefined;
+  RampHeadlessEntry: undefined;
   GetStarted: undefined;
   /**
    * BuildQuote route is shared between: