feat: headless ramps

[georgeweiler]

Description

Changelog

CHANGELOG entry:

Related issues

Fixes:

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

Screenshots/Recordings

Before

After

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Medium Risk
Adds a new headless buy entrypoint that auto-continues the Ramp flow and threads a session ID through checkout/native-provider routing; mistakes could cause unintended navigation/auto-purchases or missed order tracking.

Overview
Adds a headless buy capability that reuses the existing Ramp buy orchestration without rendering the full BuildQuote UI.

Introduces useHeadlessRamps plus a headlessBuySessionRegistry to create per-session IDs, track order IDs, and listen to RampsController:orderStatusChanged events only for orders initiated by that headless session.

Threads headlessSessionId through BuildQuote, Checkout, and Transak native flow screens/routing, and records order IDs (precreated and callback-derived) via trackHeadlessBuyOrder so headless callers can observe completion/failure; BuildQuote also supports an auto-continue mode with a minimal loading/error+retry UI.

^{Written by Cursor Bugbot for commit 3608450. This will update automatically on new commits. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeRamps
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
All 9 changed files are exclusively within the Ramp feature area (app/components/UI/Ramp/). The changes introduce a new "headless" buy flow capability:

1. New useHeadlessRamps.ts hook - Enables programmatic ramp buy flows without full UI, integrating with RampsController via Engine.controllerMessenger.
2. New headlessBuySessionRegistry.ts - Session tracking utility for headless buy orders.
3. useTransakRouting.ts - Added headlessSessionId propagation through Transak routing.
4. BuildQuote.tsx - Added headlessBuy params, auto-continue logic, and simplified headless UI mode.
5. Checkout.tsx - Added headlessSessionId tracking for order registration.
6. NativeFlow screens (EnterEmail, OtpCode, VerifyIdentity) - Added headlessSessionId propagation through the native authentication flow.

The changes modify core ramp flow screens (BuildQuote, Checkout) and add new routing logic. While the headless flow is additive, the modifications to existing screens (BuildQuote auto-continue logic, Checkout order tracking) could affect the standard ramp buy flow. SmokeRamps tests cover the fiat on-ramp/off-ramp features including the buy flow, amount input, and checkout screens that are directly modified here.

No other feature areas are affected - there are no changes to navigation infrastructure, shared controllers, or components used by other test suites.

Performance Test Selection:
The changes are focused on adding a headless buy flow capability to the Ramp feature. These are logic/orchestration changes (session tracking, routing, auto-continue) rather than UI rendering performance changes. No list rendering, animation, or data loading patterns that would impact measurable performance metrics are modified. No performance test tags are relevant.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[cursor]

Memory leak from useRef calling side-effect every render

Medium Severity

useRef(registerHeadlessBuySession()) calls registerHeadlessBuySession() on every render in React 18, since useRef evaluates its argument each time but only uses the result on the first render. Each call adds a new entry to the module-level headlessBuySessions Map, but only the first session (in sessionIdRef.current) is ever cleaned up via unregisterHeadlessBuySession on unmount. All subsequent sessions leak permanently in the global Map.

 

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
18 value mismatches detected (expected — fixture represents an existing user).
View details

[sonarqubecloud]

Quality Gate failed

Failed conditions
54.3% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud