feat(ClientController): init controller

.github/CODEOWNERS

@@ -108,6 +108,7 @@
 /packages/permission-log-controller             @MetaMask/wallet-integrations @MetaMask/core-platform
 /packages/remote-feature-flag-controller        @MetaMask/extension-platform @MetaMask/mobile-platform @MetaMask/core-platform
 /packages/storage-service                       @MetaMask/extension-platform @MetaMask/mobile-platform @MetaMask/core-platform
+/packages/client-controller                     @MetaMask/core-platform @MetaMask/extension-platform @MetaMask/mobile-platform
 
 ## Package Release related
 /packages/account-tree-controller/package.json  @MetaMask/accounts-engineers @MetaMask/core-platform
@@ -203,4 +204,6 @@
 /packages/claims-controller/package.json @MetaMask/web3auth @MetaMask/core-platform
 /packages/claims-controller/CHANGELOG.md @MetaMask/web3auth @MetaMask/core-platform
 /packages/ai-controllers/package.json @MetaMask/social-ai @MetaMask/core-platform
-/packages/ai-controllers/CHANGELOG.md @MetaMask/social-ai @MetaMask/core-platform
+/packages/ai-controllers/CHANGELOG.md @MetaMask/social-ai @MetaMask/core-platform
+/packages/client-controller/package.json @MetaMask/core-platform @MetaMask/extension-platform @MetaMask/mobile-platform
+/packages/client-controller/CHANGELOG.md @MetaMask/core-platform @MetaMask/extension-platform @MetaMask/mobile-platform

README.md

@@ -88,6 +88,7 @@ Each package in this repository has its own README where you can find installati
 - [`@metamask/subscription-controller`](packages/subscription-controller)
 - [`@metamask/transaction-controller`](packages/transaction-controller)
 - [`@metamask/transaction-pay-controller`](packages/transaction-pay-controller)
+- [`@metamask/ui-state-controller`](packages/ui-state-controller)
 - [`@metamask/user-operation-controller`](packages/user-operation-controller)
 
 <!-- end package list -->
@@ -166,6 +167,7 @@ linkStyle default opacity:0.5
   subscription_controller(["@metamask/subscription-controller"]);
   transaction_controller(["@metamask/transaction-controller"]);
   transaction_pay_controller(["@metamask/transaction-pay-controller"]);
+  ui_state_controller(["@metamask/ui-state-controller"]);
   user_operation_controller(["@metamask/user-operation-controller"]);
   account_tree_controller --> accounts_controller;
   account_tree_controller --> base_controller;
@@ -181,16 +183,29 @@ linkStyle default opacity:0.5
   address_book_controller --> base_controller;
   address_book_controller --> controller_utils;
   address_book_controller --> messenger;
+  ai_controllers --> base_controller;
+  ai_controllers --> messenger;
   analytics_controller --> base_controller;
   analytics_controller --> messenger;
+  analytics_data_regulation_controller --> base_controller;
+  analytics_data_regulation_controller --> controller_utils;
+  analytics_data_regulation_controller --> messenger;
   announcement_controller --> base_controller;
   announcement_controller --> messenger;
   app_metadata_controller --> base_controller;
   app_metadata_controller --> messenger;
   approval_controller --> base_controller;
   approval_controller --> messenger;
+  assets_controller --> account_tree_controller;
   assets_controller --> base_controller;
+  assets_controller --> controller_utils;
+  assets_controller --> core_backend;
+  assets_controller --> keyring_controller;
   assets_controller --> messenger;
+  assets_controller --> network_controller;
+  assets_controller --> network_enablement_controller;
+  assets_controller --> permission_controller;
+  assets_controller --> polling_controller;
   assets_controllers --> account_tree_controller;
   assets_controllers --> accounts_controller;
   assets_controllers --> approval_controller;
@@ -201,11 +216,13 @@ linkStyle default opacity:0.5
   assets_controllers --> messenger;
   assets_controllers --> multichain_account_service;
   assets_controllers --> network_controller;
+  assets_controllers --> network_enablement_controller;
   assets_controllers --> permission_controller;
   assets_controllers --> phishing_controller;
   assets_controllers --> polling_controller;
   assets_controllers --> preferences_controller;
   assets_controllers --> profile_sync_controller;
+  assets_controllers --> storage_service;
   assets_controllers --> transaction_controller;
   base_controller --> messenger;
   base_controller --> json_rpc_engine;
@@ -412,12 +429,11 @@ linkStyle default opacity:0.5
   subscription_controller --> polling_controller;
   subscription_controller --> profile_sync_controller;
   subscription_controller --> transaction_controller;
-  token_search_discovery_controller --> base_controller;
-  token_search_discovery_controller --> messenger;
   transaction_controller --> accounts_controller;
   transaction_controller --> approval_controller;
   transaction_controller --> base_controller;
   transaction_controller --> controller_utils;
+  transaction_controller --> core_backend;
   transaction_controller --> gas_fee_controller;
   transaction_controller --> messenger;
   transaction_controller --> network_controller;
@@ -434,6 +450,8 @@ linkStyle default opacity:0.5
   transaction_pay_controller --> network_controller;
   transaction_pay_controller --> remote_feature_flag_controller;
   transaction_pay_controller --> transaction_controller;
+  ui_state_controller --> base_controller;
+  ui_state_controller --> messenger;
   user_operation_controller --> approval_controller;
   user_operation_controller --> base_controller;
   user_operation_controller --> controller_utils;

packages/client-controller/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of `@metamask/client-controller` ([#7808](https://github.com/MetaMask/core/pull/7808))
+  - `ClientController` for managing client (UI) open/closed state
+  - `ClientController:setUiOpen` messenger action for platform code to call
+  - `ClientController:stateChange` event for controllers to subscribe to lifecycle changes
+  - `isUiOpen` state property (not persisted - always starts as `false`)
+  - `clientControllerSelectors.selectIsUiOpen` selector for derived state access
+  - Full TypeScript support with exported types
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/client-controller/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/client-controller/README.md

@@ -0,0 +1,180 @@
+# `@metamask/client-controller`
+
+Client-level state for MetaMask (e.g. whether a UI window is open). Provides a centralized way for controllers to respond to application lifecycle changes.
+
+## Installation
+
+```bash
+yarn add @metamask/client-controller
+```
+
+or
+
+```bash
+npm install @metamask/client-controller
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Messenger } from '@metamask/messenger';
+import {
+  ClientController,
+  ClientControllerActions,
+  ClientControllerEvents,
+} from '@metamask/client-controller';
+
+const rootMessenger = new Messenger<
+  'Root',
+  ClientControllerActions,
+  ClientControllerEvents
+>({ namespace: 'Root' });
+
+const controllerMessenger = new Messenger({
+  namespace: 'ClientController',
+  parent: rootMessenger,
+});
+
+const clientController = new ClientController({
+  messenger: controllerMessenger,
+});
+```
+
+### Platform Integration
+
+Platform code calls `ClientController:setUiOpen` when the UI is opened or
+closed:
+
+```text
+onUiOpened() {
+  controllerMessenger.call('ClientController:setUiOpen', true);
+}
+
+onUiClosed() {
+  controllerMessenger.call('ClientController:setUiOpen', false);
+}
+```
+
+### Consumer controller and using with other lifecycle state (e.g. Keyring unlock/lock)
+
+Use `ClientController:stateChange` only for behavior that **must** run when the
+UI is open or closed (e.g., pausing/resuming a critical background task). **Use
+the selector** when subscribing so the handler receives a single derived value
+(e.g. `isUiOpen`), and **prefer pause/resume** over stop/start for polling.
+
+UI open/close alone is usually not enough to decide when to start or stop work.
+Combine `ClientController:stateChange` with other lifecycle events, such as
+**KeyringController:unlock** / **KeyringController:lock** (or any controller that
+expresses "ready for background work"). Only start subscriptions, polling, or
+network requests when **both** the UI is open and the keyring (or equivalent) is
+unlocked; stop or pause when the UI closes **or** the keyring locks.
+
+#### Important: Usage guidelines and warnings
+
+**Do not subscribe to updates for all kinds of data as soon as the client
+opens.** When MetaMask opens, the current screen may not need every type of
+data. Starting subscriptions, polling, or network requests for everything when
+`isUiOpen` becomes true can lead to unnecessary network traffic and battery
+use, requests before onboarding is complete (a recurring source of issues), and
+poor performance as more features are added.
+
+**Use this controller responsibly:**
+
+- Start only the subscriptions, polling, or requests that are **needed for the
+  current screen or flow**
+- Do **not** start network-dependent or heavy behavior solely because
+  `ClientController:stateChange` reported `isUiOpen: true`
+- Consider **deferring** non-critical updates until the user has completed
+  onboarding or reached a screen that needs that data
+- Prefer starting and stopping per feature or per screen (e.g., when a
+  component mounts that needs the data) rather than globally when the client
+  opens
+- **Combine with Keyring unlock/lock:** Only start work when it is appropriate
+  for both UI open state and wallet state (e.g. client open **and** keyring
+  unlocked)
+- **Prefer pause/resume over stop/start for polling** so you can resume without
+  full re-initialization. Use the selector when subscribing (see example
+  below).
+
+```typescript
+import { clientControllerSelectors } from '@metamask/client-controller';
+
+class SomeDataController extends BaseController {
+  #uiOpen = false;
+  #keyringUnlocked = false;
+
+  constructor({ messenger }) {
+    super({ messenger, ... });
+
+    messenger.subscribe(
+      'ClientController:stateChange',
+      (isUiOpen) => {
+        this.#uiOpen = isUiOpen;
+        this.updateActive();
+      },
+      clientControllerSelectors.selectIsUiOpen,
+    );
+
+    messenger.subscribe('KeyringController:unlock', () => {
+      this.#keyringUnlocked = true;
+      this.updateActive();
+    });
+
+    messenger.subscribe('KeyringController:lock', () => {
+      this.#keyringUnlocked = false;
+      this.updateActive();
+    });
+  }
+
+  updateActive() {
+    const shouldRun = this.#uiOpen && this.#keyringUnlocked;
+    if (shouldRun) {
+      this.resume();
+    } else {
+      this.pause();
+    }
+  }
+}
+```
+
+Note: `stateChange` emits `[state, patches]`; the selector receives the full
+payload and returns the value passed to the handler (here, `isUiOpen`).
+
+## API Reference
+
+### State
+
+| Property   | Type      | Description                                |
+| ---------- | --------- | ------------------------------------------ |
+| `isUiOpen` | `boolean` | Whether the client (UI) is currently open. |
+
+State is not persisted. It always starts as `false`.
+
+### Actions
+
+| Action                       | Parameters      | Description                  |
+| ---------------------------- | --------------- | ---------------------------- |
+| `ClientController:getState`  | none            | Returns current state.       |
+| `ClientController:setUiOpen` | `open: boolean` | Sets whether the UI is open. |
+
+### Events
+
+| Event                          | Payload            | Description                  |
+| ------------------------------ | ------------------ | ---------------------------- |
+| `ClientController:stateChange` | `[state, patches]` | Standard state change event. |
+
+### Selectors
+
+```typescript
+import { clientControllerSelectors } from '@metamask/client-controller';
+
+const state = messenger.call('ClientController:getState');
+const isOpen = clientControllerSelectors.selectIsUiOpen(state);
+```
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found
+in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/client-controller/jest.config.js

@@ -0,0 +1,24 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const merge = require('deepmerge');
+const path = require('path');
+
+const baseConfig = require('../../jest.config.packages');
+
+const displayName = path.basename(__dirname);
+
+module.exports = merge(baseConfig, {
+  displayName,
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+});