feat: ClientNode controller API additions + deprecate legacy controller API

.gitignore

@@ -13,3 +13,6 @@ isolated-*.log
 /.caude/
 .claude/
 docs/plans/
+
+# Local planning/SDD scratch (never committed)
+docs/superpowers/

CHANGELOG.md

@@ -15,16 +15,32 @@ The main work (all changes without a GitHub username in brackets in the below li
     - Fix: `Heap` now stores each item at most once and maintains its position index eagerly, so deleting an item added after an earlier deletion works reliably
 
 - @matter/node
+    - Feature: Added `ServerNode.peers.commissioned` returning the commissioned `ClientNode`s
+    - Feature: Added `ClientNode.disable()`/`enable()` to persistently disable/enable a commissioned peer
+    - Feature: Added a `ClientNode` connection-state engine — `lifecycle.connectionState`/`connectionStateChanged`/`isConnected` and the `NodeConnectionState` enum
+    - Feature: Added `ClientNodeLifecycle.isSeeded` and the `seeded` event, indicating a peer node's structure has been read from the device at least once
+    - Feature: Added `Behaviors.forCluster(clusterId)` to resolve a cluster behavior type by numeric cluster id
+    - Feature: Added `openBasicCommissioningWindow`/`openEnhancedCommissioningWindow` on `CommissioningClient`/`ClientNode` to open a commissioning window on a commissioned peer
+    - Feature: Added split/delegated commissioning — `CommissioningClient.CommissioningOptions.finalizeCommissioning` plus `ServerNode.peers.completeCommissioning(nodeId, discoveryData?, options?)`
+    - Feature: Added `NetworkServer.autoStartCommissionedPeers` (default true) to opt out of auto-starting commissioned peers when the node goes online
     - Enhancement: Custom server session intervals (idle/active interval, active threshold) are now configurable via `sessions.intervals`
+    - Adjustment: A node with commissioning disabled (e.g. a controller) now binds an ephemeral operational port instead of the standard Matter port (5540) when `NetworkServer.port` is unset; commissionable nodes still default to 5540 and an explicit port is always honored
+    - Fix: `endpoints.size` no longer double-counts the root endpoint
     - Fix: Optimize Cluster data updates when structures change for ClientNodes
     - Fix: Prevent subscriptions from being activated on a closing session
 
+- @matter/types
+    - Feature: Added the `ClusterLookup` namespace for cluster/attribute/command/event name↔id resolution (optional `MatterModel` for custom clusters)
+
 - @matter/protocol
     - Enhancement: Connect to a newly discovered address as soon as it supersedes the previously cached address instead of waiting out the connection retry delay
     - Fix: Ensure the commissioning failsafe timer stays within the device's maximum cumulative failsafe
     - Fix: Parallel PASE commissioning now uses the won session immediately instead of blocking on losing attempts' cleanup, which could let the won session expire at the device failsafe before use
     - Fix: A device dropped during parallel PASE for invalid credentials no longer accepts a slower successful attempt on another of its addresses
 
+- @project-chip/matter.js
+    - Deprecation: The legacy controller/device API (CommissioningController, PairedNode, Device/Endpoint/Aggregator, cluster clients) is officially deprecated and will be removed in 0.19; migrate to @matter/node
+
 ## 0.17.6 (2026-07-16)
 
 - @matter/general

packages/matter.js/src/CommissioningController.ts

@@ -77,6 +77,7 @@ function discoveryKey(
     return JSON.stringify({ id: identifierData, caps: discoveryCapabilities });
 }
 
+/** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
 export async function runDiscoverCommissionableDevices(
     node: ServerNode,
     identifierData: CommissionableDeviceIdentifiers,
@@ -113,6 +114,7 @@ export async function runDiscoverCommissionableDevices(
     }
 }
 
+/** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
 export function cancelDiscoverCommissionableDevices(
     identifierData: CommissionableDeviceIdentifiers,
     discoveryCapabilities: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap> | undefined,
@@ -125,6 +127,9 @@ export function cancelDiscoverCommissionableDevices(
 // TODO decline using setRoot*Cluster
 // TODO Decline cluster access after announced/paired
 
+/**
+ * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+ */
 export type ControllerEnvironmentOptions = {
     /**
      * Environment to register the node with on start()
@@ -139,6 +144,8 @@ export type ControllerEnvironmentOptions = {
 
 /**
  * Constructor options for the CommissioningController class
+ *
+ * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
  */
 export type CommissioningControllerOptions = CommissioningControllerNodeOptions & {
     /**
@@ -238,6 +245,8 @@ export type CommissioningControllerOptions = CommissioningControllerNodeOptions
 /**
  * Configuration for performing discovery + commissioning in one step.
  * Kept in the legacy matter.js package; new code uses {@link CommissioningDiscovery.Options} directly.
+ *
+ * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
  */
 export interface DiscoveryAndCommissioningOptions extends CommissioningOptions {
     /** Discovery related options. */
@@ -275,14 +284,22 @@ export interface DiscoveryAndCommissioningOptions extends CommissioningOptions {
     };
 }
 
-/** Options needed to commission a new node */
+/**
+ * Options needed to commission a new node
+ *
+ * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+ */
 export type NodeCommissioningOptions = CommissioningControllerNodeOptions & {
     commissioning: Omit<DiscoveryAndCommissioningOptions, "fabric" | "discovery" | "passcode">;
     discovery: DiscoveryAndCommissioningOptions["discovery"];
     passcode: number;
 };
 
-/** Controller class to commission and connect multiple nodes into one fabric. */
+/**
+ * Controller class to commission and connect multiple nodes into one fabric.
+ *
+ * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+ */
 export class CommissioningController {
     #crypto: Crypto;
     #started = false;
@@ -308,6 +325,7 @@ export class CommissioningController {
      * Creates a new CommissioningController instance
      *
      * @param options The options for the CommissioningController
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     constructor(options: CommissioningControllerOptions) {
         if (options.environment === undefined) {
@@ -323,28 +341,39 @@ export class CommissioningController {
         this.#crypto.reportUsage();
     }
 
-    /** Returns the controller node instance. Throws an error when called before start() or after close(). */
+    /**
+     * Returns the controller node instance. Throws an error when called before start() or after close().
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     get node(): ServerNode {
         return this.#assertControllerIsStarted().node;
     }
 
     /**
      * Returns the OTA provider endpoint on the controller node, if enabled and controller node was started.
      * Else throws an error.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     get otaProvider(): Endpoint<OtaProviderEndpoint> {
         return this.#assertControllerIsStarted().node.endpoints.for("ota-provider") as Endpoint<OtaProviderEndpoint>;
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     get crypto() {
         return this.#crypto;
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     get nodeId() {
         return this.#controllerInstance?.nodeId;
     }
 
-    /** Returns the configuration data needed to create a PASE commissioner, e.g. in a mobile app. */
+    /**
+     * Returns the configuration data needed to create a PASE commissioner, e.g. in a mobile app.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     get paseCommissionerConfig() {
         const controller = this.#assertControllerIsStarted(
             "The CommissioningController needs to be started to get the PASE commissioner data.",
@@ -434,6 +463,8 @@ export class CommissioningController {
     /**
      * Commissions/Pairs a new device into the controller fabric. The method returns the NodeId of the commissioned
      * node on success.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async commissionNode(
         nodeOptions: NodeCommissioningOptions,
@@ -481,6 +512,7 @@ export class CommissioningController {
         return nodeId;
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     connectPaseChannel(nodeOptions: NodeCommissioningOptions): Promise<NodeSession> {
         const controller = this.#assertControllerIsStarted();
 
@@ -491,13 +523,18 @@ export class CommissioningController {
      * Completes the commissioning process for a node when the initial commissioning process was done by a PASE
      * commissioner. This method should be called to discover the device operational and complete the commissioning
      * process.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     completeCommissioningForNode(peerNodeId: NodeId, discoveryData?: DiscoveryData) {
         const controller = this.#assertControllerIsStarted();
         return controller.completeCommissioning(peerNodeId, discoveryData);
     }
 
-    /** Check if a given node id is commissioned on this controller. */
+    /**
+     * Check if a given node id is commissioned on this controller.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     isNodeCommissioned(nodeId: NodeId) {
         const controller = this.#assertControllerIsStarted();
         return controller.getCommissionedNodes().includes(nodeId) ?? false;
@@ -519,6 +556,8 @@ export class CommissioningController {
      * use this in case of an error as last option.
      * If this method is used the state of the PairedNode instance might be out of sync, so the PairedNode instance
      * should be disconnected first.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async removeNode(nodeId: NodeId, tryDecommissioning = true) {
         const controller = this.#assertControllerIsStarted();
@@ -577,6 +616,8 @@ export class CommissioningController {
     /**
      * Returns the PairedNode instance for a given NodeId. The instance is initialized without auto-connect if not yet
      * created.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async getNode(nodeId: NodeId, allowUnknownNode = false) {
         const existingNode = this.#pairedNodeForNodeId(nodeId);
@@ -700,7 +741,10 @@ export class CommissioningController {
         return Array.from(this.#initializedNodes.values());
     }
 
-    /** Returns true if t least one node is commissioned/paired with this controller instance. */
+    /**
+     * Returns true if at least one node is commissioned/paired with this controller instance.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     isCommissioned() {
         const controller = this.#assertControllerIsStarted();
 
@@ -710,6 +754,8 @@ export class CommissioningController {
     /**
      * Creates and Return a new InteractionClient to communicate with a node. This is mainly used internally and should
      * not be used directly. See the PairedNode class for the public API.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async createInteractionClient(
         nodeIdOrSession: NodeId | SecureSession,
@@ -747,14 +793,20 @@ export class CommissioningController {
         return this.#pairedNodeForNodeId(nodeId);
     }
 
-    /** Returns an array with the NodeIds of all commissioned nodes. */
+    /**
+     * Returns an array with the NodeIds of all commissioned nodes.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     getCommissionedNodes() {
         const controller = this.#assertControllerIsStarted();
 
         return controller.getCommissionedNodes() ?? [];
     }
 
-    /** Returns an array with all commissioned NodeIds and their metadata. */
+    /**
+     * Returns an array with all commissioned NodeIds and their metadata.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     getCommissionedNodesDetails(): PairedNodeDetails[] {
         const controller = this.#assertControllerIsStarted();
 
@@ -764,6 +816,8 @@ export class CommissioningController {
     /**
      * Disconnects all connected nodes and closes the network connections and other resources of the controller.
      * You can use "start()" to restart the controller after closing it.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async close() {
         this.#observers.close();
@@ -779,7 +833,10 @@ export class CommissioningController {
         this.#started = false;
     }
 
-    /** Return the port used by the controller for the UDP interface. */
+    /**
+     * Return the port used by the controller for the UDP interface.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     getPort(): number | undefined {
         return this.#options.localPort;
     }
@@ -797,12 +854,15 @@ export class CommissioningController {
         this.#ipv4Disabled = ipv4Disabled;
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     get env() {
         return this.#environment;
     }
 
     /**
      * Initialize the controller and initialize and connect to all commissioned nodes if autoConnect is not set to false.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async start() {
         if (this.#ipv4Disabled === undefined) {
@@ -850,6 +910,8 @@ export class CommissioningController {
 
     /**
      * Cancels the discovery process for commissionable devices started with discoverCommissionableDevices().
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     cancelCommissionableDeviceDiscovery(
         identifierData: CommissionableDeviceIdentifiers,
@@ -862,6 +924,8 @@ export class CommissioningController {
      * Starts to discover commissionable devices.
      * The promise will be fulfilled after the provided timeout or when the discovery is stopped via
      * cancelCommissionableDeviceDiscovery(). The discoveredCallback will be called for each discovered device.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async discoverCommissionableDevices(
         identifierData: CommissionableDeviceIdentifiers,
@@ -882,6 +946,8 @@ export class CommissioningController {
     /**
      * Use this method to reset the Controller storage. The method can only be called if the controller is stopped and
      * will remove all commissioning data and paired nodes from the controller.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async resetStorage() {
         if (this.#started) {
@@ -892,7 +958,10 @@ export class CommissioningController {
         await this.node.erase(); // TODO check if that's correct
     }
 
-    /** Returns active session information for all connected nodes. */
+    /**
+     * Returns active session information for all connected nodes.
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
+     */
     getActiveSessionInformation(): ActiveSessionInformation[] {
         return this.#controllerInstance?.getActiveSessionInformation() ?? [];
     }
@@ -942,6 +1011,8 @@ export class CommissioningController {
     /**
      * Updates the fabric label for the controller and all connected nodes.
      * The label is used to identify the controller and all connected nodes in the fabric.
+     *
+     * @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md.
      */
     async updateFabricLabel(label: string) {
         const controller = this.#assertControllerIsStarted();
@@ -992,11 +1063,13 @@ export class CommissioningController {
         }
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     get groups(): FabricGroups {
         const controllerInstance = this.#assertControllerIsStarted();
         return controllerInstance.fabric.groups;
     }
 
+    /** @deprecated Legacy API, removed in 0.19. Migrate to @matter/node — see docs/MIGRATION_CONTROLLER_018.md. */
     get fabric(): Fabric {
         const controllerInstance = this.#assertControllerIsStarted();
         return controllerInstance.fabric;