Description

This draft PR stacks the Headless Buy proof-of-concept work through Phase 3 (plus Phase 3.1) on top of main. It is intended for incremental review and CI validation before follow-up phases (BuildQuote refactor, Headless Host, routing callbacks).

Scope vs main (full branch)

• Phase 1 — Dev-only Headless Buy playground (Ramp Settings entry when isInternalBuild), route registration, and a scrollable UI to inspect useRampsController catalog data with accordions, selectors, and summary.
• Phase 2 — useHeadlessBuy read-only facade: tokens, providers, payment methods, countries, orders, getQuotes, aggregated loading/errors; playground sandbox simulating an external consumer (hardcoded defaults + accordion overrides, quote details, i18n).
• Phase 3 — sessionRegistry (module-level Map for callbacks + params), startHeadlessBuy (creates session, navigates to BuildQuote with headlessSessionId), BuildQuoteParams.headlessSessionId plumbing, playground Start headless buy / Cancel / event log, and tests.

Diff vs previous POC branches (incremental)

Full branch vs main: main...poc/headless-buy-phase-3.

PLAN.md changes from Phase 2 → Phase 3

• Checklist: Phase 3 and 3.1 marked complete; Phase 4 wording updated to useContinueWithQuote(quote, ctx) and reuse by BuildQuote + headless callers; new Phase 5b (quote-first startHeadlessBuy({ quote })); Phase 8 expanded for flow dismissal → onClose, closeSession idempotency, and useHeadlessSessionDismissal (BuildQuote now, Headless Host after 4b).
• Architecture: “Key idea” no longer assumes pre-seeding the controller from the hook; it describes session registry + navigation param only, with Phase 3.1 clarifying no controller writes from useHeadlessBuy.
• Phase 3 section: Implementation steps reordered to match shipped behavior; explicit note that controller pre-seed was superseded by Phase 3.1.
• New Phase 3.1 section: Documents the type mismatch (setters expect PaymentMethod / Provider objects, not ids) and catalog hydration race; resolution is params on session only, resolution at destination.
• New Phase 5b section: Discriminated HeadlessBuyParams, Host behavior for continue-with-quote, tests, and deliverable for devs who already have a Quote from getQuotes.
• Expanded Phase 8: Table of triggers (user_dismissed, completed, consumer_cancelled, unknown), useHeadlessSessionDismissal, centralized closeSession, tests, and note that today the playground still needs manual cancel until this ships.

Not in this PR yet: BuildQuote does not read headlessSessionId or call session.callbacks — that remains Phase 4–8 per the plan. Consumer cancel() from Phase 3 is the only guaranteed session teardown besides GC.

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Jira: TRAM-3524 | TRAM-3525 | TRAM-3526

Manual testing steps

Feature: Headless Buy playground (internal build)

  Scenario: Open playground from Ramp settings
    Given the app is an internal build with dev Ramp settings visible
    When the user opens Ramp settings and taps the Headless Buy playground entry
    Then the Headless Buy playground screen is shown with catalog accordions and the headless consumer sandbox

  Scenario: Fetch quotes from the sandbox
    Given the user is on the Headless Buy playground
    When the user enters a positive fiat amount and taps Get quotes
    Then quotes are listed in the quotes section without crashing the app

  Scenario: Start headless buy and cancel from the sandbox
    Given the user is on the Headless Buy playground with a valid amount in the sandbox
    When the user taps Start headless buy
    Then the event log records a started session and BuildQuote opens with navigation
    When the user returns to the playground and taps Cancel headless session
    Then the session is cleared and onClose consumer_cancelled is reflected in the event log

Screenshots/Recordings

Before

N/A

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.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.