feat(card): add CardController shell to Engine (MetaMask#27020)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **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**

```gherkin
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**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it updates core Engine initialization/types and
introduces new persisted background state, which could affect startup or
state serialization despite having no business logic yet.
> 
> **Overview**
> Introduces a new `CardController` (BaseController) that persists Card
feature state (`selectedCountry`, `activeProviderId`, `isAuthenticated`,
`cardholderAccounts`, `providerData`) and exposes it via the standard
Engine background state batching.
> 
> Wires the controller into Engine initialization and messaging
(`Engine.ts`, `messengers/index.ts`, `types.ts`, `constants.ts`) so
`CardController` state is included in `Engine.state`, state-change
subscriptions, and debug/state log fixtures.
> 
> Adds initial selectors in `selectors/cardController.ts`, plus unit
tests for controller construction/init and selector fallbacks, and
updates `CODEOWNERS` for new Card Engine paths.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
8363bb1. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Brunonascdev

.github/CODEOWNERS

@@ -70,8 +70,11 @@ app/selectors/rampsController                          @MetaMask/ramp
 **/ramps/**                                             @MetaMask/ramp
 
 # Card Team
-app/components/UI/Card/              @MetaMask/card
-app/core/redux/slices/card/          @MetaMask/card
+app/components/UI/Card/                                    @MetaMask/card
+app/core/redux/slices/card/                                @MetaMask/card
+app/core/Engine/controllers/card-controller                @MetaMask/card
+app/core/Engine/messengers/card-controller-messenger       @MetaMask/card
+app/selectors/cardController.ts                            @MetaMask/card
 
 # Confirmation Team
 app/components/Views/confirmations                          @MetaMask/confirmations

app/core/Engine/Engine.ts

@@ -177,6 +177,7 @@ import { profileMetricsServiceInit } from './controllers/profile-metrics-service
 import { rampsServiceInit } from './controllers/ramps-controller/ramps-service-init';
 import { rampsControllerInit } from './controllers/ramps-controller/ramps-controller-init';
 import { aiDigestControllerInit } from './controllers/ai-digest-controller-init';
+import { cardControllerInit } from './controllers/card-controller';
 import { transakServiceInit } from './controllers/ramps-controller/transak-service-init';
 
 // TODO: Replace "any" with type
@@ -371,6 +372,7 @@ export class Engine {
         TransakService: transakServiceInit,
         RampsController: rampsControllerInit,
         AiDigestController: aiDigestControllerInit,
+        CardController: cardControllerInit,
       },
       persistedState: initialState as EngineState,
       baseControllerMessenger: this.controllerMessenger,
@@ -411,6 +413,7 @@ export class Engine {
     const transakService = controllersByName.TransakService;
     const rampsController = controllersByName.RampsController;
     const aiDigestController = controllersByName.AiDigestController;
+    const cardController = controllersByName.CardController;
 
     // Backwards compatibility for existing references
     this.accountsController = accountsController;
@@ -569,6 +572,7 @@ export class Engine {
       TransakService: transakService,
       RampsController: rampsController,
       AiDigestController: aiDigestController,
+      CardController: cardController,
     };
 
     const childControllers = Object.assign({}, this.context);
@@ -1291,6 +1295,7 @@ export default {
       ApprovalController,
       BridgeController,
       BridgeStatusController,
+      CardController,
       ConnectivityController,
       CurrencyRateController,
       DeFiPositionsController,
@@ -1394,6 +1399,7 @@ export default {
       TransactionPayController: TransactionPayController.state,
       RampsController: RampsController.state,
       AiDigestController: AiDigestController.state,
+      CardController: CardController.state,
       ///: BEGIN:ONLY_INCLUDE_IF(preinstalled-snaps,external-snaps)
       AuthenticationController: AuthenticationController.state,
       CronjobController: CronjobController.state,

app/core/Engine/constants.ts

@@ -83,6 +83,7 @@ export const BACKGROUND_STATE_CHANGE_EVENT_NAMES = [
   ///: END:ONLY_INCLUDE_IF
   'NetworkEnablementController:stateChange',
   'PredictController:stateChange',
+  'CardController:stateChange',
   'DelegationController:stateChange',
   'ProfileMetricsController:stateChange',
 ] as const;

app/core/Engine/controllers/card-controller/CardController.test.ts

@@ -0,0 +1,77 @@
+import { Messenger } from '@metamask/messenger';
+import { CardController, defaultCardControllerState } from './CardController';
+import { type CardControllerActions, type CardControllerEvents } from './types';
+
+function buildMessenger() {
+  return new Messenger<
+    'CardController',
+    CardControllerActions,
+    CardControllerEvents
+  >({ namespace: 'CardController' });
+}
+
+describe('CardController', () => {
+  it('initializes with default state when no state is provided', () => {
+    const controller = new CardController({
+      messenger: buildMessenger(),
+    });
+
+    expect(controller.state).toStrictEqual(defaultCardControllerState);
+  });
+
+  it('initializes with provided state merged over defaults', () => {
+    const controller = new CardController({
+      messenger: buildMessenger(),
+      state: {
+        selectedCountry: 'US',
+        activeProviderId: 'baanx',
+        isAuthenticated: true,
+      },
+    });
+
+    expect(controller.state).toStrictEqual({
+      selectedCountry: 'US',
+      activeProviderId: 'baanx',
+      isAuthenticated: true,
+      cardholderAccounts: [],
+      providerData: {},
+    });
+  });
+
+  it('preserves default values for fields not in partial state', () => {
+    const controller = new CardController({
+      messenger: buildMessenger(),
+      state: {
+        selectedCountry: 'GB',
+      },
+    });
+
+    expect(controller.state.selectedCountry).toBe('GB');
+    expect(controller.state.activeProviderId).toBeNull();
+    expect(controller.state.isAuthenticated).toBe(false);
+    expect(controller.state.cardholderAccounts).toStrictEqual([]);
+    expect(controller.state.providerData).toStrictEqual({});
+  });
+
+  it('initializes with full persisted state including providerData', () => {
+    const controller = new CardController({
+      messenger: buildMessenger(),
+      state: {
+        selectedCountry: 'US',
+        activeProviderId: 'baanx',
+        isAuthenticated: true,
+        cardholderAccounts: ['eip155:1:0xabc'],
+        providerData: {
+          baanx: { location: 'us' },
+        },
+      },
+    });
+
+    expect(controller.state.cardholderAccounts).toStrictEqual([
+      'eip155:1:0xabc',
+    ]);
+    expect(controller.state.providerData).toStrictEqual({
+      baanx: { location: 'us' },
+    });
+  });
+});

app/core/Engine/controllers/card-controller/CardController.ts

@@ -0,0 +1,79 @@
+import { BaseController, type StateMetadata } from '@metamask/base-controller';
+import {
+  CARD_CONTROLLER_NAME,
+  type CardControllerMessenger,
+  type CardControllerState,
+} from './types';
+
+const metadata: StateMetadata<CardControllerState> = {
+  selectedCountry: {
+    persist: true,
+    includeInDebugSnapshot: true,
+    includeInStateLogs: true,
+    usedInUi: true,
+  },
+  activeProviderId: {
+    persist: true,
+    includeInDebugSnapshot: true,
+    includeInStateLogs: true,
+    usedInUi: true,
+  },
+  isAuthenticated: {
+    persist: true,
+    includeInDebugSnapshot: true,
+    includeInStateLogs: true,
+    usedInUi: true,
+  },
+  cardholderAccounts: {
+    persist: true,
+    includeInDebugSnapshot: true,
+    includeInStateLogs: true,
+    usedInUi: true,
+  },
+  providerData: {
+    persist: true,
+    includeInDebugSnapshot: false,
+    includeInStateLogs: false,
+    usedInUi: false,
+  },
+};
+
+export const defaultCardControllerState: CardControllerState = {
+  selectedCountry: null,
+  activeProviderId: null,
+  isAuthenticated: false,
+  cardholderAccounts: [],
+  providerData: {},
+};
+
+/**
+ * CardController manages the MetaMask Card feature state.
+ *
+ * This is a thin coordination layer that will eventually delegate
+ * to provider implementations. For now it owns the persisted state
+ * (country, provider, auth status) and syncs it to Redux via the
+ * standard Engine batcher.
+ */
+export class CardController extends BaseController<
+  typeof CARD_CONTROLLER_NAME,
+  CardControllerState,
+  CardControllerMessenger
+> {
+  constructor({
+    messenger,
+    state,
+  }: {
+    messenger: CardControllerMessenger;
+    state?: Partial<CardControllerState>;
+  }) {
+    super({
+      name: CARD_CONTROLLER_NAME,
+      messenger,
+      metadata,
+      state: {
+        ...defaultCardControllerState,
+        ...state,
+      },
+    });
+  }
+}

app/core/Engine/controllers/card-controller/index.test.ts

@@ -0,0 +1,70 @@
+import { ExtendedMessenger } from '../../../ExtendedMessenger';
+import { buildControllerInitRequestMock } from '../../utils/test-utils';
+import { ControllerInitRequest } from '../../types';
+import { CardController, defaultCardControllerState } from './CardController';
+import {
+  type CardControllerMessenger,
+  type CardControllerState,
+} from './types';
+import { cardControllerInit } from '.';
+import { MOCK_ANY_NAMESPACE, MockAnyNamespace } from '@metamask/messenger';
+
+jest.mock('./CardController', () => {
+  const actual = jest.requireActual('./CardController');
+  return {
+    ...actual,
+    CardController: jest.fn(actual.CardController),
+  };
+});
+
+describe('cardControllerInit', () => {
+  const cardControllerClassMock = jest.mocked(CardController);
+  let initRequestMock: jest.Mocked<
+    ControllerInitRequest<CardControllerMessenger>
+  >;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    const baseControllerMessenger = new ExtendedMessenger<MockAnyNamespace>({
+      namespace: MOCK_ANY_NAMESPACE,
+    });
+
+    initRequestMock = buildControllerInitRequestMock(baseControllerMessenger);
+  });
+
+  it('returns a controller instance', () => {
+    const result = cardControllerInit(initRequestMock);
+
+    expect(result.controller).toBeInstanceOf(CardController);
+  });
+
+  it('uses default state when no persisted state is provided', () => {
+    initRequestMock.persistedState = {};
+
+    cardControllerInit(initRequestMock);
+
+    const constructorArgs = cardControllerClassMock.mock.calls[0][0];
+    expect(constructorArgs.state).toStrictEqual(defaultCardControllerState);
+  });
+
+  it('uses persisted state when provided', () => {
+    const persistedState: CardControllerState = {
+      selectedCountry: 'US',
+      activeProviderId: 'baanx',
+      isAuthenticated: true,
+      cardholderAccounts: ['eip155:1:0xabc'],
+      providerData: { baanx: { location: 'us' } },
+    };
+
+    initRequestMock.persistedState = {
+      ...initRequestMock.persistedState,
+      CardController: persistedState,
+    };
+
+    cardControllerInit(initRequestMock);
+
+    const constructorArgs = cardControllerClassMock.mock.calls[0][0];
+    expect(constructorArgs.state).toStrictEqual(persistedState);
+  });
+});

app/core/Engine/controllers/card-controller/index.ts

@@ -0,0 +1,26 @@
+import type { ControllerInitFunction } from '../../types';
+import { CardController, defaultCardControllerState } from './CardController';
+import type { CardControllerMessenger } from './types';
+
+/**
+ * Initialize the CardController.
+ *
+ * @param request - The request object.
+ * @returns The CardController.
+ */
+export const cardControllerInit: ControllerInitFunction<
+  CardController,
+  CardControllerMessenger
+> = (request) => {
+  const { controllerMessenger, persistedState } = request;
+
+  const controller = new CardController({
+    messenger: controllerMessenger,
+    state: persistedState.CardController ?? defaultCardControllerState,
+  });
+
+  return { controller };
+};
+
+export { CardController };
+export type { CardControllerMessenger };

app/core/Engine/controllers/card-controller/types.ts

@@ -0,0 +1,41 @@
+import type {
+  ControllerGetStateAction,
+  ControllerStateChangeEvent,
+} from '@metamask/base-controller';
+import type { Messenger } from '@metamask/messenger';
+import type { Json } from '@metamask/utils';
+
+export const CARD_CONTROLLER_NAME = 'CardController';
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type CardControllerState = {
+  /** ISO 3166-1 alpha-2 country code selected by the user. */
+  selectedCountry: string | null;
+  /** Active provider ID, derived from selectedCountry. */
+  activeProviderId: string | null;
+  /** Whether the user is authenticated with the active provider. */
+  isAuthenticated: boolean;
+  /** CAIP-10 account IDs that are card holders. */
+  cardholderAccounts: string[];
+  /**
+   * Per-provider persistent data keyed by provider ID.
+   * Values are JSON-serializable objects (e.g. `{ location: 'us' }`).
+   */
+  providerData: Record<string, Record<string, Json>>;
+};
+
+export type CardControllerActions = ControllerGetStateAction<
+  typeof CARD_CONTROLLER_NAME,
+  CardControllerState
+>;
+
+export type CardControllerEvents = ControllerStateChangeEvent<
+  typeof CARD_CONTROLLER_NAME,
+  CardControllerState
+>;
+
+export type CardControllerMessenger = Messenger<
+  typeof CARD_CONTROLLER_NAME,
+  CardControllerActions,
+  CardControllerEvents
+>;

app/core/Engine/messengers/card-controller-messenger/index.ts

@@ -0,0 +1,27 @@
+import {
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+} from '@metamask/messenger';
+import type { CardControllerMessenger } from '../../controllers/card-controller/types';
+import type { RootMessenger } from '../../types';
+
+/**
+ * Get the CardControllerMessenger for the CardController.
+ *
+ * @param rootMessenger - The root messenger.
+ * @returns The CardControllerMessenger.
+ */
+export function getCardControllerMessenger(
+  rootMessenger: RootMessenger,
+): CardControllerMessenger {
+  return new Messenger<
+    'CardController',
+    MessengerActions<CardControllerMessenger>,
+    MessengerEvents<CardControllerMessenger>,
+    RootMessenger
+  >({
+    namespace: 'CardController',
+    parent: rootMessenger,
+  });
+}