@metamask-previews/client-controller 0.0.0-preview-a196307b6

package/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/

package/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.

package/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).

package/dist/ClientController-method-action-types.cjs

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ClientController-method-action-types.cjs.map

package/dist/ClientController-method-action-types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController-method-action-types.cjs","sourceRoot":"","sources":["../src/ClientController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { ClientController } from './ClientController';\n\n/**\n * Updates state with whether the MetaMask UI is open.\n *\n * This method should be called when the user has opened the first window or\n * screen containing the MetaMask UI, or closed the last window or screen\n * containing the MetaMask UI.\n *\n * @param open - Whether the MetaMask UI is open.\n */\nexport type ClientControllerSetUiOpenAction = {\n  type: `ClientController:setUiOpen`;\n  handler: ClientController['setUiOpen'];\n};\n\n/**\n * Union of all ClientController action types.\n */\nexport type ClientControllerMethodActions = ClientControllerSetUiOpenAction;\n"]}

package/dist/ClientController-method-action-types.d.cts

@@ -0,0 +1,23 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { ClientController } from "./ClientController.cjs";
+/**
+ * Updates state with whether the MetaMask UI is open.
+ *
+ * This method should be called when the user has opened the first window or
+ * screen containing the MetaMask UI, or closed the last window or screen
+ * containing the MetaMask UI.
+ *
+ * @param open - Whether the MetaMask UI is open.
+ */
+export type ClientControllerSetUiOpenAction = {
+    type: `ClientController:setUiOpen`;
+    handler: ClientController['setUiOpen'];
+};
+/**
+ * Union of all ClientController action types.
+ */
+export type ClientControllerMethodActions = ClientControllerSetUiOpenAction;
+//# sourceMappingURL=ClientController-method-action-types.d.cts.map

package/dist/ClientController-method-action-types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController-method-action-types.d.cts","sourceRoot":"","sources":["../src/ClientController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,+BAA2B;AAE3D;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,+BAA+B,CAAC"}

package/dist/ClientController-method-action-types.d.mts

@@ -0,0 +1,23 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { ClientController } from "./ClientController.mjs";
+/**
+ * Updates state with whether the MetaMask UI is open.
+ *
+ * This method should be called when the user has opened the first window or
+ * screen containing the MetaMask UI, or closed the last window or screen
+ * containing the MetaMask UI.
+ *
+ * @param open - Whether the MetaMask UI is open.
+ */
+export type ClientControllerSetUiOpenAction = {
+    type: `ClientController:setUiOpen`;
+    handler: ClientController['setUiOpen'];
+};
+/**
+ * Union of all ClientController action types.
+ */
+export type ClientControllerMethodActions = ClientControllerSetUiOpenAction;
+//# sourceMappingURL=ClientController-method-action-types.d.mts.map

package/dist/ClientController-method-action-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController-method-action-types.d.mts","sourceRoot":"","sources":["../src/ClientController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,+BAA2B;AAE3D;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,+BAA+B,CAAC"}

package/dist/ClientController-method-action-types.mjs

@@ -0,0 +1,6 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+export {};
+//# sourceMappingURL=ClientController-method-action-types.mjs.map

package/dist/ClientController-method-action-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController-method-action-types.mjs","sourceRoot":"","sources":["../src/ClientController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { ClientController } from './ClientController';\n\n/**\n * Updates state with whether the MetaMask UI is open.\n *\n * This method should be called when the user has opened the first window or\n * screen containing the MetaMask UI, or closed the last window or screen\n * containing the MetaMask UI.\n *\n * @param open - Whether the MetaMask UI is open.\n */\nexport type ClientControllerSetUiOpenAction = {\n  type: `ClientController:setUiOpen`;\n  handler: ClientController['setUiOpen'];\n};\n\n/**\n * Union of all ClientController action types.\n */\nexport type ClientControllerMethodActions = ClientControllerSetUiOpenAction;\n"]}

package/dist/ClientController.cjs

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientController = exports.getDefaultClientControllerState = exports.controllerName = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+// === GENERAL ===
+/**
+ * The name of the {@link ClientController}.
+ */
+exports.controllerName = 'ClientController';
+/**
+ * Constructs the default {@link ClientController} state.
+ *
+ * @returns The default {@link ClientController} state.
+ */
+function getDefaultClientControllerState() {
+    return {
+        isUiOpen: false,
+    };
+}
+exports.getDefaultClientControllerState = getDefaultClientControllerState;
+/**
+ * The metadata for each property in {@link ClientControllerState}.
+ */
+const controllerMetadata = {
+    isUiOpen: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: false,
+    },
+};
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = ['setUiOpen'];
+/**
+ * `ClientController` manages the application lifecycle state.
+ *
+ * This controller tracks whether the MetaMask UI is open and publishes state
+ * change events that other controllers can subscribe to for adjusting their behavior.
+ *
+ * **Use cases:**
+ * - Polling controllers can pause when the UI closes, resume when it opens
+ * - WebSocket connections can disconnect when closed, reconnect when opened
+ * - Real-time subscriptions can pause when not visible
+ *
+ * **Platform Integration:**
+ * Platform code should call `ClientController:setUiOpen` via messenger.
+ *
+ * @example
+ * ```typescript
+ * // In MetamaskController or platform code
+ * onUiOpened() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', true);
+ * }
+ *
+ * onUiClosed() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', false);
+ * }
+ *
+ * // Consumer controller subscribing to state changes
+ * class MyController extends BaseController {
+ *   constructor({ messenger }) {
+ *     super({ messenger, ... });
+ *
+ *     messenger.subscribe(
+ *       'ClientController:stateChange',
+ *       (isClientOpen) => {
+ *         if (isClientOpen) {
+ *           this.resumePolling();
+ *         } else {
+ *           this.pausePolling();
+ *         }
+ *       },
+ *       clientControllerSelectors.selectIsUiOpen,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+class ClientController extends base_controller_1.BaseController {
+    /**
+     * Constructs a new {@link ClientController}.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this controller.
+     * @param options.state - The initial state to set on this controller.
+     */
+    constructor({ messenger, state = {} }) {
+        super({
+            messenger,
+            metadata: controllerMetadata,
+            name: exports.controllerName,
+            state: {
+                ...getDefaultClientControllerState(),
+                ...state,
+            },
+        });
+        this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Updates state with whether the MetaMask UI is open.
+     *
+     * This method should be called when the user has opened the first window or
+     * screen containing the MetaMask UI, or closed the last window or screen
+     * containing the MetaMask UI.
+     *
+     * @param open - Whether the MetaMask UI is open.
+     */
+    setUiOpen(open) {
+        this.update((state) => {
+            state.isUiOpen = open;
+        });
+    }
+}
+exports.ClientController = ClientController;
+//# sourceMappingURL=ClientController.cjs.map

package/dist/ClientController.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController.cjs","sourceRoot":"","sources":["../src/ClientController.ts"],"names":[],"mappings":";;;AAKA,+DAA2D;AAK3D,kBAAkB;AAElB;;GAEG;AACU,QAAA,cAAc,GAAG,kBAAkB,CAAC;AAgBjD;;;;GAIG;AACH,SAAgB,+BAA+B;IAC7C,OAAO;QACL,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC;AAJD,0EAIC;AAED;;GAEG;AACH,MAAM,kBAAkB,GAAG;IACzB,QAAQ,EAAE;QACR,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,KAAK;KAChB;CAC6C,CAAC;AAEjD,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG,CAAC,WAAW,CAAU,CAAC;AAiEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAa,gBAAiB,SAAQ,gCAIrC;IACC;;;;;;OAMG;IACH,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,EAAE,EAA2B;QAC5D,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,kBAAkB;YAC5B,IAAI,EAAE,sBAAc;YACpB,KAAK,EAAE;gBACL,GAAG,+BAA+B,EAAE;gBACpC,GAAG,KAAK;aACT;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,CAAC,4BAA4B,CACzC,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAa;QACrB,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACxB,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AA3CD,4CA2CC","sourcesContent":["import type {\n  StateMetadata,\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { ClientControllerMethodActions } from './ClientController-method-action-types';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link ClientController}.\n */\nexport const controllerName = 'ClientController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link ClientController}.\n */\nexport type ClientControllerState = {\n  /**\n   * Whether the user has opened at least one window or screen\n   * containing the MetaMask UI. These windows or screens may or\n   * may not be in an inactive state.\n   */\n  isUiOpen: boolean;\n};\n\n/**\n * Constructs the default {@link ClientController} state.\n *\n * @returns The default {@link ClientController} state.\n */\nexport function getDefaultClientControllerState(): ClientControllerState {\n  return {\n    isUiOpen: false,\n  };\n}\n\n/**\n * The metadata for each property in {@link ClientControllerState}.\n */\nconst controllerMetadata = {\n  isUiOpen: {\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    persist: false,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<ClientControllerState>;\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = ['setUiOpen'] as const;\n\n/**\n * Retrieves the state of the {@link ClientController}.\n */\nexport type ClientControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  ClientControllerState\n>;\n\n/**\n * Actions that {@link ClientController} exposes.\n */\nexport type ClientControllerActions =\n  | ClientControllerGetStateAction\n  | ClientControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link ClientController} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Published when the state of {@link ClientController} changes.\n */\nexport type ClientControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  ClientControllerState\n>;\n\n/**\n * Events that {@link ClientController} exposes.\n */\nexport type ClientControllerEvents = ClientControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link ClientController} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger for {@link ClientController}.\n */\nexport type ClientControllerMessenger = Messenger<\n  typeof controllerName,\n  ClientControllerActions | AllowedActions,\n  ClientControllerEvents | AllowedEvents\n>;\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * The options for constructing a {@link ClientController}.\n */\nexport type ClientControllerOptions = {\n  /**\n   * The messenger suited for this controller.\n   */\n  messenger: ClientControllerMessenger;\n  /**\n   * The initial state to set on this controller.\n   */\n  state?: Partial<ClientControllerState>;\n};\n\n/**\n * `ClientController` manages the application lifecycle state.\n *\n * This controller tracks whether the MetaMask UI is open and publishes state\n * change events that other controllers can subscribe to for adjusting their behavior.\n *\n * **Use cases:**\n * - Polling controllers can pause when the UI closes, resume when it opens\n * - WebSocket connections can disconnect when closed, reconnect when opened\n * - Real-time subscriptions can pause when not visible\n *\n * **Platform Integration:**\n * Platform code should call `ClientController:setUiOpen` via messenger.\n *\n * @example\n * ```typescript\n * // In MetamaskController or platform code\n * onUiOpened() {\n *   // ...\n *   this.controllerMessenger.call('ClientController:setUiOpen', true);\n * }\n *\n * onUiClosed() {\n *   // ...\n *   this.controllerMessenger.call('ClientController:setUiOpen', false);\n * }\n *\n * // Consumer controller subscribing to state changes\n * class MyController extends BaseController {\n *   constructor({ messenger }) {\n *     super({ messenger, ... });\n *\n *     messenger.subscribe(\n *       'ClientController:stateChange',\n *       (isClientOpen) => {\n *         if (isClientOpen) {\n *           this.resumePolling();\n *         } else {\n *           this.pausePolling();\n *         }\n *       },\n *       clientControllerSelectors.selectIsUiOpen,\n *     );\n *   }\n * }\n * ```\n */\nexport class ClientController extends BaseController<\n  typeof controllerName,\n  ClientControllerState,\n  ClientControllerMessenger\n> {\n  /**\n   * Constructs a new {@link ClientController}.\n   *\n   * @param options - The constructor options.\n   * @param options.messenger - The messenger suited for this controller.\n   * @param options.state - The initial state to set on this controller.\n   */\n  constructor({ messenger, state = {} }: ClientControllerOptions) {\n    super({\n      messenger,\n      metadata: controllerMetadata,\n      name: controllerName,\n      state: {\n        ...getDefaultClientControllerState(),\n        ...state,\n      },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Updates state with whether the MetaMask UI is open.\n   *\n   * This method should be called when the user has opened the first window or\n   * screen containing the MetaMask UI, or closed the last window or screen\n   * containing the MetaMask UI.\n   *\n   * @param open - Whether the MetaMask UI is open.\n   */\n  setUiOpen(open: boolean): void {\n    this.update((state) => {\n      state.isUiOpen = open;\n    });\n  }\n}\n"]}

package/dist/ClientController.d.cts

@@ -0,0 +1,135 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { ClientControllerMethodActions } from "./ClientController-method-action-types.cjs";
+/**
+ * The name of the {@link ClientController}.
+ */
+export declare const controllerName = "ClientController";
+/**
+ * Describes the shape of the state object for {@link ClientController}.
+ */
+export type ClientControllerState = {
+    /**
+     * Whether the user has opened at least one window or screen
+     * containing the MetaMask UI. These windows or screens may or
+     * may not be in an inactive state.
+     */
+    isUiOpen: boolean;
+};
+/**
+ * Constructs the default {@link ClientController} state.
+ *
+ * @returns The default {@link ClientController} state.
+ */
+export declare function getDefaultClientControllerState(): ClientControllerState;
+/**
+ * Retrieves the state of the {@link ClientController}.
+ */
+export type ClientControllerGetStateAction = ControllerGetStateAction<typeof controllerName, ClientControllerState>;
+/**
+ * Actions that {@link ClientController} exposes.
+ */
+export type ClientControllerActions = ClientControllerGetStateAction | ClientControllerMethodActions;
+/**
+ * Actions from other messengers that {@link ClientController} calls.
+ */
+type AllowedActions = never;
+/**
+ * Published when the state of {@link ClientController} changes.
+ */
+export type ClientControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, ClientControllerState>;
+/**
+ * Events that {@link ClientController} exposes.
+ */
+export type ClientControllerEvents = ClientControllerStateChangeEvent;
+/**
+ * Events from other messengers that {@link ClientController} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger for {@link ClientController}.
+ */
+export type ClientControllerMessenger = Messenger<typeof controllerName, ClientControllerActions | AllowedActions, ClientControllerEvents | AllowedEvents>;
+/**
+ * The options for constructing a {@link ClientController}.
+ */
+export type ClientControllerOptions = {
+    /**
+     * The messenger suited for this controller.
+     */
+    messenger: ClientControllerMessenger;
+    /**
+     * The initial state to set on this controller.
+     */
+    state?: Partial<ClientControllerState>;
+};
+/**
+ * `ClientController` manages the application lifecycle state.
+ *
+ * This controller tracks whether the MetaMask UI is open and publishes state
+ * change events that other controllers can subscribe to for adjusting their behavior.
+ *
+ * **Use cases:**
+ * - Polling controllers can pause when the UI closes, resume when it opens
+ * - WebSocket connections can disconnect when closed, reconnect when opened
+ * - Real-time subscriptions can pause when not visible
+ *
+ * **Platform Integration:**
+ * Platform code should call `ClientController:setUiOpen` via messenger.
+ *
+ * @example
+ * ```typescript
+ * // In MetamaskController or platform code
+ * onUiOpened() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', true);
+ * }
+ *
+ * onUiClosed() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', false);
+ * }
+ *
+ * // Consumer controller subscribing to state changes
+ * class MyController extends BaseController {
+ *   constructor({ messenger }) {
+ *     super({ messenger, ... });
+ *
+ *     messenger.subscribe(
+ *       'ClientController:stateChange',
+ *       (isClientOpen) => {
+ *         if (isClientOpen) {
+ *           this.resumePolling();
+ *         } else {
+ *           this.pausePolling();
+ *         }
+ *       },
+ *       clientControllerSelectors.selectIsUiOpen,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class ClientController extends BaseController<typeof controllerName, ClientControllerState, ClientControllerMessenger> {
+    /**
+     * Constructs a new {@link ClientController}.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this controller.
+     * @param options.state - The initial state to set on this controller.
+     */
+    constructor({ messenger, state }: ClientControllerOptions);
+    /**
+     * Updates state with whether the MetaMask UI is open.
+     *
+     * This method should be called when the user has opened the first window or
+     * screen containing the MetaMask UI, or closed the last window or screen
+     * containing the MetaMask UI.
+     *
+     * @param open - Whether the MetaMask UI is open.
+     */
+    setUiOpen(open: boolean): void;
+}
+export {};
+//# sourceMappingURL=ClientController.d.cts.map

package/dist/ClientController.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController.d.cts","sourceRoot":"","sources":["../src/ClientController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EACxB,0BAA0B,EAC3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,6BAA6B,EAAE,mDAA+C;AAI5F;;GAEG;AACH,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAIjD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,qBAAqB,CAIvE;AAkBD;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG,wBAAwB,CACnE,OAAO,cAAc,EACrB,qBAAqB,CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,8BAA8B,GAC9B,6BAA6B,CAAC;AAElC;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG,0BAA0B,CACvE,OAAO,cAAc,EACrB,qBAAqB,CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,gCAAgC,CAAC;AAEtE;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,SAAS,CAC/C,OAAO,cAAc,EACrB,uBAAuB,GAAG,cAAc,EACxC,sBAAsB,GAAG,aAAa,CACvC,CAAC;AAIF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;OAEG;IACH,SAAS,EAAE,yBAAyB,CAAC;IACrC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAClD,OAAO,cAAc,EACrB,qBAAqB,EACrB,yBAAyB,CAC1B;IACC;;;;;;OAMG;gBACS,EAAE,SAAS,EAAE,KAAU,EAAE,EAAE,uBAAuB;IAiB9D;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAK/B"}

package/dist/ClientController.d.mts

@@ -0,0 +1,135 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { ClientControllerMethodActions } from "./ClientController-method-action-types.mjs";
+/**
+ * The name of the {@link ClientController}.
+ */
+export declare const controllerName = "ClientController";
+/**
+ * Describes the shape of the state object for {@link ClientController}.
+ */
+export type ClientControllerState = {
+    /**
+     * Whether the user has opened at least one window or screen
+     * containing the MetaMask UI. These windows or screens may or
+     * may not be in an inactive state.
+     */
+    isUiOpen: boolean;
+};
+/**
+ * Constructs the default {@link ClientController} state.
+ *
+ * @returns The default {@link ClientController} state.
+ */
+export declare function getDefaultClientControllerState(): ClientControllerState;
+/**
+ * Retrieves the state of the {@link ClientController}.
+ */
+export type ClientControllerGetStateAction = ControllerGetStateAction<typeof controllerName, ClientControllerState>;
+/**
+ * Actions that {@link ClientController} exposes.
+ */
+export type ClientControllerActions = ClientControllerGetStateAction | ClientControllerMethodActions;
+/**
+ * Actions from other messengers that {@link ClientController} calls.
+ */
+type AllowedActions = never;
+/**
+ * Published when the state of {@link ClientController} changes.
+ */
+export type ClientControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, ClientControllerState>;
+/**
+ * Events that {@link ClientController} exposes.
+ */
+export type ClientControllerEvents = ClientControllerStateChangeEvent;
+/**
+ * Events from other messengers that {@link ClientController} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger for {@link ClientController}.
+ */
+export type ClientControllerMessenger = Messenger<typeof controllerName, ClientControllerActions | AllowedActions, ClientControllerEvents | AllowedEvents>;
+/**
+ * The options for constructing a {@link ClientController}.
+ */
+export type ClientControllerOptions = {
+    /**
+     * The messenger suited for this controller.
+     */
+    messenger: ClientControllerMessenger;
+    /**
+     * The initial state to set on this controller.
+     */
+    state?: Partial<ClientControllerState>;
+};
+/**
+ * `ClientController` manages the application lifecycle state.
+ *
+ * This controller tracks whether the MetaMask UI is open and publishes state
+ * change events that other controllers can subscribe to for adjusting their behavior.
+ *
+ * **Use cases:**
+ * - Polling controllers can pause when the UI closes, resume when it opens
+ * - WebSocket connections can disconnect when closed, reconnect when opened
+ * - Real-time subscriptions can pause when not visible
+ *
+ * **Platform Integration:**
+ * Platform code should call `ClientController:setUiOpen` via messenger.
+ *
+ * @example
+ * ```typescript
+ * // In MetamaskController or platform code
+ * onUiOpened() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', true);
+ * }
+ *
+ * onUiClosed() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', false);
+ * }
+ *
+ * // Consumer controller subscribing to state changes
+ * class MyController extends BaseController {
+ *   constructor({ messenger }) {
+ *     super({ messenger, ... });
+ *
+ *     messenger.subscribe(
+ *       'ClientController:stateChange',
+ *       (isClientOpen) => {
+ *         if (isClientOpen) {
+ *           this.resumePolling();
+ *         } else {
+ *           this.pausePolling();
+ *         }
+ *       },
+ *       clientControllerSelectors.selectIsUiOpen,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class ClientController extends BaseController<typeof controllerName, ClientControllerState, ClientControllerMessenger> {
+    /**
+     * Constructs a new {@link ClientController}.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this controller.
+     * @param options.state - The initial state to set on this controller.
+     */
+    constructor({ messenger, state }: ClientControllerOptions);
+    /**
+     * Updates state with whether the MetaMask UI is open.
+     *
+     * This method should be called when the user has opened the first window or
+     * screen containing the MetaMask UI, or closed the last window or screen
+     * containing the MetaMask UI.
+     *
+     * @param open - Whether the MetaMask UI is open.
+     */
+    setUiOpen(open: boolean): void;
+}
+export {};
+//# sourceMappingURL=ClientController.d.mts.map

package/dist/ClientController.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController.d.mts","sourceRoot":"","sources":["../src/ClientController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EACxB,0BAA0B,EAC3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,6BAA6B,EAAE,mDAA+C;AAI5F;;GAEG;AACH,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAIjD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,qBAAqB,CAIvE;AAkBD;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG,wBAAwB,CACnE,OAAO,cAAc,EACrB,qBAAqB,CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,8BAA8B,GAC9B,6BAA6B,CAAC;AAElC;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG,0BAA0B,CACvE,OAAO,cAAc,EACrB,qBAAqB,CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,gCAAgC,CAAC;AAEtE;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,SAAS,CAC/C,OAAO,cAAc,EACrB,uBAAuB,GAAG,cAAc,EACxC,sBAAsB,GAAG,aAAa,CACvC,CAAC;AAIF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;OAEG;IACH,SAAS,EAAE,yBAAyB,CAAC;IACrC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,gBAAiB,SAAQ,cAAc,CAClD,OAAO,cAAc,EACrB,qBAAqB,EACrB,yBAAyB,CAC1B;IACC;;;;;;OAMG;gBACS,EAAE,SAAS,EAAE,KAAU,EAAE,EAAE,uBAAuB;IAiB9D;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAK/B"}

package/dist/ClientController.mjs

@@ -0,0 +1,112 @@
+import { BaseController } from "@metamask/base-controller";
+// === GENERAL ===
+/**
+ * The name of the {@link ClientController}.
+ */
+export const controllerName = 'ClientController';
+/**
+ * Constructs the default {@link ClientController} state.
+ *
+ * @returns The default {@link ClientController} state.
+ */
+export function getDefaultClientControllerState() {
+    return {
+        isUiOpen: false,
+    };
+}
+/**
+ * The metadata for each property in {@link ClientControllerState}.
+ */
+const controllerMetadata = {
+    isUiOpen: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: false,
+    },
+};
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = ['setUiOpen'];
+/**
+ * `ClientController` manages the application lifecycle state.
+ *
+ * This controller tracks whether the MetaMask UI is open and publishes state
+ * change events that other controllers can subscribe to for adjusting their behavior.
+ *
+ * **Use cases:**
+ * - Polling controllers can pause when the UI closes, resume when it opens
+ * - WebSocket connections can disconnect when closed, reconnect when opened
+ * - Real-time subscriptions can pause when not visible
+ *
+ * **Platform Integration:**
+ * Platform code should call `ClientController:setUiOpen` via messenger.
+ *
+ * @example
+ * ```typescript
+ * // In MetamaskController or platform code
+ * onUiOpened() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', true);
+ * }
+ *
+ * onUiClosed() {
+ *   // ...
+ *   this.controllerMessenger.call('ClientController:setUiOpen', false);
+ * }
+ *
+ * // Consumer controller subscribing to state changes
+ * class MyController extends BaseController {
+ *   constructor({ messenger }) {
+ *     super({ messenger, ... });
+ *
+ *     messenger.subscribe(
+ *       'ClientController:stateChange',
+ *       (isClientOpen) => {
+ *         if (isClientOpen) {
+ *           this.resumePolling();
+ *         } else {
+ *           this.pausePolling();
+ *         }
+ *       },
+ *       clientControllerSelectors.selectIsUiOpen,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export class ClientController extends BaseController {
+    /**
+     * Constructs a new {@link ClientController}.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this controller.
+     * @param options.state - The initial state to set on this controller.
+     */
+    constructor({ messenger, state = {} }) {
+        super({
+            messenger,
+            metadata: controllerMetadata,
+            name: controllerName,
+            state: {
+                ...getDefaultClientControllerState(),
+                ...state,
+            },
+        });
+        this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Updates state with whether the MetaMask UI is open.
+     *
+     * This method should be called when the user has opened the first window or
+     * screen containing the MetaMask UI, or closed the last window or screen
+     * containing the MetaMask UI.
+     *
+     * @param open - Whether the MetaMask UI is open.
+     */
+    setUiOpen(open) {
+        this.update((state) => {
+            state.isUiOpen = open;
+        });
+    }
+}
+//# sourceMappingURL=ClientController.mjs.map

package/dist/ClientController.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientController.mjs","sourceRoot":"","sources":["../src/ClientController.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAK3D,kBAAkB;AAElB;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAgBjD;;;;GAIG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,kBAAkB,GAAG;IACzB,QAAQ,EAAE;QACR,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,KAAK;KAChB;CAC6C,CAAC;AAEjD,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG,CAAC,WAAW,CAAU,CAAC;AAiEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,OAAO,gBAAiB,SAAQ,cAIrC;IACC;;;;;;OAMG;IACH,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,EAAE,EAA2B;QAC5D,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,kBAAkB;YAC5B,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE;gBACL,GAAG,+BAA+B,EAAE;gBACpC,GAAG,KAAK;aACT;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,CAAC,4BAA4B,CACzC,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAa;QACrB,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACxB,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import type {\n  StateMetadata,\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { ClientControllerMethodActions } from './ClientController-method-action-types';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link ClientController}.\n */\nexport const controllerName = 'ClientController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link ClientController}.\n */\nexport type ClientControllerState = {\n  /**\n   * Whether the user has opened at least one window or screen\n   * containing the MetaMask UI. These windows or screens may or\n   * may not be in an inactive state.\n   */\n  isUiOpen: boolean;\n};\n\n/**\n * Constructs the default {@link ClientController} state.\n *\n * @returns The default {@link ClientController} state.\n */\nexport function getDefaultClientControllerState(): ClientControllerState {\n  return {\n    isUiOpen: false,\n  };\n}\n\n/**\n * The metadata for each property in {@link ClientControllerState}.\n */\nconst controllerMetadata = {\n  isUiOpen: {\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    persist: false,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<ClientControllerState>;\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = ['setUiOpen'] as const;\n\n/**\n * Retrieves the state of the {@link ClientController}.\n */\nexport type ClientControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  ClientControllerState\n>;\n\n/**\n * Actions that {@link ClientController} exposes.\n */\nexport type ClientControllerActions =\n  | ClientControllerGetStateAction\n  | ClientControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link ClientController} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Published when the state of {@link ClientController} changes.\n */\nexport type ClientControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  ClientControllerState\n>;\n\n/**\n * Events that {@link ClientController} exposes.\n */\nexport type ClientControllerEvents = ClientControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link ClientController} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger for {@link ClientController}.\n */\nexport type ClientControllerMessenger = Messenger<\n  typeof controllerName,\n  ClientControllerActions | AllowedActions,\n  ClientControllerEvents | AllowedEvents\n>;\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * The options for constructing a {@link ClientController}.\n */\nexport type ClientControllerOptions = {\n  /**\n   * The messenger suited for this controller.\n   */\n  messenger: ClientControllerMessenger;\n  /**\n   * The initial state to set on this controller.\n   */\n  state?: Partial<ClientControllerState>;\n};\n\n/**\n * `ClientController` manages the application lifecycle state.\n *\n * This controller tracks whether the MetaMask UI is open and publishes state\n * change events that other controllers can subscribe to for adjusting their behavior.\n *\n * **Use cases:**\n * - Polling controllers can pause when the UI closes, resume when it opens\n * - WebSocket connections can disconnect when closed, reconnect when opened\n * - Real-time subscriptions can pause when not visible\n *\n * **Platform Integration:**\n * Platform code should call `ClientController:setUiOpen` via messenger.\n *\n * @example\n * ```typescript\n * // In MetamaskController or platform code\n * onUiOpened() {\n *   // ...\n *   this.controllerMessenger.call('ClientController:setUiOpen', true);\n * }\n *\n * onUiClosed() {\n *   // ...\n *   this.controllerMessenger.call('ClientController:setUiOpen', false);\n * }\n *\n * // Consumer controller subscribing to state changes\n * class MyController extends BaseController {\n *   constructor({ messenger }) {\n *     super({ messenger, ... });\n *\n *     messenger.subscribe(\n *       'ClientController:stateChange',\n *       (isClientOpen) => {\n *         if (isClientOpen) {\n *           this.resumePolling();\n *         } else {\n *           this.pausePolling();\n *         }\n *       },\n *       clientControllerSelectors.selectIsUiOpen,\n *     );\n *   }\n * }\n * ```\n */\nexport class ClientController extends BaseController<\n  typeof controllerName,\n  ClientControllerState,\n  ClientControllerMessenger\n> {\n  /**\n   * Constructs a new {@link ClientController}.\n   *\n   * @param options - The constructor options.\n   * @param options.messenger - The messenger suited for this controller.\n   * @param options.state - The initial state to set on this controller.\n   */\n  constructor({ messenger, state = {} }: ClientControllerOptions) {\n    super({\n      messenger,\n      metadata: controllerMetadata,\n      name: controllerName,\n      state: {\n        ...getDefaultClientControllerState(),\n        ...state,\n      },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Updates state with whether the MetaMask UI is open.\n   *\n   * This method should be called when the user has opened the first window or\n   * screen containing the MetaMask UI, or closed the last window or screen\n   * containing the MetaMask UI.\n   *\n   * @param open - Whether the MetaMask UI is open.\n   */\n  setUiOpen(open: boolean): void {\n    this.update((state) => {\n      state.isUiOpen = open;\n    });\n  }\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientControllerSelectors = exports.getDefaultClientControllerState = exports.ClientController = void 0;
+var ClientController_1 = require("./ClientController.cjs");
+Object.defineProperty(exports, "ClientController", { enumerable: true, get: function () { return ClientController_1.ClientController; } });
+Object.defineProperty(exports, "getDefaultClientControllerState", { enumerable: true, get: function () { return ClientController_1.getDefaultClientControllerState; } });
+var selectors_1 = require("./selectors.cjs");
+Object.defineProperty(exports, "clientControllerSelectors", { enumerable: true, get: function () { return selectors_1.clientControllerSelectors; } });
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2DAG4B;AAF1B,oHAAA,gBAAgB,OAAA;AAChB,mIAAA,+BAA+B,OAAA;AAEjC,6CAAwD;AAA/C,sHAAA,yBAAyB,OAAA","sourcesContent":["export {\n  ClientController,\n  getDefaultClientControllerState,\n} from './ClientController';\nexport { clientControllerSelectors } from './selectors';\n\nexport type {\n  ClientControllerState,\n  ClientControllerOptions,\n  ClientControllerGetStateAction,\n  ClientControllerActions,\n  ClientControllerStateChangeEvent,\n  ClientControllerEvents,\n  ClientControllerMessenger,\n} from './ClientController';\nexport type { ClientControllerSetUiOpenAction } from './ClientController-method-action-types';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,5 @@
+export { ClientController, getDefaultClientControllerState, } from "./ClientController.cjs";
+export { clientControllerSelectors } from "./selectors.cjs";
+export type { ClientControllerState, ClientControllerOptions, ClientControllerGetStateAction, ClientControllerActions, ClientControllerStateChangeEvent, ClientControllerEvents, ClientControllerMessenger, } from "./ClientController.cjs";
+export type { ClientControllerSetUiOpenAction } from "./ClientController-method-action-types.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,+BAA+B,GAChC,+BAA2B;AAC5B,OAAO,EAAE,yBAAyB,EAAE,wBAAoB;AAExD,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,uBAAuB,EACvB,gCAAgC,EAChC,sBAAsB,EACtB,yBAAyB,GAC1B,+BAA2B;AAC5B,YAAY,EAAE,+BAA+B,EAAE,mDAA+C"}

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+export { ClientController, getDefaultClientControllerState, } from "./ClientController.mjs";
+export { clientControllerSelectors } from "./selectors.mjs";
+export type { ClientControllerState, ClientControllerOptions, ClientControllerGetStateAction, ClientControllerActions, ClientControllerStateChangeEvent, ClientControllerEvents, ClientControllerMessenger, } from "./ClientController.mjs";
+export type { ClientControllerSetUiOpenAction } from "./ClientController-method-action-types.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,+BAA+B,GAChC,+BAA2B;AAC5B,OAAO,EAAE,yBAAyB,EAAE,wBAAoB;AAExD,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,uBAAuB,EACvB,gCAAgC,EAChC,sBAAsB,EACtB,yBAAyB,GAC1B,+BAA2B;AAC5B,YAAY,EAAE,+BAA+B,EAAE,mDAA+C"}

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export { ClientController, getDefaultClientControllerState } from "./ClientController.mjs";
+export { clientControllerSelectors } from "./selectors.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,+BAA+B,EAChC,+BAA2B;AAC5B,OAAO,EAAE,yBAAyB,EAAE,wBAAoB","sourcesContent":["export {\n  ClientController,\n  getDefaultClientControllerState,\n} from './ClientController';\nexport { clientControllerSelectors } from './selectors';\n\nexport type {\n  ClientControllerState,\n  ClientControllerOptions,\n  ClientControllerGetStateAction,\n  ClientControllerActions,\n  ClientControllerStateChangeEvent,\n  ClientControllerEvents,\n  ClientControllerMessenger,\n} from './ClientController';\nexport type { ClientControllerSetUiOpenAction } from './ClientController-method-action-types';\n"]}

package/dist/selectors.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientControllerSelectors = void 0;
+/**
+ * Selects whether the UI is currently open.
+ *
+ * @param state - The ClientController state.
+ * @returns True if the UI is open.
+ */
+const selectIsUiOpen = (state) => state.isUiOpen;
+/**
+ * Selectors for the ClientController state.
+ * These can be used with Redux or directly with controller state.
+ */
+exports.clientControllerSelectors = {
+    selectIsUiOpen,
+};
+//# sourceMappingURL=selectors.cjs.map

package/dist/selectors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.cjs","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAM,cAAc,GAAG,CAAC,KAA4B,EAAW,EAAE,CAC/D,KAAK,CAAC,QAAQ,CAAC;AAEjB;;;GAGG;AACU,QAAA,yBAAyB,GAAG;IACvC,cAAc;CACf,CAAC","sourcesContent":["import type { ClientControllerState } from './ClientController';\n\n/**\n * Selects whether the UI is currently open.\n *\n * @param state - The ClientController state.\n * @returns True if the UI is open.\n */\nconst selectIsUiOpen = (state: ClientControllerState): boolean =>\n  state.isUiOpen;\n\n/**\n * Selectors for the ClientController state.\n * These can be used with Redux or directly with controller state.\n */\nexport const clientControllerSelectors = {\n  selectIsUiOpen,\n};\n"]}

package/dist/selectors.d.cts

@@ -0,0 +1,9 @@
+import type { ClientControllerState } from "./ClientController.cjs";
+/**
+ * Selectors for the ClientController state.
+ * These can be used with Redux or directly with controller state.
+ */
+export declare const clientControllerSelectors: {
+    selectIsUiOpen: (state: ClientControllerState) => boolean;
+};
+//# sourceMappingURL=selectors.d.cts.map

package/dist/selectors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.cts","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,+BAA2B;AAWhE;;;GAGG;AACH,eAAO,MAAM,yBAAyB;4BAPP,qBAAqB,KAAG,OAAO;CAS7D,CAAC"}

package/dist/selectors.d.mts

@@ -0,0 +1,9 @@
+import type { ClientControllerState } from "./ClientController.mjs";
+/**
+ * Selectors for the ClientController state.
+ * These can be used with Redux or directly with controller state.
+ */
+export declare const clientControllerSelectors: {
+    selectIsUiOpen: (state: ClientControllerState) => boolean;
+};
+//# sourceMappingURL=selectors.d.mts.map

package/dist/selectors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.mts","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,+BAA2B;AAWhE;;;GAGG;AACH,eAAO,MAAM,yBAAyB;4BAPP,qBAAqB,KAAG,OAAO;CAS7D,CAAC"}

package/dist/selectors.mjs

@@ -0,0 +1,15 @@
+/**
+ * Selects whether the UI is currently open.
+ *
+ * @param state - The ClientController state.
+ * @returns True if the UI is open.
+ */
+const selectIsUiOpen = (state) => state.isUiOpen;
+/**
+ * Selectors for the ClientController state.
+ * These can be used with Redux or directly with controller state.
+ */
+export const clientControllerSelectors = {
+    selectIsUiOpen,
+};
+//# sourceMappingURL=selectors.mjs.map

package/dist/selectors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.mjs","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,cAAc,GAAG,CAAC,KAA4B,EAAW,EAAE,CAC/D,KAAK,CAAC,QAAQ,CAAC;AAEjB;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,cAAc;CACf,CAAC","sourcesContent":["import type { ClientControllerState } from './ClientController';\n\n/**\n * Selects whether the UI is currently open.\n *\n * @param state - The ClientController state.\n * @returns True if the UI is open.\n */\nconst selectIsUiOpen = (state: ClientControllerState): boolean =>\n  state.isUiOpen;\n\n/**\n * Selectors for the ClientController state.\n * These can be used with Redux or directly with controller state.\n */\nexport const clientControllerSelectors = {\n  selectIsUiOpen,\n};\n"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@metamask-previews/client-controller",
+  "version": "0.0.0-preview-a196307b6",
+  "description": "Client-level state for MetaMask (e.g. whether a UI window is open)",
+  "keywords": [
+    "MetaMask",
+    "Ethereum"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/client-controller#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "build:all": "ts-bridge --project tsconfig.build.json --verbose --clean",
+    "build:docs": "typedoc",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/client-controller",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/client-controller",
+    "publish:preview": "yarn npm publish --tag preview",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
+    "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
+    "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "dependencies": {
+    "@metamask/base-controller": "^9.0.0",
+    "@metamask/messenger": "^0.3.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^3.4.4",
+    "@ts-bridge/cli": "^0.6.4",
+    "@types/jest": "^29.5.14",
+    "deepmerge": "^4.2.2",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~5.3.3"
+  },
+  "engines": {
+    "node": "^18.18 || >=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}