@matter/node 0.17.9 → 0.18.0-alpha.0-20260807-335c3291b

package/src/behaviors/power-source/PowerSourceServer.ts

@@ -62,6 +62,5 @@ export class PowerSourceBaseServer extends PowerSourceLevelBase {
     }
 }
 
-// We had turned on some more features to provide the default implementation, but export the cluster with default
-// Features again.
-export class PowerSourceServer extends PowerSourceBaseServer.for(PowerSource) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class PowerSourceServer extends PowerSourceBaseServer.with() {}

package/src/behaviors/power-topology/PowerTopologyServer.ts

@@ -48,4 +48,5 @@ export class PowerTopologyBaseServer extends PowerTopologyBase {
     }
 }
 
-export class PowerTopologyServer extends PowerTopologyBaseServer.for(PowerTopology) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class PowerTopologyServer extends PowerTopologyBaseServer.with() {}

package/src/behaviors/service-area/ServiceAreaServer.ts

@@ -294,6 +294,5 @@ export namespace ServiceAreaBaseServer {
     };
 }
 
-// We had turned on some more features to provide the default implementation, but export the cluster with no
-// Features again.
+// Drop the features the base implementation enables internally so consumers select their own
 export class ServiceAreaServer extends ServiceAreaBaseServer.with() {}

package/src/behaviors/smoke-co-alarm/SmokeCoAlarmServer.ts

@@ -41,4 +41,5 @@ export class SmokeCoAlarmBaseServer extends SmokeCoAlarmBase {
     }
 }
 
-export class SmokeCoAlarmServer extends SmokeCoAlarmBaseServer.for(SmokeCoAlarm) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class SmokeCoAlarmServer extends SmokeCoAlarmBaseServer.with() {}

package/src/behaviors/switch/SwitchServer.ts

@@ -358,5 +358,5 @@ export namespace SwitchBaseServer {
     }
 }
 
-// Reset all Features
-export class SwitchServer extends SwitchBaseServer.for(Switch) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class SwitchServer extends SwitchBaseServer.with() {}

package/src/behaviors/thermostat/AtomicWriteHandler.ts

@@ -142,7 +142,7 @@ export class AtomicWriteHandler {
                 initialValues,
             );
             this.#pendingWrites.add(state);
-            state.closed.on(() => void this.#pendingWrites.delete(state));
+            state.closed.once(() => void this.#pendingWrites.delete(state));
             state.start();
             logger.debug("Added atomic write state:", state);
             return state;

package/src/behaviors/thermostat/AtomicWriteState.ts

@@ -30,8 +30,10 @@ export class AtomicWriteState {
     readonly pendingAttributeValues: Val.Struct = {};
     readonly timeout: number;
     readonly initialValues: Val.Struct;
+    /** Emitted exactly once when the state is closed. */
     readonly closed = Observable<[void]>();
     #timer: Timer;
+    #isClosed = false;
 
     constructor(
         peerAddress: PeerAddress,
@@ -80,6 +82,10 @@ export class AtomicWriteState {
     }
 
     close() {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
         logger.debug(
             `Closing atomic write state for peer ${this.peerAddress.toString()} on endpoint ${this.endpoint.id}`,
         );

package/src/behaviors/thermostat/ThermostatServer.ts

@@ -1671,6 +1671,5 @@ export namespace ThermostatBaseServer {
     }
 }
 
-// We had turned on some more features to provide a default implementation, but export the cluster with default
-// Features again.
-export class ThermostatServer extends ThermostatBaseServer.for(Thermostat) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class ThermostatServer extends ThermostatBaseServer.with() {}

package/src/behaviors/window-covering/WindowCoveringServer.ts

@@ -648,4 +648,5 @@ export namespace WindowCoveringBaseServer {
     };
 }
 
-export class WindowCoveringServer extends WindowCoveringBaseServer.for(WindowCovering) {}
+// Drop the features the base implementation enables internally so consumers select their own
+export class WindowCoveringServer extends WindowCoveringBaseServer.with() {}

package/src/endpoint/properties/Behaviors.ts

@@ -5,7 +5,7 @@
  */
 
 import { Behavior } from "#behavior/Behavior.js";
-import type { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
 import { ActionContext } from "#behavior/context/ActionContext.js";
 import { NodeActivity } from "#behavior/context/NodeActivity.js";
 import { LocalActorContext } from "#behavior/context/server/LocalActorContext.js";
@@ -31,7 +31,7 @@ import {
 } from "@matter/general";
 import { ClusterModel } from "@matter/model";
 import { ClusterTypeProtocol, Val } from "@matter/protocol";
-import type { ClusterType } from "@matter/types";
+import type { ClusterId, ClusterType } from "@matter/types";
 import type { Agent } from "../Agent.js";
 import type { Endpoint } from "../Endpoint.js";
 import { BehaviorInitializationError, EndpointBehaviorsError } from "../errors.js";
@@ -84,6 +84,18 @@ export class Behaviors {
         return supported as T;
     }
 
+    /**
+     * Obtain the {@link ClusterBehavior.Type} the endpoint uses to implement a given cluster, if supported.
+     */
+    forCluster(clusterId: ClusterId): ClusterBehavior.Type | undefined {
+        for (const type of Object.values(this.#supported)) {
+            if (ClusterBehavior.is(type) && type.cluster.id === clusterId) {
+                return type;
+            }
+        }
+        return undefined;
+    }
+
     /**
      * The list of active behaviors.
      */

package/src/endpoint/properties/Endpoints.ts

@@ -42,7 +42,7 @@ export class Endpoints implements ImmutableSet<Endpoint> {
     }
 
     get size(): number {
-        return this.#list.length + 1;
+        return this.#list.length;
     }
 
     map<R>(mapper: (item: Endpoint<EndpointType.Empty>) => R): R[] {

package/src/node/ClientNode.ts

@@ -22,6 +22,7 @@ import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
 import {
     DependencyLifecycleError,
     Diagnostic,
+    Duration,
     Identity,
     ImplementationError,
     InternalError,
@@ -33,6 +34,7 @@ import { Matter, MatterModel } from "@matter/model";
 import { Interactable, OccurrenceManager, PeerAddress, PeerSet } from "@matter/protocol";
 import { ClientEndpointInitializer } from "./client/ClientEndpointInitializer.js";
 import { ClientNodeInteraction } from "./client/ClientNodeInteraction.js";
+import { ClientNodeLifecycle } from "./ClientNodeLifecycle.js";
 import { Node } from "./Node.js";
 import type { ServerNode } from "./ServerNode.js";
 
@@ -81,6 +83,10 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         return this.#matter ?? this.env.maybeGet(MatterModel) ?? Matter;
     }
 
+    override get lifecycle(): ClientNodeLifecycle {
+        return super.lifecycle as ClientNodeLifecycle;
+    }
+
     override get endpoints(): ClientNodeEndpoints {
         return new ClientNodeEndpoints(this);
     }
@@ -153,6 +159,25 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         await this.delete();
     }
 
+    /**
+     * Open a Basic Commissioning Window on this peer (uses the passcode originally printed on the device).
+     *
+     * This is an optional feature and not all devices support it; use {@link openEnhancedCommissioningWindow} unless
+     * you specifically need the basic commissioning method.
+     */
+    async openBasicCommissioningWindow(commissioningTimeout?: Duration) {
+        await this.act(agent => agent.commissioning.openBasicCommissioningWindow(commissioningTimeout));
+    }
+
+    /**
+     * Open an Enhanced Commissioning Window on this peer using a freshly generated random passcode.
+     *
+     * @returns the manual and QR pairing codes encoding the generated passcode.
+     */
+    async openEnhancedCommissioningWindow(commissioningTimeout?: Duration) {
+        return await this.act(agent => agent.commissioning.openEnhancedCommissioningWindow(commissioningTimeout));
+    }
+
     /**
      * Force-remove the node without first decommissioning.
      *
@@ -185,7 +210,12 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
             return;
         }
 
+        // A disabled node should be offline; setting this before teardown also lets the connection-state engine settle
+        // straight to Disconnected instead of flashing Reconnecting as the subscription drops.
+        this.lifecycle.targetState = "offline";
         await this.lifecycle.mutex.produce(async () => {
+            // Drop the subscription before flipping isDisabled so the connection-state engine cannot momentarily read
+            // Connected while disabling (subscriptionActive is checked ahead of isDisabled).
             await this.cancelWithMutex();
             await this.setStateOf(NetworkClient, { isDisabled: true });
         });
@@ -217,6 +247,10 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         await super.resetWithMutex();
     }
 
+    protected override createLifecycle(): ClientNodeLifecycle {
+        return new ClientNodeLifecycle(this);
+    }
+
     protected createRuntime(): NetworkRuntime {
         return new ClientNetworkRuntime(this);
     }

package/src/node/ClientNodeLifecycle.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ActionContext } from "#behavior/context/ActionContext.js";
+import { Observable } from "@matter/general";
+import { NodeLifecycle } from "./NodeLifecycle.js";
+
+/**
+ * Connection state of a client (peer) node.
+ *
+ * Values match the legacy `NodeStates` enum so consumers migrate by type swap.
+ */
+export enum NodeConnectionState {
+    /**
+     * The node is connected: the last communications succeeded and subscription updates are flowing, so data is
+     * up-to-date.
+     */
+    Connected = 0,
+
+    /**
+     * The node is disconnected because it is disabled, stopped or not yet started.  No connection is attempted and
+     * data is stale.
+     */
+    Disconnected = 1,
+
+    /**
+     * A former connection was lost and we are actively re-establishing it on known addresses.  Data is stale and it is
+     * not yet known whether reconnection will succeed.
+     */
+    Reconnecting = 2,
+
+    /**
+     * The node appears offline: communication failed and there is no known-reachable address, so we are waiting for the
+     * node to re-announce itself via mDNS before attempting to connect again.
+     */
+    WaitingForDeviceDiscovery = 3,
+}
+
+/**
+ * Lifecycle information specific to client (peer) nodes.
+ */
+export class ClientNodeLifecycle extends NodeLifecycle {
+    #seeded = Observable<[context: ActionContext]>();
+    #connectionStateChanged = Observable<[state: NodeConnectionState]>();
+    #isSeeded = false;
+    #connectionState = NodeConnectionState.Disconnected;
+
+    /**
+     * True once the node's structure has been read at least once (BasicInformation present and more than just the
+     * root endpoint present).
+     */
+    get isSeeded() {
+        return this.#isSeeded;
+    }
+
+    /**
+     * Emits the first time the node becomes {@link isSeeded}.
+     */
+    get seeded() {
+        return this.#seeded;
+    }
+
+    /**
+     * Transitions the node to seeded. No-op if already seeded, so {@link seeded} emits at most once.
+     */
+    markSeeded(context: ActionContext) {
+        if (this.#isSeeded) {
+            return;
+        }
+        this.#isSeeded = true;
+        this.#seeded.emit(context);
+    }
+
+    /**
+     * The current {@link NodeConnectionState}.
+     */
+    get connectionState() {
+        return this.#connectionState;
+    }
+
+    /**
+     * Emits on each {@link connectionState} transition (not on no-op re-computes).
+     */
+    get connectionStateChanged() {
+        return this.#connectionStateChanged;
+    }
+
+    /**
+     * True when {@link connectionState} is {@link NodeConnectionState.Connected}.
+     */
+    get isConnected() {
+        return this.#connectionState === NodeConnectionState.Connected;
+    }
+
+    /**
+     * Set the {@link connectionState}, emitting {@link connectionStateChanged} only on a real transition.
+     */
+    setConnectionState(state: NodeConnectionState) {
+        if (this.#connectionState === state) {
+            return;
+        }
+        this.#connectionState = state;
+        this.#connectionStateChanged.emit(state);
+    }
+}

package/src/node/client/ClientNodeInteraction.ts

@@ -392,8 +392,8 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
      * Temporary accessor of cached data, if any are stored. This will be implemented by the ClientNodeInteraction and
      * point to the node state of the relevant endpoint and is needed to support the old API behavior for
      * AttributeClient.
-     * TODO Remove when we remove the legacy controller API
-     * @deprecated
+     *
+     * @deprecated Scheduled for removal in 0.19 with the legacy controller API.
      */
     localStateFor(endpointId: EndpointNumber): Record<string, Record<string, Val.Struct> | undefined> | undefined {
         if (!this.#node.endpoints.has(endpointId)) {