Description

Introduces the CardController shell into the Engine as the first step toward the multi-provider Card architecture.

Why: The Card feature is tightly coupled to Baanx with business logic scattered across hooks, views, and a 2,600-line SDK monolith. To support multiple card providers and clean up the architecture, we need a proper Engine controller that owns the Card feature's persistent state. This PR lays the foundation — an inert controller that holds state and syncs it to Redux via the standard Engine batcher. No user-facing changes.

What changed:

New files:

• app/core/Engine/controllers/card-controller/types.ts: Defines CardControllerState (5 fields: selectedCountry, activeProviderId, isAuthenticated, cardholderAccounts, providerData), default state factory, and action/event/messenger types.
• app/core/Engine/controllers/card-controller/CardController.ts: Bare-bones controller extending BaseController. All state is persisted and marked usedInUi: true. No business logic yet — provider delegation comes in subsequent PRs.
• app/core/Engine/controllers/card-controller/index.ts: Init function following the standard Engine pattern — reads persisted state, creates controller instance.
• app/core/Engine/messengers/card-controller-messenger/index.ts: Simple messenger with no delegated actions/events (those will be added when the controller needs to talk to KeyringController, TransactionController, etc.).
• app/selectors/cardController.ts: Four selectors: selectCardSelectedCountry, selectCardActiveProviderId, selectIsCardAuthenticated, selectCardholderAccounts.

Modified files:

• app/core/Engine/types.ts: Added CardController to Controllers, EngineState, GlobalActions, GlobalEvents, and ControllersToInitialize.
• app/core/Engine/Engine.ts: Registered init function, destructured from controllersByName, added to this.context and state getter.
• app/core/Engine/messengers/index.ts: Added CardController entry to CONTROLLER_MESSENGERS.
• app/core/Engine/constants.ts: Added 'CardController:stateChange' to BACKGROUND_STATE_CHANGE_EVENT_NAMES.
• app/util/test/initial-background-state.json: Added CardController default state to the test fixture.
• .github/CODEOWNERS: Assigned app/core/Engine/controllers/card-controller, app/core/Engine/messengers/card-controller-messenger, and app/selectors/cardController.ts to @MetaMask/card.

Test files:

• CardController.test.ts: Tests controller construction with default state, partial state, and full persisted state.
• index.test.ts: Tests the init function returns a controller instance, uses default state when none is persisted, and uses persisted state when provided.
• cardController.test.ts: Tests all four selectors with populated state, empty state, and undefined CardController state (fallback values).

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Manual testing steps

Feature: CardController initialization

  Scenario: Controller initializes with default state on fresh install
    Given the app is freshly installed
    When the Engine initializes
    Then state.engine.backgroundState.CardController exists
    And selectedCountry is null
    And activeProviderId is null
    And isAuthenticated is false
    And cardholderAccounts is an empty array
    And providerData is an empty object

  Scenario: Controller state persists across app restarts
    Given the app has been launched before
    And CardController state was persisted
    When the Engine initializes again
    Then the persisted CardController state is restored

  Scenario: No user-facing changes
    Given the user is on any screen in the app
    When the app loads
    Then nothing visually changes
    And the Card feature continues to work as before

Screenshots/Recordings

No UI changes — this is an infrastructure-only PR.

Before

No CardController in Engine. Card state managed entirely by Redux slice.

After

CardController exists in Engine with default state. Syncs to state.engine.backgroundState.CardController. Existing Card feature behavior is unchanged.

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.