@camstack/addon-matter-broker 0.2.149 → 0.2.150

package/dist/addon.mjs

@@ -6602,7 +6602,7 @@ var SecretOverwriteRefusedError = class extends Error {
 		this.name = "SecretOverwriteRefusedError";
 	}
 };
-function isRecord$4(value) {
+function isRecord$4$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolvedValue(pass, marker) {
@@ -6631,7 +6631,7 @@ function inArray(pass, incoming, stored) {
 	return incoming.map((item, index) => {
 		const twin = stored[index];
 		if (isSecretMarker(twin)) return typeof item === "string" && item === resolvedValue(pass, twin) ? twin : item;
-		if (isRecord$4(item) && isRecord$4(twin)) return inArrayRow(pass, item, twin);
+		if (isRecord$4$1(item) && isRecord$4$1(twin)) return inArrayRow(pass, item, twin);
 		if (Array.isArray(item) && Array.isArray(twin)) return inArray(pass, item, twin);
 		return item;
 	});
@@ -6642,7 +6642,7 @@ function inArrayRow(pass, incoming, stored) {
 		const twin = stored[key];
 		if (isSecretMarker(twin)) {
 			if (typeof value === "string" && value === resolvedValue(pass, twin)) out[key] = twin;
-		} else if (isRecord$4(value) && isRecord$4(twin)) out[key] = inArrayRow(pass, value, twin);
+		} else if (isRecord$4$1(value) && isRecord$4$1(twin)) out[key] = inArrayRow(pass, value, twin);
 		else if (Array.isArray(value) && Array.isArray(twin)) out[key] = inArray(pass, value, twin);
 	}
 	return out;
@@ -6650,7 +6650,7 @@ function inArrayRow(pass, incoming, stored) {
 async function walk(pass, incoming, stored) {
 	if (isSecretMarker(stored)) return atMarker(pass, incoming, stored);
 	if (Array.isArray(incoming) && Array.isArray(stored)) return inArray(pass, incoming, stored);
-	if (!isRecord$4(incoming) || !isRecord$4(stored)) return incoming;
+	if (!isRecord$4$1(incoming) || !isRecord$4$1(stored)) return incoming;
 	const out = { ...incoming };
 	for (const [key, value] of Object.entries(incoming)) out[key] = await walk(pass, value, stored[key]);
 	return out;
@@ -6681,7 +6681,7 @@ async function restoreUnchangedSecrets(input) {
 function isJsonEqual(a, b) {
 	if (Object.is(a, b)) return true;
 	if (Array.isArray(a)) return Array.isArray(b) && a.length === b.length && a.every((v, i) => isJsonEqual(v, b[i]));
-	if (isRecord$4(a) && isRecord$4(b)) {
+	if (isRecord$4$1(a) && isRecord$4$1(b)) {
 		const keys = Object.keys(a);
 		if (keys.length !== Object.keys(b).length) return false;
 		return keys.every((k) => Object.prototype.hasOwnProperty.call(b, k) && isJsonEqual(a[k], b[k]));
@@ -6705,7 +6705,7 @@ function markerKeysOf(blob, owner) {
 }
 function nodeFromStored(value, owner) {
 	if (isSecretMarker(value)) return isSecretRefOwnedBy(value.$secret, owner) ? { kind: "leaf" } : null;
-	if (!isRecord$4(value)) return null;
+	if (!isRecord$4$1(value)) return null;
 	const children = /* @__PURE__ */ new Map();
 	for (const [key, child] of Object.entries(value)) {
 		const node = nodeFromStored(child, owner);
@@ -11256,7 +11256,7 @@ var ExpressionEvalError = class extends Error {
 		this.name = "ExpressionEvalError";
 	}
 };
-function asFiniteNumber(value, name, index) {
+function asFiniteNumber$1(value, name, index) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
 	return value;
 }
@@ -11269,7 +11269,7 @@ function finiteResult(value, name) {
 	return value;
 }
 function allFiniteNumbers(args, name) {
-	return args.map((a, idx) => asFiniteNumber(a, name, idx));
+	return args.map((a, idx) => asFiniteNumber$1(a, name, idx));
 }
 function asBoolean$2(value, name, index) {
 	if (typeof value !== "boolean") throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a boolean`);
@@ -11306,29 +11306,29 @@ var table = {
 	abs: {
 		minArgs: 1,
 		maxArgs: 1,
-		apply: (args) => finiteResult(Math.abs(asFiniteNumber(args[0], "abs", 0)), "abs")
+		apply: (args) => finiteResult(Math.abs(asFiniteNumber$1(args[0], "abs", 0)), "abs")
 	},
 	floor: {
 		minArgs: 1,
 		maxArgs: 1,
-		apply: (args) => finiteResult(Math.floor(asFiniteNumber(args[0], "floor", 0)), "floor")
+		apply: (args) => finiteResult(Math.floor(asFiniteNumber$1(args[0], "floor", 0)), "floor")
 	},
 	ceil: {
 		minArgs: 1,
 		maxArgs: 1,
-		apply: (args) => finiteResult(Math.ceil(asFiniteNumber(args[0], "ceil", 0)), "ceil")
+		apply: (args) => finiteResult(Math.ceil(asFiniteNumber$1(args[0], "ceil", 0)), "ceil")
 	},
 	sqrt: {
 		minArgs: 1,
 		maxArgs: 1,
-		apply: (args) => finiteResult(Math.sqrt(asFiniteNumber(args[0], "sqrt", 0)), "sqrt")
+		apply: (args) => finiteResult(Math.sqrt(asFiniteNumber$1(args[0], "sqrt", 0)), "sqrt")
 	},
 	round: {
 		minArgs: 1,
 		maxArgs: 2,
 		apply: (args) => {
-			const x = asFiniteNumber(args[0], "round", 0);
-			const digits = args.length > 1 ? Math.trunc(asFiniteNumber(args[1], "round", 1)) : 0;
+			const x = asFiniteNumber$1(args[0], "round", 0);
+			const digits = args.length > 1 ? Math.trunc(asFiniteNumber$1(args[1], "round", 1)) : 0;
 			if (digits < 0 || digits > 100) throw new ExpressionEvalError("round: digits must be between 0 and 100");
 			const factor = 10 ** digits;
 			return finiteResult(Math.round(x * factor) / factor, "round");
@@ -11337,15 +11337,15 @@ var table = {
 	pow: {
 		minArgs: 2,
 		maxArgs: 2,
-		apply: (args) => finiteResult(asFiniteNumber(args[0], "pow", 0) ** asFiniteNumber(args[1], "pow", 1), "pow")
+		apply: (args) => finiteResult(asFiniteNumber$1(args[0], "pow", 0) ** asFiniteNumber$1(args[1], "pow", 1), "pow")
 	},
 	clamp: {
 		minArgs: 3,
 		maxArgs: 3,
 		apply: (args) => {
-			const x = asFiniteNumber(args[0], "clamp", 0);
-			const lo = asFiniteNumber(args[1], "clamp", 1);
-			const hi = asFiniteNumber(args[2], "clamp", 2);
+			const x = asFiniteNumber$1(args[0], "clamp", 0);
+			const lo = asFiniteNumber$1(args[1], "clamp", 1);
+			const hi = asFiniteNumber$1(args[2], "clamp", 2);
 			if (lo > hi) throw new ExpressionEvalError("clamp: lower bound is greater than upper bound");
 			return finiteResult(Math.min(hi, Math.max(lo, x)), "clamp");
 		}
@@ -11374,13 +11374,13 @@ var table = {
 	age: {
 		minArgs: 2,
 		maxArgs: 2,
-		apply: (args) => finiteResult(asFiniteNumber(args[0], "age", 0) - asFiniteNumber(args[1], "age", 1), "age")
+		apply: (args) => finiteResult(asFiniteNumber$1(args[0], "age", 0) - asFiniteNumber$1(args[1], "age", 1), "age")
 	},
 	convert: {
 		minArgs: 3,
 		maxArgs: 3,
 		apply: (args, hooks) => {
-			const x = asFiniteNumber(args[0], "convert", 0);
+			const x = asFiniteNumber$1(args[0], "convert", 0);
 			const from = asString(args[1], "convert", 1).trim();
 			const to = asString(args[2], "convert", 2).trim();
 			if (hooks.convert) {
@@ -11406,11 +11406,11 @@ var table = {
 		minArgs: 2,
 		maxArgs: 2,
 		apply: (args, hooks) => {
-			const windowMs = asFiniteNumber(args[1], "within", 1);
+			const windowMs = asFiniteNumber$1(args[1], "within", 1);
 			if (windowMs < 0) throw new ExpressionEvalError("within: the window must not be negative");
 			const at = args[0];
 			if (at === null) return false;
-			const ts = asFiniteNumber(at, "within", 0);
+			const ts = asFiniteNumber$1(at, "within", 0);
 			const now = hooks.now;
 			if (now === void 0 || !Number.isFinite(now)) throw new ExpressionEvalError("within: no clock was supplied to this evaluation");
 			const inside = now - ts <= windowMs;
@@ -11427,7 +11427,7 @@ var table = {
 		minArgs: 1,
 		maxArgs: INF,
 		apply: (args) => {
-			const present = args.flatMap((a, i) => a === null ? [] : [asFiniteNumber(a, "latest", i)]);
+			const present = args.flatMap((a, i) => a === null ? [] : [asFiniteNumber$1(a, "latest", i)]);
 			return present.length === 0 ? null : finiteResult(Math.max(...present), "latest");
 		}
 	},
@@ -197514,6 +197514,7 @@ var StubMatterController = class {
 	async removeNode(_nodeId) {
 		throw new MatterControllerNotWiredError("removeNode");
 	}
+	async syncSubscriptions() {}
 };
 /**
 * Factory seam (stub default): build a {@link StubMatterController}.
@@ -197686,7 +197687,13 @@ var MatterAttributeId = {
 	/** ElectricalPowerMeasurement.ActivePower (int64, mW). */
 	ActivePower: 8,
 	/** ElectricalEnergyMeasurement.CumulativeEnergyImported (energy struct, mWh). */
-	CumulativeEnergyImported: 1
+	CumulativeEnergyImported: 1,
+	/** DoorLock.LockState (enum: 0 NotFullyLocked, 1 Locked, 2 Unlocked, 3 Unlatched). */
+	LockState: 0,
+	/** DoorLock.DoorState (enum; 2 = DoorJammed). Present only with the door sensor. */
+	DoorState: 3,
+	/** DoorLock.RequirePinForRemoteOperation (bool). */
+	RequirePinForRemoteOperation: 51
 };
 /** Thermostat.SystemMode enum → CamStack HvacMode (climate-control). */
 var SYSTEM_MODE_TO_HVAC = new Map([
@@ -197718,8 +197725,11 @@ function asBoolean(value) {
 * matter.js may surface a `MeasuredValue` either as a plain scaled int or wrapped
 * in an energy-measurement struct (`{ energy }`). Pull the numeric payload out.
 */
+function isRecord$4(value) {
+	return typeof value === "object" && value !== null;
+}
 function asEnergyMilliWattHours(value) {
-	if (typeof value === "object" && value !== null && "energy" in value) return asNumber(value.energy);
+	if (isRecord$4(value) && "energy" in value) return asNumber(value["energy"]);
 	return asNumber(value);
 }
 /**
@@ -197741,9 +197751,77 @@ function decodeMatterAttribute(input) {
 		case MatterClusterId.Thermostat: return decodeThermostat(attributeId, value);
 		case MatterClusterId.ElectricalPowerMeasurement: return decodeElectricalPower(attributeId, value);
 		case MatterClusterId.ElectricalEnergyMeasurement: return decodeElectricalEnergy(attributeId, value);
+		case MatterClusterId.DoorLock: return decodeDoorLock(attributeId, value);
 		default: return null;
 	}
 }
+/** LockState enum → cap state. NotFullyLocked has no cap value of its own. */
+var LOCK_STATE_TO_CAP = new Map([
+	[0, {
+		state: "jammed",
+		detail: "not-fully-locked"
+	}],
+	[1, { state: "locked" }],
+	[2, { state: "unlocked" }],
+	[3, {
+		state: "unlocked",
+		detail: "unlatched"
+	}]
+]);
+/** DoorState enum → a detail. Only DoorJammed also moves the lock cap. */
+var DOOR_STATE_DETAIL = new Map([
+	[0, "door-open"],
+	[1, "door-closed"],
+	[2, "door-jammed"],
+	[3, "door-forced-open"],
+	[4, "door-unspecified"],
+	[5, "door-ajar"]
+]);
+function decodeDoorLock(attributeId, value) {
+	if (attributeId === MatterAttributeId.LockState) {
+		const raw = asNumber(value);
+		if (raw === null) return null;
+		const mapped = LOCK_STATE_TO_CAP.get(raw);
+		if (mapped === void 0) return null;
+		return {
+			cap: "lock-control",
+			patch: {
+				state: mapped.state,
+				lastChangedAt: Date.now()
+			},
+			...mapped.detail !== void 0 ? { detail: mapped.detail } : {}
+		};
+	}
+	if (attributeId === MatterAttributeId.DoorState) {
+		const raw = asNumber(value);
+		if (raw === null) return null;
+		const detail = DOOR_STATE_DETAIL.get(raw);
+		if (detail === void 0) return null;
+		if (detail === "door-jammed") return {
+			cap: "lock-control",
+			patch: {
+				state: "jammed",
+				lastChangedAt: Date.now()
+			},
+			detail
+		};
+		return {
+			cap: "lock-control",
+			patch: {},
+			detail
+		};
+	}
+	if (attributeId === MatterAttributeId.RequirePinForRemoteOperation) {
+		const required = asBoolean(value);
+		if (required === null) return null;
+		return {
+			cap: "lock-control",
+			patch: {},
+			detail: required ? "pin-required" : "pin-not-required"
+		};
+	}
+	return null;
+}
 function decodeOnOff(attributeId, value) {
 	if (attributeId !== MatterAttributeId.OnOff) return null;
 	const on = asBoolean(value);
@@ -197967,7 +198045,10 @@ var ATTR_NAME_TO_ID = new Map([
 	["voltage", MatterAttributeId.Voltage],
 	["activeCurrent", MatterAttributeId.ActiveCurrent],
 	["activePower", MatterAttributeId.ActivePower],
-	["cumulativeEnergyImported", MatterAttributeId.CumulativeEnergyImported]
+	["cumulativeEnergyImported", MatterAttributeId.CumulativeEnergyImported],
+	["lockState", MatterAttributeId.LockState],
+	["doorState", MatterAttributeId.DoorState],
+	["requirePinForRemoteOperation", MatterAttributeId.RequirePinForRemoteOperation]
 ]);
 /** clusterId → matter.js behavior id (camelCase) for outbound command clusters. */
 var CLUSTER_ID_TO_BEHAVIOR_ID = new Map([
@@ -197979,14 +198060,14 @@ var CLUSTER_ID_TO_BEHAVIOR_ID = new Map([
 	[258, "windowCovering"]
 ]);
 /** True when `value` is a non-null object (cast-free record narrowing). */
-function isRecord$1(value) {
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null;
 }
 /** Read a finite numeric cluster id from a `Behavior.Type`'s `.cluster.id`. */
 function clusterIdOf(behaviorType) {
-	if (!isRecord$1(behaviorType)) return null;
+	if (!isRecord$3(behaviorType)) return null;
 	const cluster = behaviorType["cluster"];
-	if (!isRecord$1(cluster)) return null;
+	if (!isRecord$3(cluster)) return null;
 	const id = cluster["id"];
 	if (typeof id === "number" && Number.isFinite(id)) return id;
 	if (typeof id === "bigint") return Number(id);
@@ -197997,13 +198078,13 @@ function clusterIdOf(behaviorType) {
 * the matter.js `Endpoint` interop at one typed boundary.
 */
 function asDynamicEndpoint(value) {
-	if (!isRecord$1(value)) return null;
+	if (!isRecord$3(value)) return null;
 	const number = value["number"];
 	const behaviors = value["behaviors"];
 	const parts = value["parts"];
 	const stateOf = value["stateOf"];
 	const commandsOf = value["commandsOf"];
-	if (typeof number === "number" && isRecord$1(behaviors) && "supported" in behaviors && typeof stateOf === "function" && typeof commandsOf === "function" && isIterable$1(parts)) return {
+	if (typeof number === "number" && isRecord$3(behaviors) && "supported" in behaviors && typeof stateOf === "function" && typeof commandsOf === "function" && isIterable$2(parts)) return {
 		number,
 		behaviors: { supported: behaviors["supported"] },
 		parts: mapIterable(parts, asDynamicEndpointOrThrow),
@@ -198027,7 +198108,7 @@ async function invokeNodeCommand(input) {
 	const behaviorId = CLUSTER_ID_TO_BEHAVIOR_ID.get(clusterId);
 	if (behaviorId === void 0) throw new Error(`matter-broker: cluster 0x${clusterId.toString(16)} has no command binding`);
 	const commands = target.commandsOf(behaviorId);
-	if (!isRecord$1(commands)) throw new Error(`matter-broker: endpoint ${endpointId} has no '${behaviorId}' commands`);
+	if (!isRecord$3(commands)) throw new Error(`matter-broker: endpoint ${endpointId} has no '${behaviorId}' commands`);
 	const command = commands[commandName];
 	const fn = asCommandFn(command);
 	if (fn === null) throw new Error(`matter-broker: command '${commandName}' unavailable on '${behaviorId}'`);
@@ -198052,8 +198133,8 @@ function asDynamicEndpointOrThrow(value) {
 	if (ep === null) throw new TypeError("matter-broker: unexpected non-endpoint child part");
 	return ep;
 }
-function isIterable$1(value) {
-	return isRecord$1(value) && typeof Reflect.get(value, Symbol.iterator) === "function";
+function isIterable$2(value) {
+	return isRecord$3(value) && typeof Reflect.get(value, Symbol.iterator) === "function";
 }
 function* mapIterable(it, fn) {
 	for (const v of it) yield fn(v);
@@ -198074,7 +198155,7 @@ function collectEndpoint(endpoint, out) {
 	const supported = endpoint.behaviors.supported;
 	const clusterIds = [];
 	const attributes = [];
-	if (isRecord$1(supported)) for (const [behaviorId, behaviorType] of Object.entries(supported)) {
+	if (isRecord$3(supported)) for (const [behaviorId, behaviorType] of Object.entries(supported)) {
 		const clusterId = clusterIdOf(behaviorType);
 		if (clusterId === null) continue;
 		clusterIds.push(clusterId);
@@ -198094,7 +198175,7 @@ function readBehaviorAttributes(endpoint, behaviorId, clusterId, attributes) {
 	} catch {
 		return;
 	}
-	if (!isRecord$1(struct)) return;
+	if (!isRecord$3(struct)) return;
 	for (const [attrName, value] of Object.entries(struct)) {
 		const attributeId = ATTR_NAME_TO_ID.get(attrName);
 		if (attributeId === void 0) continue;
@@ -198106,35 +198187,413 @@ function readBehaviorAttributes(endpoint, behaviorId, clusterId, attributes) {
 	}
 }
 //#endregion
+//#region src/matter-commission-progress.ts
+/**
+* Commissioning progress the admin UI polls, plus the named failures a share
+* code can produce. Pure — no matter.js import.
+*
+* Phases follow the on-network share path: discover the device, establish
+* PASE, then commission onto this fabric. A missing or malformed code never
+* becomes a later phase.
+*/
+var CommissionPhase = {
+	Idle: "idle",
+	Discovering: "discovering",
+	Pase: "pase",
+	Commissioning: "commissioning",
+	Done: "done",
+	Failed: "failed"
+};
+var CommissionFailureCode = {
+	CodeExpired: "code-expired",
+	DeviceNotFound: "device-not-found",
+	WrongCode: "wrong-code",
+	InvalidCode: "invalid-code",
+	Unknown: "unknown"
+};
+var IDLE_COMMISSION_PROGRESS = {
+	phase: CommissionPhase.Idle,
+	failure: null,
+	message: null
+};
+/** Stable prefix the UI matches. The human text follows the colon. */
+function commissionFailureMessage(code, detail) {
+	return `matter-commission:${code}: ${detail}`;
+}
+/**
+* Map a controller or matter.js error onto a named failure. Order matters:
+* an expired commissioning window is not "device not found", and a rejected
+* passcode is not a network miss.
+*/
+function classifyCommissionError(message) {
+	const text = message.toLowerCase();
+	if (text.includes("invalid pairing code") || text.includes("11 or 21")) return CommissionFailureCode.InvalidCode;
+	if (text.includes("expired") || text.includes("commissioning window") || text.includes("window closed")) return CommissionFailureCode.CodeExpired;
+	if (text.includes("passcode") || text.includes("wrong code") || text.includes("pase") || text.includes("authentication failed") || text.includes("status 0x7e") || text.includes("invalid code")) return CommissionFailureCode.WrongCode;
+	if (text.includes("not found") || text.includes("no device") || text.includes("no commissionable") || text.includes("discovery") || text.includes("timed out") || text.includes("timeout") || text.includes("unreachable")) return CommissionFailureCode.DeviceNotFound;
+	return CommissionFailureCode.Unknown;
+}
+//#endregion
+//#region src/matter-subscription.ts
+/**
+* Per-node Matter attribute subscriptions. The matter.js call itself lives in
+* {@link import('./matter-peer-subscribe.js')}; this module owns the lifecycle:
+* open, resubscribe after the session drops or the node returns, and a bounded
+* backoff. A report whose value is missing is not a value (D393) and is dropped.
+*/
+/** First wait after a dropped subscription. */
+var SUBSCRIPTION_BACKOFF_INITIAL_MS = 1e3;
+/** Cap so a sleepy Thread node cannot be hammered. */
+var SUBSCRIPTION_BACKOFF_MAX_MS = 6e4;
+/**
+* One supervisor per fabric. `sync` is safe to call on start, after commission,
+* and on the reconcile timer (the backstop when a lifecycle event was missed).
+*/
+var MatterSubscriptionSupervisor = class {
+	#brokerId;
+	#logger;
+	#resolveDeviceId;
+	#onReport;
+	#slots = /* @__PURE__ */ new Map();
+	#stopped = false;
+	constructor(options) {
+		this.#brokerId = options.brokerId;
+		this.#logger = options.logger;
+		this.#resolveDeviceId = options.resolveDeviceId;
+		this.#onReport = options.onReport;
+	}
+	/** How many times `subscribe` has been entered for a node (tests). */
+	subscribeAttempts(nodeId) {
+		return this.#slots.get(nodeId)?.generation ?? 0;
+	}
+	phase(nodeId) {
+		return this.#slots.get(nodeId)?.phase ?? null;
+	}
+	async sync(peers) {
+		if (this.#stopped) return;
+		const live = /* @__PURE__ */ new Set();
+		for (const peer of peers) {
+			live.add(peer.nodeId);
+			const slot = this.#slots.get(peer.nodeId);
+			if (slot === void 0) {
+				await this.#open(peer);
+				continue;
+			}
+			slot.peer = peer;
+			if (slot.phase !== "subscribed" && peer.online() && slot.phase !== "resubscribing") {
+				slot.attempt = 0;
+				await this.#open(peer);
+			}
+		}
+		for (const [nodeId, slot] of this.#slots) {
+			if (live.has(nodeId)) continue;
+			await this.#drop(slot);
+			this.#slots.delete(nodeId);
+		}
+	}
+	async stop() {
+		this.#stopped = true;
+		for (const slot of this.#slots.values()) await this.#drop(slot);
+		this.#slots.clear();
+	}
+	async #open(peer) {
+		if (this.#stopped) return;
+		const existing = this.#slots.get(peer.nodeId);
+		if (existing?.phase === "subscribed" && existing.subscription !== null) return;
+		if (existing?.timer !== null && existing?.timer !== void 0) {
+			clearTimeout(existing.timer);
+			existing.timer = null;
+		}
+		const generation = (existing?.generation ?? 0) + 1;
+		const slot = existing ?? this.#fresh(peer);
+		slot.peer = peer;
+		slot.generation = generation;
+		slot.phase = "resubscribing";
+		this.#slots.set(peer.nodeId, slot);
+		this.#listen(slot);
+		this.#log(peer.nodeId, "resubscribing");
+		let subscription;
+		try {
+			subscription = await peer.subscribe({
+				onReport: (report) => {
+					if (report.value === void 0 || report.value === null) return;
+					this.#onReport(report);
+				},
+				onClosed: () => {
+					const current = this.#slots.get(peer.nodeId);
+					if (current === void 0 || current.generation !== generation) return;
+					this.#onClosed(peer.nodeId);
+				}
+			});
+		} catch (err) {
+			this.#log(peer.nodeId, "subscribe-failed", { error: errMsg(err) });
+			const current = this.#slots.get(peer.nodeId);
+			if (current === void 0 || current.generation !== generation) return;
+			current.phase = "subscribe-failed";
+			this.#schedule(peer.nodeId);
+			return;
+		}
+		if (this.#stopped || this.#slots.get(peer.nodeId)?.generation !== generation) {
+			await subscription.close().catch(() => void 0);
+			return;
+		}
+		slot.subscription = subscription;
+		slot.phase = "subscribed";
+		slot.attempt = 0;
+		this.#log(peer.nodeId, "subscribed");
+	}
+	#onClosed(nodeId) {
+		const slot = this.#slots.get(nodeId);
+		if (slot === void 0 || slot.dropping) return;
+		if (slot.phase !== "subscribed" && slot.phase !== "resubscribing") return;
+		slot.subscription = null;
+		slot.phase = "closed";
+		this.#log(nodeId, "closed");
+		if (!slot.peer.online()) {
+			slot.phase = "offline";
+			this.#log(nodeId, "offline");
+			return;
+		}
+		this.#schedule(nodeId);
+	}
+	#schedule(nodeId) {
+		const slot = this.#slots.get(nodeId);
+		if (slot === void 0 || this.#stopped) return;
+		if (slot.timer !== null) clearTimeout(slot.timer);
+		const delay = Math.min(SUBSCRIPTION_BACKOFF_MAX_MS, SUBSCRIPTION_BACKOFF_INITIAL_MS * 2 ** slot.attempt);
+		slot.attempt += 1;
+		slot.phase = "backing-off";
+		this.#log(nodeId, "backing-off", {
+			delayMs: delay,
+			attempt: slot.attempt
+		});
+		slot.timer = setTimeout(() => {
+			slot.timer = null;
+			this.#open(slot.peer);
+		}, delay);
+		if (typeof slot.timer.unref === "function") slot.timer.unref();
+	}
+	#listen(slot) {
+		if (slot.listening) return;
+		slot.listening = true;
+		slot.unlisten.push(slot.peer.onOffline(() => {
+			const current = this.#slots.get(slot.peer.nodeId);
+			if (current === void 0) return;
+			if (current.phase === "offline") return;
+			current.phase = "offline";
+			this.#log(slot.peer.nodeId, "offline");
+		}));
+		slot.unlisten.push(slot.peer.onOnline(() => {
+			const current = this.#slots.get(slot.peer.nodeId);
+			if (current === void 0 || this.#stopped) return;
+			current.attempt = 0;
+			if (current.timer !== null) {
+				clearTimeout(current.timer);
+				current.timer = null;
+			}
+			this.#log(slot.peer.nodeId, "online");
+			this.#open(current.peer);
+		}));
+	}
+	async #drop(slot) {
+		slot.dropping = true;
+		if (slot.timer !== null) clearTimeout(slot.timer);
+		slot.timer = null;
+		for (const unlisten of slot.unlisten) unlisten();
+		slot.unlisten = [];
+		const subscription = slot.subscription;
+		slot.subscription = null;
+		if (subscription !== null) try {
+			await subscription.close();
+		} catch (err) {
+			this.#logger.warn("Matter subscription close failed", {
+				tags: this.#tags(slot.peer.nodeId),
+				meta: {
+					nodeId: slot.peer.nodeId,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+	#fresh(peer) {
+		return {
+			peer,
+			phase: "resubscribing",
+			attempt: 0,
+			timer: null,
+			subscription: null,
+			unlisten: [],
+			generation: 0,
+			listening: false,
+			dropping: false
+		};
+	}
+	#tags(nodeId) {
+		const deviceId = this.#resolveDeviceId(nodeId);
+		if (deviceId !== null) return { deviceId };
+		return { brokerId: this.#brokerId };
+	}
+	#log(nodeId, phase, extra) {
+		const deviceId = this.#resolveDeviceId(nodeId);
+		this.#logger.info("Matter subscription state", {
+			tags: deviceId !== null ? { deviceId } : { brokerId: this.#brokerId },
+			meta: {
+				nodeId,
+				phase,
+				...extra
+			}
+		});
+	}
+};
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null;
+}
+function asFiniteNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "bigint") {
+		const n = Number(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+function isIterable$1(value) {
+	return isRecord$2(value) && typeof Reflect.get(value, Symbol.iterator) === "function";
+}
+function isAsyncIterable(value) {
+	return isRecord$2(value) && typeof Reflect.get(value, Symbol.asyncIterator) === "function";
+}
+/**
+* Pull attribute values out of a matter.js `ReadResult` (or a recorded fixture
+* of the same shape). Status reports and missing values are skipped — they are
+* not a measurement.
+*/
+async function collectAttributeReports(nodeId, update) {
+	const out = [];
+	const chunks = isAsyncIterable(update) ? update : isIterable$1(update) ? update : [];
+	for await (const chunk of chunks) {
+		const reports = isIterable$1(chunk) ? chunk : [];
+		for (const report of reports) {
+			const decoded = reportFromRecord(nodeId, report);
+			if (decoded !== null) out.push(decoded);
+		}
+	}
+	return out;
+}
+function reportFromRecord(nodeId, report) {
+	if (!isRecord$2(report)) return null;
+	if (report["kind"] !== "attr-value") return null;
+	if (report["value"] === void 0 || report["value"] === null) return null;
+	const path = report["path"];
+	if (!isRecord$2(path)) return null;
+	const endpointId = asFiniteNumber(path["endpointId"]);
+	const clusterId = asFiniteNumber(path["clusterId"]);
+	const attributeId = asFiniteNumber(path["attributeId"]);
+	if (endpointId === null || clusterId === null || attributeId === null) return null;
+	return {
+		nodeId,
+		endpointId,
+		clusterId,
+		attributeId,
+		value: report["value"]
+	};
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function peerOnline$1(peer) {
+	const lifecycle = peer["lifecycle"];
+	if (!isRecord$1(lifecycle)) return false;
+	return lifecycle["isOnline"] === true;
+}
+function listenLifecycle(peer, event, handler) {
+	const lifecycle = peer["lifecycle"];
+	if (!isRecord$1(lifecycle)) return () => void 0;
+	const observable = lifecycle[event];
+	if (!isRecord$1(observable)) return () => void 0;
+	const on = observable["on"];
+	const off = observable["off"];
+	if (typeof on !== "function" || typeof off !== "function") return () => void 0;
+	Reflect.apply(on, observable, [handler]);
+	return () => {
+		Reflect.apply(off, observable, [handler]);
+	};
+}
+/** Stop matter.js's own wildcard subscription so this addon owns the session. */
+function disableAutoSubscribe(peer) {
+	const stateOf = peer["stateOf"];
+	if (typeof stateOf !== "function") return;
+	let network;
+	try {
+		network = Reflect.apply(stateOf, peer, ["network"]);
+	} catch {
+		return;
+	}
+	if (!isRecord$1(network)) return;
+	if ("autoSubscribe" in network) network["autoSubscribe"] = false;
+}
+function subscriptionFrom(result) {
+	return { close: async () => {
+		if (!isRecord$1(result)) return;
+		const fn = result["close"];
+		if (typeof fn !== "function") return;
+		await Promise.resolve(Reflect.apply(fn, result, []));
+	} };
+}
+/**
+* Build a subscribable view of a commissioned peer, or null when the peer has
+* no `interaction.subscribe` (nothing to attach — the caller logs that).
+*/
+function subscribableFromPeer(peer, nodeId) {
+	if (!isRecord$1(peer)) return null;
+	const interaction = peer["interaction"];
+	if (!isRecord$1(interaction) || typeof interaction["subscribe"] !== "function") return null;
+	const subscribe = interaction["subscribe"];
+	return {
+		nodeId,
+		online: () => peerOnline$1(peer),
+		onOnline: (handler) => listenLifecycle(peer, "online", handler),
+		onOffline: (handler) => listenLifecycle(peer, "offline", handler),
+		subscribe: async (handlers) => {
+			disableAutoSubscribe(peer);
+			const request = {
+				sustain: true,
+				keepSubscriptions: false,
+				fabricFilter: true,
+				attributes: [{}],
+				minIntervalFloor: Seconds(0),
+				maxIntervalCeiling: Seconds(60),
+				bootstrapWithRead: true,
+				updated: async (update) => {
+					const reports = await collectAttributeReports(nodeId, update);
+					for (const report of reports) handlers.onReport(report);
+				},
+				closed: () => {
+					handlers.onClosed();
+				}
+			};
+			return subscriptionFrom(await Promise.resolve(Reflect.apply(subscribe, interaction, [request])));
+		}
+	};
+}
+//#endregion
 //#region src/matter-controller-impl.ts
 /**
-* Real {@link MatterController} backed by matter.js v0.17 (`@matter/main` +
-* `@matter/nodejs`).
-*
-* matter.js v0.17 uses the "node API": a {@link ServerNode} owns the controller
-* fabric, and commissioned devices are {@link ClientNode} peers reachable via
-* `serverNode.peers`. This class wraps exactly one `ServerNode` per broker
-* (= one fabric), persisting it under the addon `dataDir` via the matter.js
-* `Environment`'s `storage.path` variable.
-*
-* Bound API (matter.js 0.17.3):
-*   - `ServerNode.create({ environment, id })` — fabric owner; storage at dataDir.
-*   - `serverNode.peers.commission({ pairingCode })` — commission a node from a
-*     QR (`MT:…`) or manual pairing code; resolves to a `ClientNode`.
-*   - `serverNode.peers` — iterable of commissioned `ClientNode`s.
-*   - `clientNode.lifecycle.isOnline`, `clientNode.peerAddress.nodeId` — liveness
-*     + stable node id.
-*   - `clientNode.decommission()` — remove a node from the fabric.
-*   - endpoint `commandsOf(behaviorId)[name](args)` — outbound cluster commands.
-*
-* The dynamic endpoint/cluster/attribute introspection lives in
-* `matter-endpoint-introspect.ts` (the single matter.js dynamic-shape boundary).
-* This class polls each node's endpoint state on reconcile + emits decoded
-* attribute reports, and re-emits on node online/offline transitions.
-*
-* BLE commissioning (`@matter/nodejs-ble`) is NOT wired — that package is not
-* installed. IP / on-network commissioning is the supported path; see the class
-* `commissionNode` note.
+* Real {@link MatterController} backed by matter.js (`@matter/main` +
+* `@matter/nodejs`). ServerNode / ClientNode is the API this controller uses.
+*
+* One `ServerNode` per broker (= one fabric). Storage is matter.js's own
+* files under the addon `dataDir` (`Environment` `storage.path`) — the
+* library-owned exception for fabric root / NOC / node registry, same class
+* as HAP pairing files. Not the keychain.
+*
+* Bound API:
+*   - `ServerNode.create({ environment, id })` — fabric owner.
+*   - `serverNode.peers.commission({ pairingCode, continueCommissioningAfterPase })`.
+*   - `clientNode.interaction.subscribe({ sustain: true })` — attribute reports.
+*   - `clientNode.lifecycle` online / offline — resubscribe.
+*   - endpoint `commandsOf(behaviorId)[name](args)` — outbound commands.
+*
+* BLE commissioning is not wired. IP / on-network share codes only.
 */
 /** A commissioning failure (bad code / device unreachable), distinct from runtime. */
 var MatterCommissioningError = class extends Error {
@@ -198154,12 +198613,19 @@ var MatterJsController = class {
 	#options;
 	#logger;
 	#handlers = /* @__PURE__ */ new Set();
+	#subscriptions;
 	#server = null;
 	/** Last emitted value per `node:endpoint:cluster:attribute` (change detection). */
 	#lastValues = /* @__PURE__ */ new Map();
 	constructor(options, logger) {
 		this.#options = options;
 		this.#logger = logger;
+		this.#subscriptions = new MatterSubscriptionSupervisor({
+			brokerId: options.brokerId,
+			logger,
+			resolveDeviceId: options.resolveDeviceId ?? (() => null),
+			onReport: (report) => this.#emitIfChanged(report)
+		});
 	}
 	get options() {
 		return this.#options;
@@ -198167,19 +198633,17 @@ var MatterJsController = class {
 	/** Boot the ServerNode fabric, loading/persisting state from `dataDir`. */
 	async start() {
 		if (this.#server !== null) return;
-		const environment = this.#buildEnvironment();
-		const server = await ServerNode.create({
-			environment,
-			id: this.#options.brokerId
-		});
+		const server = this.#options.openServer !== void 0 ? await this.#options.openServer() : await this.#openProductionServer();
 		this.#server = server;
 		await server.start();
 		this.#logger.info("MatterJsController: ServerNode online", { tags: { brokerId: this.#options.brokerId } });
+		await this.syncSubscriptions();
 		this.#emitAllReports();
 	}
-	/** Close the ServerNode FIRST (frees OS sockets/subscriptions), then clear. */
+	/** Close subscriptions FIRST, then the ServerNode. */
 	async stop() {
 		this.#handlers.clear();
+		await this.#subscriptions.stop();
 		const server = this.#server;
 		this.#server = null;
 		this.#lastValues.clear();
@@ -198200,19 +198664,49 @@ var MatterJsController = class {
 	*/
 	async commissionNode(pairingCode) {
 		const server = this.#requireServer("commissionNode");
+		this.#progress({
+			phase: CommissionPhase.Discovering,
+			failure: null,
+			message: null
+		});
 		try {
-			const node = await server.peers.commission({ pairingCode });
+			const node = await server.commission({
+				pairingCode,
+				onPase: () => {
+					this.#progress({
+						phase: CommissionPhase.Pase,
+						failure: null,
+						message: null
+					});
+					this.#progress({
+						phase: CommissionPhase.Commissioning,
+						failure: null,
+						message: null
+					});
+				}
+			});
 			const view = this.#viewPeer(node);
 			this.#logger.info("MatterJsController: node commissioned", {
 				tags: { brokerId: this.#options.brokerId },
 				meta: { nodeId: view?.id ?? "(unknown)" }
 			});
+			await this.syncSubscriptions();
 			this.#emitAllReports();
 			if (view === null) throw new MatterCommissioningError("commissioned node exposed no operational id");
+			this.#progress({
+				phase: CommissionPhase.Done,
+				failure: null,
+				message: null
+			});
 			return { nodeId: view.id };
 		} catch (err) {
-			if (err instanceof MatterCommissioningError) throw err;
-			throw new MatterCommissioningError(errMsg(err), { cause: err });
+			if (err instanceof MatterCommissioningError && err.message.includes("no operational id")) {
+				this.#failCommission(err.message);
+				throw err;
+			}
+			const message = errMsg(err);
+			this.#failCommission(message);
+			throw new MatterCommissioningError(commissionFailureMessage(classifyCommissionError(message), message), { cause: err });
 		}
 	}
 	/** Pull the live commissioned-node inventory off `serverNode.peers`. */
@@ -198220,12 +198714,31 @@ var MatterJsController = class {
 		const server = this.#server;
 		if (server === null) return [];
 		const out = [];
-		for (const peer of this.#peers(server)) {
+		for (const peer of server.listPeers()) {
 			const snapshot = this.#snapshot(peer);
 			if (snapshot !== null) out.push(snapshot);
 		}
 		return out;
 	}
+	async syncSubscriptions() {
+		const server = this.#server;
+		if (server === null) return;
+		const peers = [];
+		for (const peer of server.listPeers()) {
+			const view = this.#viewPeer(peer);
+			if (view === null) continue;
+			const subscribable = subscribableFromPeer(peer, view.id);
+			if (subscribable === null) {
+				this.#logger.warn("MatterJsController: peer has no attribute subscription", {
+					tags: { brokerId: this.#options.brokerId },
+					meta: { nodeId: view.id }
+				});
+				continue;
+			}
+			peers.push(subscribable);
+		}
+		await this.#subscriptions.sync(peers);
+	}
 	async getNode(nodeId) {
 		return (await this.listNodes()).find((n) => n.nodeId === nodeId) ?? null;
 	}
@@ -198266,6 +198779,25 @@ var MatterJsController = class {
 			throw err;
 		}
 	}
+	async #openProductionServer() {
+		const environment = this.#buildEnvironment();
+		const server = await ServerNode.create({
+			environment,
+			id: this.#options.brokerId
+		});
+		return {
+			start: () => server.start(),
+			close: () => server.close(),
+			listPeers: () => this.#serverPeers(server),
+			commission: ({ pairingCode, onPase }) => server.peers.commission({
+				pairingCode,
+				continueCommissioningAfterPase: () => {
+					onPase();
+					return true;
+				}
+			})
+		};
+	}
 	#buildEnvironment() {
 		const env = Environment.default;
 		env.vars.set("storage.path", this.#options.dataDir);
@@ -198278,13 +198810,13 @@ var MatterJsController = class {
 		return this.#server;
 	}
 	/** Iterate the commissioned peers of a ServerNode (cast-free). */
-	#peers(server) {
+	#serverPeers(server) {
 		const peers = server.peers;
 		if (isIterable(peers)) return peers;
 		return [];
 	}
 	#findPeer(server, nodeId) {
-		for (const peer of this.#peers(server)) {
+		for (const peer of server.listPeers()) {
 			const view = this.#viewPeer(peer);
 			if (view !== null && view.id === nodeId) return view;
 		}
@@ -198292,12 +198824,23 @@ var MatterJsController = class {
 	}
 	/** Raw (un-viewed) peer object for operations that call its methods. */
 	#rawPeer(server, nodeId) {
-		for (const peer of this.#peers(server)) {
+		for (const peer of server.listPeers()) {
 			const view = this.#viewPeer(peer);
 			if (view !== null && view.id === nodeId) return peer;
 		}
 		return null;
 	}
+	#progress(progress) {
+		this.#options.onCommissionProgress?.(progress);
+	}
+	#failCommission(message) {
+		const failure = classifyCommissionError(message);
+		this.#progress({
+			phase: CommissionPhase.Failed,
+			failure,
+			message: commissionFailureMessage(failure, message)
+		});
+	}
 	/** Reduce a peer to the read-only view the addon models. */
 	#viewPeer(peer) {
 		if (!isRecord(peer)) return null;
@@ -198341,7 +198884,7 @@ var MatterJsController = class {
 	#emitAllReports() {
 		const server = this.#server;
 		if (server === null) return;
-		for (const peer of this.#peers(server)) {
+		for (const peer of server.listPeers()) {
 			const view = this.#viewPeer(peer);
 			if (view === null) continue;
 			for (const ep of readNodeEndpoints(view.rootEndpoint)) for (const attr of ep.attributes) {
@@ -198357,6 +198900,7 @@ var MatterJsController = class {
 		}
 	}
 	#emitIfChanged(report) {
+		if (report.value === void 0 || report.value === null) return;
 		const key = `${report.nodeId}:${report.endpointId}:${report.clusterId}:${report.attributeId}`;
 		const prev = this.#lastValues.get(key);
 		if (prev !== void 0 && shallowEqual(prev, report.value)) return;
@@ -198442,12 +198986,24 @@ var MatterNodeResolver = class {
 	#attrs = /* @__PURE__ */ new Map();
 	/** Live attribute-report subscribers (endpoint device classes). */
 	#listeners = /* @__PURE__ */ new Set();
+	/** Adopted container id per Matter node, for subscription logs. */
+	#deviceIds = /* @__PURE__ */ new Map();
 	/**
 	* Subscribe to live attribute reports across all brokers. Endpoint device
 	* classes subscribe on activate (filtering to their own node/endpoint) so a
 	* push report decodes straight into their runtime-state slice. Returns a
 	* disposer.
 	*/
+	/** Remember the CamStack container id for a commissioned node. */
+	bindDevice(nodeId, deviceId) {
+		this.#deviceIds.set(nodeId, deviceId);
+	}
+	unbindDevice(nodeId) {
+		this.#deviceIds.delete(nodeId);
+	}
+	deviceIdFor(nodeId) {
+		return this.#deviceIds.get(nodeId) ?? null;
+	}
 	onAttributeReport(listener) {
 		this.#listeners.add(listener);
 		return () => {
@@ -198509,6 +199065,7 @@ var MatterNodeResolver = class {
 		this.#nodes.clear();
 		this.#attrs.clear();
 		this.#listeners.clear();
+		this.#deviceIds.clear();
 	}
 };
 /** The single in-process per-broker node resolver shared across the addon. */
@@ -198568,6 +199125,7 @@ var MatterIntegrationManager = class {
 	#nodeCount = 0;
 	#lastCheckedAt = null;
 	#error = null;
+	#commission = IDLE_COMMISSION_PROGRESS;
 	constructor(options) {
 		this.#id = options.id;
 		this.#name = options.name;
@@ -198578,7 +199136,17 @@ var MatterIntegrationManager = class {
 		this.#onDisconnected = options.onDisconnected;
 		this.#onNodesChanged = options.onNodesChanged;
 		this.#onAttributeReport = options.onAttributeReport;
-		this.#makeController = options.makeController ?? ((opts) => new MatterJsController(opts, this.#logger));
+		this.#makeController = options.makeController ?? ((opts) => new MatterJsController({
+			...opts,
+			onCommissionProgress: (progress) => {
+				this.#commission = progress;
+			},
+			resolveDeviceId: (nodeId) => matterNodes.deviceIdFor(nodeId)
+		}, this.#logger));
+	}
+	/** Latest commissioning phase for `broker.getState({ key: 'commission' })`. */
+	getCommissionProgress() {
+		return this.#commission;
 	}
 	/** The connection settings the manager is currently configured with. */
 	getConnection() {
@@ -198653,6 +199221,7 @@ var MatterIntegrationManager = class {
 		if (controller === null) return;
 		try {
 			const nodes = await controller.listNodes();
+			await controller.syncSubscriptions();
 			this.#nodeCount = nodes.length;
 			this.#lastCheckedAt = Date.now();
 			matterNodes.setNodes(this.#id, nodes);
@@ -198833,6 +199402,10 @@ var MatterBrokerRegistry = class {
 		if (!mgr) throw new Error(`MatterBrokerRegistry: unknown broker id "${brokerId}"`);
 		return mgr.commissionNode(pairingCode);
 	}
+	getCommissionProgress(brokerId) {
+		const mgr = this.#managers.get(brokerId);
+		return mgr ? mgr.getCommissionProgress() : null;
+	}
 	async removeNode(brokerId, nodeId) {
 		const mgr = this.#managers.get(brokerId);
 		if (!mgr) throw new Error(`MatterBrokerRegistry: unknown broker id "${brokerId}"`);
@@ -198935,6 +199508,26 @@ function toRecord(value) {
 function settingsToMatterConnection(settings) {
 	return matterConnectionSchema.parse(toRecord(settings));
 }
+/**
+* Settings readers see an empty string for both secrets. The stored value
+* stays in the keychain (records `secret` meta). An empty round-trip must
+* not wipe it — see {@link mergeMatterSecrets}.
+*/
+function publicMatterConnection(connection) {
+	return {
+		...connection,
+		wifiPassword: "",
+		threadDataset: ""
+	};
+}
+/** Keep a stored secret when the form sent back the redacted empty string. */
+function mergeMatterSecrets(existing, incoming) {
+	return {
+		...incoming,
+		wifiPassword: incoming.wifiPassword.length > 0 ? incoming.wifiPassword : existing.wifiPassword,
+		threadDataset: incoming.threadDataset.length > 0 ? incoming.threadDataset : existing.threadDataset
+	};
+}
 /** Hand-written connection form for the broker/integration creation UI. */
 function buildConnectionFormSchema() {
 	return { sections: [{
@@ -198946,9 +199539,10 @@ function buildConnectionFormSchema() {
 		columns: 1,
 		fields: [
 			{
-				type: "text",
+				type: "password",
 				key: "threadDataset",
 				secret: true,
+				showToggle: true,
 				label: "Thread operational dataset (hex, optional)",
 				labelKey: "matter-broker:connection.s_matter-fabric.threadDataset.label",
 				placeholder: "0e08000000000001…"
@@ -199025,17 +199619,14 @@ var MATTER_KIND = "matter";
 * Construct the `broker` cap provider for the Matter addon. Pure builder.
 * Mirrors `buildEcowittBrokerProvider`. The defining Matter operation —
 * commissioning — is surfaced through `publish` with
-* `target: { action: 'commissionNode' }` and `payload: { pairingCode }`. The
-* Wi-Fi password is the only secret; it is redacted on settings reads and
-* preserved on an empty round-trip.
+* `target: { action: 'commissionNode' }` and `payload: { pairingCode }`.
+* `threadDataset` and `wifiPassword` are redacted on settings reads and
+* preserved on an empty round-trip. Fabric keys stay in matter.js storage.
 */
 function buildMatterBrokerProvider(deps) {
 	const { ownerAddonId, registry, getBrokers, persistBrokers, cascadeRemoveDevices, logger } = deps;
 	const owns = (id) => getBrokers().some((b) => b.id === id);
-	const redact = (entry) => ({
-		...entry.connection,
-		wifiPassword: ""
-	});
+	const redact = (entry) => publicMatterConnection(entry.connection);
 	return {
 		list: async ({ kind }) => {
 			if (kind && kind !== MATTER_KIND) return [];
@@ -199103,10 +199694,7 @@ function buildMatterBrokerProvider(deps) {
 			const existing = getBrokers().find((b) => b.id === id);
 			if (!existing) return;
 			const parsed = settingsToMatterConnection(settings);
-			const merged = {
-				...parsed,
-				wifiPassword: parsed.wifiPassword.length > 0 ? parsed.wifiPassword : existing.connection.wifiPassword
-			};
+			const merged = mergeMatterSecrets(existing.connection, parsed);
 			const updated = await registry.updateEntry(id, merged);
 			await persistBrokers(getBrokers().map((b) => b.id === id ? updated : b));
 		},
@@ -199142,7 +199730,7 @@ function buildMatterBrokerProvider(deps) {
 			if (!owns(brokerId)) throw new Error(`matter: unknown broker ${brokerId}`);
 			const action = typeof target["action"] === "string" ? target["action"] : void 0;
 			if (action === "commissionNode") {
-				const code = typeof payload === "object" && payload !== null && "pairingCode" in payload ? String(payload["pairingCode"] ?? "") : "";
+				const code = pairingCodeFromPayload(payload);
 				parsePairingCode(code);
 				return registry.commissionNode(brokerId, code);
 			}
@@ -199150,13 +199738,23 @@ function buildMatterBrokerProvider(deps) {
 		},
 		subscribe: async () => ({ subscriptionId: "" }),
 		unsubscribe: async () => void 0,
-		getState: async () => null,
+		getState: async ({ brokerId, key }) => {
+			if (key !== "commission") return null;
+			return registry.getCommissionProgress(brokerId);
+		},
 		getStatus: async () => ({
 			brokerCount: registry.size(),
 			connectedCount: registry.connectedCount()
 		})
 	};
 }
+function pairingCodeFromPayload(payload) {
+	if (typeof payload !== "object" || payload === null || !("pairingCode" in payload)) return "";
+	const code = payload.pairingCode;
+	if (typeof code === "string") return code;
+	if (typeof code === "number" && Number.isFinite(code)) return String(code);
+	return "";
+}
 //#endregion
 //#region src/matter-discovery.ts
 /**
@@ -199387,6 +199985,27 @@ function setBrokerDevicesOnline(devices, brokerId, online) {
 	return count;
 }
 //#endregion
+//#region src/matter-lock-command.ts
+/**
+* Decide the command arguments. `pinRequired` comes from the live
+* RequirePinForRemoteOperation attribute, not from a stored secret.
+*/
+function planDoorLockCommand(input) {
+	const code = input.code?.trim() ?? "";
+	if (input.pinRequired && code.length === 0) return {
+		ok: false,
+		reason: "pin-required"
+	};
+	if (code.length > 0) return {
+		ok: true,
+		args: { pinCode: code }
+	};
+	return {
+		ok: true,
+		args: {}
+	};
+}
+//#endregion
 //#region src/devices/matter-endpoint-device.ts
 /**
 * Persisted config every Matter endpoint child carries. `nodeId`/`endpointId`
@@ -199478,7 +200097,8 @@ var COLD_POWER = { lastFetchedAt: 0 };
 * arrives, each cap reads its cold-start default.
 */
 var MatterEndpointDevice = class extends BaseDevice {
-	features = [];
+	/** Live RequirePinForRemoteOperation. Commands read this, not a stored PIN. */
+	pinRequired = false;
 	brokerId;
 	nodeId;
 	endpointId;
@@ -199492,12 +200112,17 @@ var MatterEndpointDevice = class extends BaseDevice {
 		this.nodeId = persisted.nodeId;
 		this.endpointId = persisted.endpointId;
 		this.caps = persisted.capabilities.filter(isKnownCap);
+		this.pinRequired = matterNodes.getAttribute(this.brokerId, this.nodeId, this.endpointId, MatterClusterId.DoorLock, MatterAttributeId.RequirePinForRemoteOperation) === true;
 		this.online = matterNodes.getNode(this.brokerId, this.nodeId)?.online ?? true;
 		this.updateSourceInfo({
 			id: `${this.nodeId}:${this.endpointId}`,
 			system: "matter"
 		});
 	}
+	/** PIN-required locks advertise the feature the lock UI already understands. */
+	get features() {
+		return this.pinRequired ? [DeviceFeature.LockPinRequired] : [];
+	}
 	async onActivate() {
 		await super.onActivate();
 		for (const cap of this.caps) {
@@ -199525,7 +200150,29 @@ var MatterEndpointDevice = class extends BaseDevice {
 			value: report.value
 		});
 		if (decoded === null) return;
+		if (decoded.detail === "pin-required" || decoded.detail === "pin-not-required") {
+			const next = decoded.detail === "pin-required";
+			if (next !== this.pinRequired) {
+				this.pinRequired = next;
+				this.ctx.logger.info("Matter lock PIN requirement changed", {
+					tags: { deviceId: this.id },
+					meta: {
+						nodeId: this.nodeId,
+						endpointId: this.endpointId,
+						pinRequired: next
+					}
+				});
+			}
+		} else if (decoded.detail !== void 0) this.ctx.logger.info("Matter lock detail", {
+			tags: { deviceId: this.id },
+			meta: {
+				nodeId: this.nodeId,
+				endpointId: this.endpointId,
+				detail: decoded.detail
+			}
+		});
 		if (!this.registeredCaps.has(decoded.cap)) return;
+		if (Object.keys(decoded.patch).length === 0) return;
 		this.runtimeState.patchCapState(CAP_SLICE_NAME[decoded.cap], decoded.patch);
 	}
 	/** Invoke a cluster command on this endpoint via the live controller. */
@@ -199621,30 +200268,52 @@ var MatterEndpointDevice = class extends BaseDevice {
 		};
 		this.ctx.registerNativeCap(lockControlCapability, {
 			getStatus: async () => this.runtimeState.getCapState("lock-control") ?? COLD,
-			lock: async () => {
-				await this.invoke(MatterClusterId.DoorLock, "lockDoor");
-				this.runtimeState.setCapState("lock-control", {
-					state: "locked",
-					lastChangedAt: Date.now()
-				});
+			lock: async ({ code }) => {
+				await this.invokeLock("lockDoor", "locking", code);
 			},
-			unlock: async () => {
-				await this.invoke(MatterClusterId.DoorLock, "unlockDoor");
-				this.runtimeState.setCapState("lock-control", {
-					state: "unlocked",
-					lastChangedAt: Date.now()
-				});
+			unlock: async ({ code }) => {
+				await this.invokeLock("unlockDoor", "unlocking", code);
 			},
 			open: async () => {
-				await this.invoke(MatterClusterId.DoorLock, "unlockDoor");
-				this.runtimeState.setCapState("lock-control", {
-					state: "unlocked",
-					lastChangedAt: Date.now()
-				});
+				await this.invokeLock("unlockDoor", "unlocking", void 0);
 			}
 		});
 		this.runtimeState.setCapState("lock-control", COLD);
 	}
+	/**
+	* Send lockDoor / unlockDoor. The final locked/unlocked state arrives on the
+	* attribute subscription — this method only records the in-flight transition.
+	* A PIN is forwarded on the command and nowhere else.
+	*/
+	async invokeLock(commandName, pending, code) {
+		const plan = planDoorLockCommand({
+			pinRequired: this.pinRequired,
+			code
+		});
+		if (!plan.ok) {
+			this.ctx.logger.warn("Matter lock command refused: PIN required and none was provided", {
+				tags: { deviceId: this.id },
+				meta: {
+					nodeId: this.nodeId,
+					endpointId: this.endpointId,
+					commandName
+				}
+			});
+			throw new Error("matter-broker: this lock requires a PIN for remote operation");
+		}
+		const previous = this.runtimeState.getCapState("lock-control");
+		this.runtimeState.setCapState("lock-control", {
+			state: pending,
+			lastChangedAt: Date.now()
+		});
+		try {
+			const args = "pinCode" in plan.args ? plan.args : void 0;
+			await this.invoke(MatterClusterId.DoorLock, commandName, args);
+		} catch (err) {
+			if (previous !== void 0) this.runtimeState.setCapState("lock-control", previous);
+			throw err;
+		}
+	}
 	registerCover() {
 		const COLD = {
 			state: "closed",
@@ -199865,11 +200534,16 @@ var MatterNodeDevice = class extends BaseDevice {
 		this.nodeId = cfg.nodeId;
 		this.integrationId = cfg.integrationId;
 		this.online = matterNodes.getNode(this.brokerId, this.nodeId)?.online ?? false;
+		matterNodes.bindDevice(this.nodeId, this.id);
 		this.updateSourceInfo({
 			id: this.nodeId,
 			system: "matter"
 		});
 	}
+	async removeDevice() {
+		matterNodes.unbindDevice(this.nodeId);
+		await super.removeDevice();
+	}
 	getAccessoryChildren() {
 		const specs = [];
 		for (const endpoint of this.config.values.endpoints) {