@riddix/hamh 2.0.43 → 2.0.45

package/dist/backend/cli.js

@@ -145734,6 +145734,9 @@ var init_home_assistant_filter = __esm({
       HomeAssistantMatcherType2["Label"] = "label";
       HomeAssistantMatcherType2["EntityLabel"] = "entity_label";
       HomeAssistantMatcherType2["DeviceLabel"] = "device_label";
+      HomeAssistantMatcherType2["EntityLabelRegex"] = "entity_label_regex";
+      HomeAssistantMatcherType2["DeviceLabelRegex"] = "device_label_regex";
+      HomeAssistantMatcherType2["AnyFieldRegex"] = "any_field_regex";
       HomeAssistantMatcherType2["Area"] = "area";
       HomeAssistantMatcherType2["EntityCategory"] = "entity_category";
       HomeAssistantMatcherType2["DeviceName"] = "device_name";
@@ -146125,6 +146128,7 @@ var init_clusters2 = __esm({
       ClusterId3["pm10ConcentrationMeasurement"] = "pm10ConcentrationMeasurement";
       ClusterId3["pm25ConcentrationMeasurement"] = "pm25ConcentrationMeasurement";
       ClusterId3["powerSource"] = "powerSource";
+      ClusterId3["powerTopology"] = "powerTopology";
       ClusterId3["pressureMeasurement"] = "pressureMeasurement";
       ClusterId3["relativeHumidityMeasurement"] = "relativeHumidityMeasurement";
       ClusterId3["smokeCoAlarm"] = "smokeCoAlarm";
@@ -146638,7 +146642,7 @@ var init_bridge_config_schema = __esm({
             {
               const: "regex",
               title: "regex",
-              description: "Full regular expression matching entity IDs. Use ^ and $ for anchors. Example: '^(light|switch)\\.kitchen_.*' matches all kitchen lights and switches."
+              description: "Regex tested against the entity_id only (e.g. 'light.kitchen_lamp'). For labels use entity_label_regex or device_label_regex. Example: '^(light|switch)\\.kitchen_.*'."
             },
             {
               const: "domain",
@@ -146665,6 +146669,21 @@ var init_bridge_config_schema = __esm({
               title: "device_label",
               description: "Matches ALL entities of a device if the device has this label. Use this to include a complete device with all its entities."
             },
+            {
+              const: "entity_label_regex",
+              title: "entity_label_regex",
+              description: "Regex tested against entity-label slugs and display names. Matches if any label assigned to the entity matches. Example: '^(matter|voice).*'."
+            },
+            {
+              const: "device_label_regex",
+              title: "device_label_regex",
+              description: "Regex tested against device-label slugs and display names. Matches ALL entities of a device whose label matches. Example: '^(matter|voice).*'."
+            },
+            {
+              const: "any_field_regex",
+              title: "any_field_regex",
+              description: "Regex tested against a single-line key=value haystack covering entity_id, domain, platform, area, entity_category, device_class, entity_labels, entity_label_names, device_labels, device_label_names, device_name, product_name. Use lookaheads for AND, alternation for OR. Example: '(?=.*domain=light)(?=.*area=living_room)|(?=.*domain=switch)(?=.*entity_labels=.*\\bvoice\\b)'."
+            },
             {
               const: "area",
               title: "area",
@@ -146813,6 +146832,20 @@ var init_bridge_config_schema = __esm({
           description: "Workaround for Alexa resetting light brightness to 100% after subscription renewal. When enabled, the bridge ignores brightness commands that set lights to 100% within 200ms of a turn-on command for the same light. WARNING: breaks Apple Home's 'set room to 100%' Siri commands, which use the same on() + moveToLevel(254) pattern. Only enable on Alexa-only bridges.",
           type: "boolean",
           default: false
+        },
+        useHaRegistrySerial: {
+          title: "Use HA Registry Serial Number",
+          description: "Fall back to the Home Assistant device registry serial_number when no per-entity customSerialNumber is configured. Default off because changing serialNumber after commissioning can confuse controllers. A per-entity customSerialNumber still takes precedence.",
+          type: "boolean",
+          default: false
+        },
+        coverSliderDebounceMs: {
+          title: "Cover Slider Debounce (ms)",
+          description: "Override the cover position-update debounce window for this bridge. Some controllers (Apple Home) stream slider updates while the user is still dragging, causing covers to start moving toward an intermediate target. Set to the time the bridge should wait after the last update before sending the final value to Home Assistant. 0 keeps the built-in two-phase debounce (400 ms initial / 150 ms subsequent), which fits most controllers. Try 800\u20131500 ms for slow blinds. A per-entity override on a single cover wins over this flag.",
+          type: "number",
+          minimum: 0,
+          maximum: 5e3,
+          default: 0
         }
       }
     };
@@ -146879,6 +146912,14 @@ var init_bridge_config_schema = __esm({
           description: "Append a suffix to every entity serial number on this bridge. Useful for forcing controllers like Aqara to treat devices as new and bypass cached device data. Leave empty for default behavior.",
           maxLength: 16
         },
+        sessionMaxAgeHours: {
+          title: "Session Rotation Max Age (hours)",
+          type: "number",
+          description: "Server Mode only. Rotate matter sessions older than this many hours so iPhone clients re-subscribe and Apple Home unsticks 'Updating' tiles. Set 0 to disable rotation. Range 0-168, default 4. (#287)",
+          default: 4,
+          minimum: 0,
+          maximum: 168
+        },
         filter: homeAssistantFilterSchema,
         featureFlags: featureFlagSchema
       },
@@ -147325,7 +147366,7 @@ var HA_MESSAGE_TIMEOUT_MS;
 var init_send_ha_message = __esm({
   "src/utils/send-ha-message.ts"() {
     "use strict";
-    HA_MESSAGE_TIMEOUT_MS = 3e4;
+    HA_MESSAGE_TIMEOUT_MS = 6e4;
   }
 });
 
@@ -147873,6 +147914,7 @@ WARNING: ${includeIdentity ? "This backup contains sensitive Matter identity dat
                     mopIntensityEntity: config10.mopIntensityEntity,
                     valetudoIdentifier: config10.valetudoIdentifier,
                     coverSwapOpenClose: config10.coverSwapOpenClose,
+                    coverSliderDebounceMs: config10.coverSliderDebounceMs,
                     disableClimateOnOff: config10.disableClimateOnOff,
                     disableClimateFanControl: config10.disableClimateFanControl,
                     customServiceAreas: config10.customServiceAreas,
@@ -148020,6 +148062,7 @@ WARNING: ${includeIdentity ? "This backup contains sensitive Matter identity dat
                   temperatureEntity: config10.temperatureEntity,
                   valetudoIdentifier: config10.valetudoIdentifier,
                   coverSwapOpenClose: config10.coverSwapOpenClose,
+                  coverSliderDebounceMs: config10.coverSliderDebounceMs,
                   disableClimateOnOff: config10.disableClimateOnOff,
                   disableClimateFanControl: config10.disableClimateFanControl,
                   customServiceAreas: config10.customServiceAreas,
@@ -148390,6 +148433,15 @@ function bridgeIconApi(storageLocation) {
       res.json({ success: true, iconUrl });
     }
   );
+  router.get(
+    "/:bridgeId/exists",
+    (req, res) => {
+      const bridgeId = req.params.bridgeId;
+      const files = fs2.readdirSync(iconsDir);
+      const exists = files.some((f) => f.startsWith(`${bridgeId}.`));
+      res.json({ exists });
+    }
+  );
   router.get("/:bridgeId", (req, res) => {
     const bridgeId = req.params.bridgeId;
     const files = fs2.readdirSync(iconsDir);
@@ -148413,16 +148465,6 @@ function bridgeIconApi(storageLocation) {
     fs2.unlinkSync(filePath);
     res.json({ success: true });
   });
-  router.head("/:bridgeId", (req, res) => {
-    const bridgeId = req.params.bridgeId;
-    const files = fs2.readdirSync(iconsDir);
-    const iconFile = files.find((f) => f.startsWith(`${bridgeId}.`));
-    if (iconFile) {
-      res.status(200).end();
-    } else {
-      res.status(404).end();
-    }
-  });
   return router;
 }
 
@@ -148842,6 +148884,7 @@ function entityMappingApi(mappingStorage) {
       customProductName: body.customProductName,
       customVendorName: body.customVendorName,
       customSerialNumber: body.customSerialNumber,
+      customVendorId: body.customVendorId,
       disabled: body.disabled,
       filterLifeEntity: body.filterLifeEntity,
       cleaningModeEntity: body.cleaningModeEntity,
@@ -148860,8 +148903,10 @@ function entityMappingApi(mappingStorage) {
       currentRoomEntity: body.currentRoomEntity,
       valetudoIdentifier: body.valetudoIdentifier,
       coverSwapOpenClose: body.coverSwapOpenClose,
+      coverSliderDebounceMs: body.coverSliderDebounceMs,
       disableClimateOnOff: body.disableClimateOnOff,
       disableClimateFanControl: body.disableClimateFanControl,
+      climateKeepModeOnIdle: body.climateKeepModeOnIdle,
       composedEntities: body.composedEntities
     };
     const config10 = await mappingStorage.setMapping(request);
@@ -149325,8 +149370,10 @@ function configToProfileEntry(config10) {
     customFanSpeedTags: config10.customFanSpeedTags,
     valetudoIdentifier: config10.valetudoIdentifier,
     coverSwapOpenClose: config10.coverSwapOpenClose,
+    coverSliderDebounceMs: config10.coverSliderDebounceMs,
     disableClimateOnOff: config10.disableClimateOnOff,
-    disableClimateFanControl: config10.disableClimateFanControl
+    disableClimateFanControl: config10.disableClimateFanControl,
+    climateKeepModeOnIdle: config10.climateKeepModeOnIdle
   };
 }
 function mappingProfileApi(mappingStorage) {
@@ -149448,8 +149495,10 @@ function mappingProfileApi(mappingStorage) {
           customFanSpeedTags: entry.customFanSpeedTags,
           valetudoIdentifier: entry.valetudoIdentifier,
           coverSwapOpenClose: entry.coverSwapOpenClose,
+          coverSliderDebounceMs: entry.coverSliderDebounceMs,
           disableClimateOnOff: entry.disableClimateOnOff,
-          disableClimateFanControl: entry.disableClimateFanControl
+          disableClimateFanControl: entry.disableClimateFanControl,
+          climateKeepModeOnIdle: entry.climateKeepModeOnIdle
         });
         applied++;
       } catch (e) {
@@ -149501,6 +149550,18 @@ function testMatcher(matcher, device, entity, entityState, labels) {
       const slug = resolveLabelValue(matcher.value, labels);
       return !!device?.labels && device.labels.includes(slug);
     }
+    case "entity_label_regex":
+      return testLabelRegex(matcher.value, entity?.labels, labels);
+    case "device_label_regex":
+      return testLabelRegex(matcher.value, device?.labels, labels);
+    case "any_field_regex":
+      return testAnyFieldRegex(
+        matcher.value,
+        entity,
+        device,
+        entityState,
+        labels
+      );
     case "entity_category":
       return entity?.entity_category === matcher.value;
     case "platform":
@@ -149535,6 +149596,62 @@ function testRegex(pattern2, value) {
     return false;
   }
 }
+function testLabelRegex(pattern2, assigned, labels) {
+  if (!assigned?.length) {
+    return false;
+  }
+  let regex;
+  try {
+    regex = new RegExp(pattern2);
+  } catch {
+    return false;
+  }
+  for (const slug of assigned) {
+    if (regex.test(slug)) {
+      return true;
+    }
+    const named = labels?.find((l) => l.label_id === slug)?.name;
+    if (named && regex.test(named)) {
+      return true;
+    }
+  }
+  return false;
+}
+function testAnyFieldRegex(pattern2, entity, device, entityState, labels) {
+  let regex;
+  try {
+    regex = new RegExp(pattern2);
+  } catch {
+    return false;
+  }
+  return regex.test(buildEntityHaystack(entity, device, entityState, labels));
+}
+function buildEntityHaystack(entity, device, entityState, labels) {
+  const domain = entity.entity_id.split(".")[0];
+  const entityArea = entity.area_id ?? (typeof device?.area_id === "string" ? device.area_id : "");
+  const entityCategory = typeof entity.entity_category === "string" ? entity.entity_category : "";
+  const deviceClass = typeof entityState?.attributes?.device_class === "string" ? entityState.attributes.device_class : "";
+  const entityLabelSlugs = entity.labels ?? [];
+  const deviceLabelSlugs = device?.labels ?? [];
+  const entityLabelNames = entityLabelSlugs.map((slug) => labels?.find((l) => l.label_id === slug)?.name ?? "").filter((name) => name.length > 0);
+  const deviceLabelNames = deviceLabelSlugs.map((slug) => labels?.find((l) => l.label_id === slug)?.name ?? "").filter((name) => name.length > 0);
+  const deviceName = device?.name_by_user ?? device?.name ?? device?.default_name ?? "";
+  const productName = device?.model ?? device?.default_model ?? "";
+  return [
+    `entity_id=${entity.entity_id}`,
+    `domain=${domain}`,
+    `platform=${entity.platform ?? ""}`,
+    `area=${entityArea ?? ""}`,
+    `entity_category=${entityCategory}`,
+    `device_class=${deviceClass}`,
+    `entity_labels=${entityLabelSlugs.join(",")}`,
+    `entity_label_names=${entityLabelNames.join(",")}`,
+    `device_labels=${deviceLabelSlugs.join(",")}`,
+    `device_label_names=${deviceLabelNames.join(",")}`,
+    `device_name=${deviceName}`,
+    `product_name=${productName}`
+  ].join(" ");
+}
 function testDeviceName(pattern2, device) {
   if (!device) {
     return false;
@@ -152042,7 +152159,8 @@ var Options = class {
     return {
       url: this.startOptions.homeAssistantUrl,
       accessToken: this.startOptions.homeAssistantAccessToken,
-      refreshInterval: this.startOptions.homeAssistantRefreshInterval
+      refreshInterval: this.startOptions.homeAssistantRefreshInterval,
+      messageTimeoutMs: this.startOptions.haMessageTimeout
     };
   }
   get webApi() {
@@ -152734,25 +152852,33 @@ init_retry();
 
 // src/services/home-assistant/api/get-registry.ts
 init_send_ha_message();
-async function getRegistry(connection) {
-  return sendHaMessage(connection, {
-    type: "config/entity_registry/list"
-  });
+async function getRegistry(connection, timeoutMs) {
+  return sendHaMessage(
+    connection,
+    { type: "config/entity_registry/list" },
+    timeoutMs
+  );
 }
-async function getDeviceRegistry(connection) {
-  return sendHaMessage(connection, {
-    type: "config/device_registry/list"
-  });
+async function getDeviceRegistry(connection, timeoutMs) {
+  return sendHaMessage(
+    connection,
+    { type: "config/device_registry/list" },
+    timeoutMs
+  );
 }
-async function getLabelRegistry(connection) {
-  return sendHaMessage(connection, {
-    type: "config/label_registry/list"
-  });
+async function getLabelRegistry(connection, timeoutMs) {
+  return sendHaMessage(
+    connection,
+    { type: "config/label_registry/list" },
+    timeoutMs
+  );
 }
-async function getAreaRegistry(connection) {
-  return sendHaMessage(connection, {
-    type: "config/area_registry/list"
-  });
+async function getAreaRegistry(connection, timeoutMs) {
+  return sendHaMessage(
+    connection,
+    { type: "config/area_registry/list" },
+    timeoutMs
+  );
 }
 
 // src/services/home-assistant/home-assistant-registry.ts
@@ -152855,12 +152981,15 @@ var HomeAssistantRegistry = class extends Service {
         }
       });
     }
+    const timeoutMs = this.options.messageTimeoutMs;
     const [entityRegistry, statesList, deviceRegistry, labels, areas] = await Promise.all([
-      getRegistry(connection),
+      getRegistry(connection, timeoutMs),
       getStates(connection),
-      getDeviceRegistry(connection),
-      getLabelRegistry(connection).catch(() => []),
-      getAreaRegistry(connection).catch(
+      getDeviceRegistry(connection, timeoutMs),
+      getLabelRegistry(connection, timeoutMs).catch(
+        () => []
+      ),
+      getAreaRegistry(connection, timeoutMs).catch(
         () => []
       )
     ]);
@@ -153329,6 +153458,7 @@ var EntityMappingStorage = class extends Service {
       customProductName: request.customProductName?.trim() || void 0,
       customVendorName: request.customVendorName?.trim() || void 0,
       customSerialNumber: request.customSerialNumber?.trim() || void 0,
+      customVendorId: sanitizeVendorId(request.customVendorId),
       disabled: request.disabled,
       filterLifeEntity: request.filterLifeEntity?.trim() || void 0,
       cleaningModeEntity: request.cleaningModeEntity?.trim() || void 0,
@@ -153349,11 +153479,13 @@ var EntityMappingStorage = class extends Service {
       currentRoomEntity: request.currentRoomEntity?.trim() || void 0,
       valetudoIdentifier: request.valetudoIdentifier?.trim() || void 0,
       coverSwapOpenClose: request.coverSwapOpenClose || void 0,
+      coverSliderDebounceMs: sanitizeDebounceMs(request.coverSliderDebounceMs),
       disableClimateOnOff: request.disableClimateOnOff || void 0,
       disableClimateFanControl: request.disableClimateFanControl || void 0,
+      climateKeepModeOnIdle: request.climateKeepModeOnIdle || void 0,
       composedEntities: request.composedEntities?.filter((e) => e.entityId?.trim()) ?? void 0
     };
-    if (!config10.matterDeviceType && !config10.customName && !config10.customProductName && !config10.customVendorName && !config10.customSerialNumber && config10.disabled !== true && !config10.filterLifeEntity && !config10.cleaningModeEntity && !config10.temperatureEntity && !config10.humidityEntity && !config10.batteryEntity && !config10.roomEntities && !config10.disableLockPin && !config10.powerEntity && !config10.energyEntity && !config10.pressureEntity && !config10.suctionLevelEntity && !config10.mopIntensityEntity && (!config10.customServiceAreas || config10.customServiceAreas.length === 0) && (!config10.customFanSpeedTags || Object.keys(config10.customFanSpeedTags).length === 0) && !config10.currentRoomEntity && !config10.valetudoIdentifier && !config10.coverSwapOpenClose && !config10.disableClimateOnOff && !config10.disableClimateFanControl && (!config10.composedEntities || config10.composedEntities.length === 0)) {
+    if (!config10.matterDeviceType && !config10.customName && !config10.customProductName && !config10.customVendorName && !config10.customSerialNumber && config10.customVendorId === void 0 && config10.disabled !== true && !config10.filterLifeEntity && !config10.cleaningModeEntity && !config10.temperatureEntity && !config10.humidityEntity && !config10.batteryEntity && !config10.roomEntities && !config10.disableLockPin && !config10.powerEntity && !config10.energyEntity && !config10.pressureEntity && !config10.suctionLevelEntity && !config10.mopIntensityEntity && (!config10.customServiceAreas || config10.customServiceAreas.length === 0) && (!config10.customFanSpeedTags || Object.keys(config10.customFanSpeedTags).length === 0) && !config10.currentRoomEntity && !config10.valetudoIdentifier && !config10.coverSwapOpenClose && !config10.coverSliderDebounceMs && !config10.disableClimateOnOff && !config10.disableClimateFanControl && !config10.climateKeepModeOnIdle && (!config10.composedEntities || config10.composedEntities.length === 0)) {
       bridgeMap.delete(request.entityId);
     } else {
       bridgeMap.set(request.entityId, config10);
@@ -153373,6 +153505,26 @@ var EntityMappingStorage = class extends Service {
     await this.persist();
   }
 };
+function sanitizeVendorId(value) {
+  if (value === void 0 || value === null || value === "") {
+    return void 0;
+  }
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 65534) {
+    return void 0;
+  }
+  return n;
+}
+function sanitizeDebounceMs(value) {
+  if (value === void 0 || value === null || value === "") {
+    return void 0;
+  }
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isFinite(n) || n <= 0) {
+    return void 0;
+  }
+  return Math.min(5e3, Math.round(n));
+}
 
 // src/services/storage/lock-credential-storage.ts
 init_service();
@@ -165393,8 +165545,10 @@ var ServerModeServerNode = class extends ServerNode {
   async updateDeviceIdentity(entityId, device, mapping, friendlyName) {
     const nodeLabel = trimToLength(mapping?.customName, 32, "...") ?? trimToLength(friendlyName, 32, "...") ?? trimToLength(entityId, 32, "...");
     const productNameFromNodeLabel = this.featureFlags?.productNameFromNodeLabel === true ? trimToLength(sanitizeMatterString(nodeLabel ?? ""), 32, "...") ?? void 0 : void 0;
-    const rawSerial = trimToLength(mapping?.customSerialNumber, 32, "...");
-    const serialNumber = rawSerial && this.serialNumberSuffix ? trimToLength(`${rawSerial}${this.serialNumberSuffix}`, 32, "...") : rawSerial;
+    const maxRawLen = 32 - (this.serialNumberSuffix?.length ?? 0);
+    const registrySerial = this.featureFlags?.useHaRegistrySerial ? trimToLength(device?.serial_number, maxRawLen, "...") : void 0;
+    const rawSerial = trimToLength(mapping?.customSerialNumber, maxRawLen, "...") ?? registrySerial;
+    const serialNumber = rawSerial && this.serialNumberSuffix ? `${rawSerial}${this.serialNumberSuffix}` : rawSerial;
     const basicInformation = dropUndefined({
       vendorName: trimToLength(mapping?.customVendorName, 32, "...") ?? trimToLength(device?.manufacturer, 32, "..."),
       productName: trimToLength(mapping?.customProductName, 32, "...") ?? productNameFromNodeLabel ?? trimToLength(device?.model_id, 32, "...") ?? trimToLength(device?.model, 32, "..."),
@@ -166497,6 +166651,9 @@ var BridgeDataProvider = class extends Service {
   get serialNumberSuffix() {
     return this.data.serialNumberSuffix;
   }
+  get sessionMaxAgeHours() {
+    return this.data.sessionMaxAgeHours;
+  }
   /************************************************
    * Functions
    ************************************************/
@@ -166522,6 +166679,7 @@ var BridgeDataProvider = class extends Service {
       icon: this.icon,
       priority: this.priority,
       serialNumberSuffix: this.serialNumberSuffix,
+      sessionMaxAgeHours: this.sessionMaxAgeHours,
       status: status3.code,
       statusReason: status3.reason,
       commissioning: commissioning ? {
@@ -168118,6 +168276,12 @@ ${e?.toString()}`);
     if (!this.dataProvider.featureFlags?.autoForceSync) {
       return 0;
     }
+    if (isHeapUnderPressure()) {
+      this.log.warn(
+        "Force sync skipped: heap under pressure, reduce entities or raise NODE_OPTIONS=--max-old-space-size"
+      );
+      return 0;
+    }
     const { HomeAssistantEntityBehavior: HomeAssistantEntityBehavior2 } = await Promise.resolve().then(() => (init_home_assistant_entity_behavior(), home_assistant_entity_behavior_exports));
     const allEndpoints = [];
     const collect = (ep) => {
@@ -168415,10 +168579,14 @@ var BasicInformationServer2 = class extends BridgedDeviceBasicInformationServer
     const nodeLabel = ellipse(32, homeAssistant.state.customName) ?? ellipse(32, registryName) ?? ellipse(32, entity.state?.attributes?.friendly_name) ?? ellipse(32, entity.entity_id);
     const productNameFromNodeLabel = featureFlags?.productNameFromNodeLabel === true ? ellipse(32, sanitizeMatterString(nodeLabel ?? "")) ?? void 0 : void 0;
     const serialNumberSuffix = this.env.get(BridgeDataProvider).serialNumberSuffix;
-    const rawSerial = ellipse(32, mapping?.customSerialNumber) ?? hash(32, entity.entity_id);
-    const serialNumber = serialNumberSuffix ? ellipse(32, `${rawSerial}${serialNumberSuffix}`) : rawSerial;
+    const maxRawLen = 32 - (serialNumberSuffix?.length ?? 0);
+    const registrySerial = featureFlags?.useHaRegistrySerial ? ellipse(maxRawLen, device?.serial_number) : void 0;
+    const rawSerial = ellipse(maxRawLen, mapping?.customSerialNumber) ?? registrySerial ?? hash(maxRawLen, entity.entity_id);
+    const serialNumber = rawSerial && serialNumberSuffix ? `${rawSerial}${serialNumberSuffix}` : rawSerial;
+    const customVendorId = mapping?.customVendorId;
+    const vendorId3 = isValidVendorId(customVendorId) ? customVendorId : basicInformation.vendorId;
     applyPatchState(this.state, {
-      vendorId: VendorId(basicInformation.vendorId),
+      vendorId: VendorId(vendorId3),
       vendorName: ellipse(32, mapping?.customVendorName) ?? ellipse(32, device?.manufacturer) ?? hash(32, basicInformation.vendorName),
       productName: ellipse(32, mapping?.customProductName) ?? productNameFromNodeLabel ?? ellipse(32, device?.model_id) ?? ellipse(32, device?.model) ?? hash(32, basicInformation.productName),
       productLabel: ellipse(64, device?.model) ?? hash(64, basicInformation.productLabel),
@@ -168443,6 +168611,9 @@ function hash(maxLength, value) {
   const suffix = crypto6.createHash("md5").update(value ?? "").digest("hex").substring(0, hashLength);
   return trimToLength(value, maxLength, suffix);
 }
+function isValidVendorId(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65534;
+}
 
 // src/matter/behaviors/electrical-energy-measurement-server.ts
 init_esm();
@@ -168493,6 +168664,10 @@ var ElectricalEnergyMeasurementServerBase = class extends FeaturedBase {
   ElectricalEnergyMeasurementServerBase2.State = State;
 })(ElectricalEnergyMeasurementServerBase || (ElectricalEnergyMeasurementServerBase = {}));
 var HaElectricalEnergyMeasurementServer = ElectricalEnergyMeasurementServerBase.set({
+  // Match the activePower=0 default in HaElectricalPowerMeasurementServer
+  // so SmartThings doesn't show "- kWh" before the first state update or
+  // when an entity only carries power (not energy) data.
+  cumulativeEnergyImported: { energy: 0 },
   accuracy: {
     measurementType: ElectricalPowerMeasurement3.MeasurementType.ElectricalEnergy,
     measured: true,
@@ -168723,6 +168898,11 @@ var defaultBatteryConfig = {
 };
 var DefaultPowerSourceServer = PowerSourceServer2(defaultBatteryConfig);
 
+// src/matter/behaviors/power-topology-server.ts
+var HaPowerTopologyServer = PowerTopologyServer.with(
+  PowerTopology3.Feature.NodeTopology
+);
+
 // src/matter/behaviors/temperature-measurement-server.ts
 init_home_assistant_entity_behavior();
 var TemperatureMeasurementServerBase = class extends TemperatureMeasurementServer {
@@ -169826,6 +170006,9 @@ var ComposedAirPurifierEndpoint = class _ComposedAirPurifierEndpoint extends End
     if (config10.batteryEntityId) {
       parentType = parentType.with(PowerSourceServer2(batteryConfig));
     }
+    if (config10.powerEntityId || config10.energyEntityId) {
+      parentType = parentType.with(HaPowerTopologyServer);
+    }
     if (config10.powerEntityId) {
       parentType = parentType.with(HaElectricalPowerMeasurementServer);
     }
@@ -170161,6 +170344,9 @@ var ComposedSensorEndpoint = class _ComposedSensorEndpoint extends Endpoint {
     if (config10.batteryEntityId) {
       parentType = parentType.with(PowerSourceServer2(batteryConfig2));
     }
+    if (config10.powerEntityId || config10.energyEntityId) {
+      parentType = parentType.with(HaPowerTopologyServer);
+    }
     if (config10.powerEntityId) {
       parentType = parentType.with(HaElectricalPowerMeasurementServer);
     }
@@ -171791,6 +171977,7 @@ function isHeatCoolOnly(modes) {
   return modes.includes(ClimateHvacMode.heat_cool) && !modes.includes(ClimateHvacMode.heat) && !modes.includes(ClimateHvacMode.cool);
 }
 var lastHvacDirection = /* @__PURE__ */ new Map();
+var climateFreezeState = /* @__PURE__ */ new Map();
 function getHeatCoolOnlyDirection(entity, agent) {
   const action = attributes4(entity).hvac_action;
   const homeAssistant = agent.get(HomeAssistantEntityBehavior);
@@ -171805,6 +171992,95 @@ function getHeatCoolOnlyDirection(entity, agent) {
   }
   return lastHvacDirection.get(entityId) ?? "heating";
 }
+function computeSystemMode(entity, agent) {
+  const hvacMode = entity.state;
+  const systemMode = hvacModeToSystemMode[hvacMode] ?? Thermostat3.SystemMode.Off;
+  if (systemMode === Thermostat3.SystemMode.Auto) {
+    const modes = attributes4(entity).hvac_modes ?? [];
+    if (isHeatCoolOnly(modes)) {
+      const direction = getHeatCoolOnlyDirection(entity, agent);
+      return direction === "cooling" ? Thermostat3.SystemMode.Cool : Thermostat3.SystemMode.Heat;
+    }
+    const hasMatterAuto = modes.includes(ClimateHvacMode.heat_cool) && (modes.includes(ClimateHvacMode.heat) || modes.includes(ClimateHvacMode.cool));
+    if (hasMatterAuto) {
+      return systemMode;
+    }
+    const hasCooling = modes.some((m) => m === ClimateHvacMode.cool);
+    const hasHeating = modes.some(
+      (m) => m === ClimateHvacMode.heat || m === ClimateHvacMode.auto
+    );
+    if (hasHeating && !hasCooling) {
+      return Thermostat3.SystemMode.Heat;
+    }
+    if (hasCooling && !hasHeating) {
+      return Thermostat3.SystemMode.Cool;
+    }
+    const homeAssistant = agent.get(HomeAssistantEntityBehavior);
+    const entityId = homeAssistant.entityId;
+    const action = attributes4(entity).hvac_action;
+    if (action === ClimateHvacAction.cooling) {
+      lastHvacDirection.set(entityId, "cooling");
+      return Thermostat3.SystemMode.Cool;
+    }
+    if (action === ClimateHvacAction.heating) {
+      lastHvacDirection.set(entityId, "heating");
+      return Thermostat3.SystemMode.Heat;
+    }
+    const remembered = lastHvacDirection.get(entityId);
+    if (remembered) {
+      return remembered === "cooling" ? Thermostat3.SystemMode.Cool : Thermostat3.SystemMode.Heat;
+    }
+    const current = attributes4(entity).current_temperature;
+    const target = attributes4(entity).temperature;
+    if (typeof current === "number" && typeof target === "number") {
+      if (current > target) {
+        lastHvacDirection.set(entityId, "cooling");
+        return Thermostat3.SystemMode.Cool;
+      }
+      if (current < target) {
+        lastHvacDirection.set(entityId, "heating");
+        return Thermostat3.SystemMode.Heat;
+      }
+    }
+    return Thermostat3.SystemMode.Cool;
+  }
+  return systemMode;
+}
+function applyClimateFreezeForKeepModeOnIdle(computed, entity, entityId, keepModeOnIdle) {
+  if (computed !== Thermostat3.SystemMode.Off) {
+    const existing2 = climateFreezeState.get(entityId);
+    if (existing2) {
+      existing2.lastNonOffMode = computed;
+      existing2.pending = true;
+      existing2.confirmedOff = false;
+    } else {
+      climateFreezeState.set(entityId, {
+        lastNonOffMode: computed,
+        pending: true,
+        confirmedOff: false
+      });
+    }
+    return computed;
+  }
+  const action = attributes4(entity).hvac_action;
+  const existing = climateFreezeState.get(entityId);
+  if (action === ClimateHvacAction.off) {
+    if (existing) {
+      if (existing.confirmedOff) {
+        existing.pending = false;
+        existing.confirmedOff = false;
+      } else {
+        existing.confirmedOff = true;
+      }
+    }
+  } else if (existing) {
+    existing.confirmedOff = false;
+  }
+  if (keepModeOnIdle && existing?.pending) {
+    return existing.lastNonOffMode;
+  }
+  return computed;
+}
 var config4 = {
   // Temperature range (target_temp_low/high) only works in heat_cool mode.
   // In heat or cool mode, HA expects a single "temperature" value.
@@ -171824,58 +172100,14 @@ var config4 = {
   getTargetHeatingTemperature: (entity, agent) => getTemp(agent, entity, "target_temp_low") ?? getTemp(agent, entity, "target_temperature") ?? getTemp(agent, entity, "temperature"),
   getTargetCoolingTemperature: (entity, agent) => getTemp(agent, entity, "target_temp_high") ?? getTemp(agent, entity, "target_temperature") ?? getTemp(agent, entity, "temperature"),
   getSystemMode: (entity, agent) => {
-    const hvacMode = entity.state;
-    const systemMode = hvacModeToSystemMode[hvacMode] ?? Thermostat3.SystemMode.Off;
-    if (systemMode === Thermostat3.SystemMode.Auto) {
-      const modes = attributes4(entity).hvac_modes ?? [];
-      if (isHeatCoolOnly(modes)) {
-        const direction = getHeatCoolOnlyDirection(entity, agent);
-        return direction === "cooling" ? Thermostat3.SystemMode.Cool : Thermostat3.SystemMode.Heat;
-      }
-      const hasMatterAuto = modes.includes(ClimateHvacMode.heat_cool) && (modes.includes(ClimateHvacMode.heat) || modes.includes(ClimateHvacMode.cool));
-      if (hasMatterAuto) {
-        return systemMode;
-      }
-      const hasCooling = modes.some((m) => m === ClimateHvacMode.cool);
-      const hasHeating = modes.some(
-        (m) => m === ClimateHvacMode.heat || m === ClimateHvacMode.auto
-      );
-      if (hasHeating && !hasCooling) {
-        return Thermostat3.SystemMode.Heat;
-      }
-      if (hasCooling && !hasHeating) {
-        return Thermostat3.SystemMode.Cool;
-      }
-      const homeAssistant = agent.get(HomeAssistantEntityBehavior);
-      const entityId = homeAssistant.entityId;
-      const action = attributes4(entity).hvac_action;
-      if (action === ClimateHvacAction.cooling) {
-        lastHvacDirection.set(entityId, "cooling");
-        return Thermostat3.SystemMode.Cool;
-      }
-      if (action === ClimateHvacAction.heating) {
-        lastHvacDirection.set(entityId, "heating");
-        return Thermostat3.SystemMode.Heat;
-      }
-      const remembered = lastHvacDirection.get(entityId);
-      if (remembered) {
-        return remembered === "cooling" ? Thermostat3.SystemMode.Cool : Thermostat3.SystemMode.Heat;
-      }
-      const current = attributes4(entity).current_temperature;
-      const target = attributes4(entity).temperature;
-      if (typeof current === "number" && typeof target === "number") {
-        if (current > target) {
-          lastHvacDirection.set(entityId, "cooling");
-          return Thermostat3.SystemMode.Cool;
-        }
-        if (current < target) {
-          lastHvacDirection.set(entityId, "heating");
-          return Thermostat3.SystemMode.Heat;
-        }
-      }
-      return Thermostat3.SystemMode.Cool;
-    }
-    return systemMode;
+    const homeAssistant = agent.get(HomeAssistantEntityBehavior);
+    const computed = computeSystemMode(entity, agent);
+    return applyClimateFreezeForKeepModeOnIdle(
+      computed,
+      entity,
+      homeAssistant.entityId,
+      homeAssistant.state.mapping?.climateKeepModeOnIdle === true
+    );
   },
   getRunningMode: (entity) => {
     const action = attributes4(entity).hvac_action;
@@ -172138,6 +172370,18 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
   static DEBOUNCE_INITIAL_MS = 400;
   static DEBOUNCE_SUBSEQUENT_MS = 150;
   static COMMAND_SEQUENCE_THRESHOLD_MS = 600;
+  // Per-entity override wins over per-bridge flag; both must be > 0 to count.
+  resolveDebounceOverride(homeAssistant) {
+    const fromEntity = homeAssistant.state.mapping?.coverSliderDebounceMs;
+    if (typeof fromEntity === "number" && fromEntity > 0) {
+      return fromEntity;
+    }
+    const fromBridge = this.env.get(BridgeDataProvider).featureFlags?.coverSliderDebounceMs;
+    if (typeof fromBridge === "number" && fromBridge > 0) {
+      return fromBridge;
+    }
+    return null;
+  }
   async [Symbol.asyncDispose]() {
     if (this.liftDebounceTimer) {
       clearTimeout(this.liftDebounceTimer);
@@ -172152,23 +172396,9 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
     await super[Symbol.asyncDispose]();
   }
   async initialize() {
-    if (this.features.lift) {
-      if (this.state.installedOpenLimitLift == null) {
-        this.state.installedOpenLimitLift = 0;
-      }
-      if (this.state.installedClosedLimitLift == null) {
-        this.state.installedClosedLimitLift = 1e4;
-      }
-    }
-    if (this.features.tilt) {
-      if (this.state.installedOpenLimitTilt == null) {
-        this.state.installedOpenLimitTilt = 0;
-      }
-      if (this.state.installedClosedLimitTilt == null) {
-        this.state.installedClosedLimitTilt = 1e4;
-      }
-    }
+    this.internal.disableOperationalModeHandling = true;
     if (this.features.positionAwareLift) {
+      this.state.currentPositionLiftPercentage = void 0;
       if (this.state.currentPositionLiftPercent100ths === void 0) {
         this.state.currentPositionLiftPercent100ths = null;
       }
@@ -172177,6 +172407,7 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
       }
     }
     if (this.features.positionAwareTilt) {
+      this.state.currentPositionTiltPercentage = void 0;
       if (this.state.currentPositionTiltPercent100ths === void 0) {
         this.state.currentPositionTiltPercent100ths = null;
       }
@@ -172233,41 +172464,39 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
     );
     const overrideType = config10.getCoverType?.(state, this.agent);
     const overrideEndProduct = config10.getEndProductType?.(state, this.agent);
+    const previousStatus = this.state.operationalStatus?.global;
+    const startedMoving = !isStopped && previousStatus === MovementStatus.Stopped;
     const appliedPatch = applyPatchState(
       this.state,
       {
         type: overrideType ?? (this.features.lift && this.features.tilt ? WindowCovering3.WindowCoveringType.TiltBlindLift : this.features.tilt ? WindowCovering3.WindowCoveringType.TiltBlindTiltOnly : WindowCovering3.WindowCoveringType.Rollershade),
         endProductType: overrideEndProduct ?? (this.features.lift && this.features.tilt ? WindowCovering3.EndProductType.SheerShade : this.features.tilt ? WindowCovering3.EndProductType.TiltOnlyInteriorBlind : WindowCovering3.EndProductType.RollerShade),
-        operationalStatus: {
-          global: movementStatus,
-          ...this.features.lift ? { lift: movementStatus } : {},
-          ...this.features.tilt ? { tilt: movementStatus } : {}
-        },
-        ...this.features.absolutePosition && this.features.lift ? {
-          installedOpenLimitLift: 0,
-          installedClosedLimitLift: 1e4,
-          currentPositionLift: currentLift100ths
-        } : {},
-        ...this.features.absolutePosition && this.features.tilt ? {
-          installedOpenLimitTilt: 0,
-          installedClosedLimitTilt: 1e4,
-          currentPositionTilt: currentTilt100ths
-        } : {},
+        // Target before operationalStatus so the wire order matches the
+        // certified Eve MotionBlinds (state, target, current). Patch insertion
+        // order propagates into matter.js's changeList via for-in over values
+        // (Datasource.js:414), then through attrsChanged.emit (#328).
         ...this.features.positionAwareLift ? {
-          currentPositionLiftPercentage: currentLift,
-          currentPositionLiftPercent100ths: currentLift100ths,
           targetPositionLiftPercent100ths: inferTarget(
             currentLift100ths,
             this.state.targetPositionLiftPercent100ths
           )
         } : {},
         ...this.features.positionAwareTilt ? {
-          currentPositionTiltPercentage: currentTilt,
-          currentPositionTiltPercent100ths: currentTilt100ths,
           targetPositionTiltPercent100ths: inferTarget(
             currentTilt100ths,
             this.state.targetPositionTiltPercent100ths
           )
+        } : {},
+        operationalStatus: {
+          global: movementStatus,
+          ...this.features.lift ? { lift: movementStatus } : {},
+          ...this.features.tilt ? { tilt: movementStatus } : {}
+        },
+        ...this.features.positionAwareLift && !startedMoving ? {
+          currentPositionLiftPercent100ths: currentLift100ths
+        } : {},
+        ...this.features.positionAwareTilt && !startedMoving ? {
+          currentPositionTiltPercent100ths: currentTilt100ths
         } : {}
       }
     );
@@ -172284,7 +172513,7 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
     const currentLift = this.state.currentPositionLiftPercent100ths ?? 0;
     const currentTilt = this.state.currentPositionTiltPercent100ths ?? 0;
     logger179.info(
-      `handleMovement: type=${MovementType[type]}, direction=${MovementDirection[direction]}, target=${targetPercent100ths}, currentLift=${currentLift}, currentTilt=${currentTilt}, absolutePosition=${this.features.absolutePosition}`
+      `handleMovement: type=${MovementType[type]}, direction=${MovementDirection[direction]}, target=${targetPercent100ths}, currentLift=${currentLift}, currentTilt=${currentTilt}`
     );
     if (type === MovementType.Lift) {
       this.lastLiftMovementMs = Date.now();
@@ -172293,7 +172522,7 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
         this.handleLiftOpen();
       } else if (targetPercent100ths === 1e4) {
         this.handleLiftClose();
-      } else if (targetPercent100ths != null && this.features.absolutePosition) {
+      } else if (targetPercent100ths != null && this.features.positionAwareLift) {
         this.handleGoToLiftPosition(targetPercent100ths);
       } else if (direction === MovementDirection.Open) {
         this.handleLiftOpen();
@@ -172311,7 +172540,7 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
         this.handleTiltOpen();
       } else if (targetPercent100ths === 1e4) {
         this.handleTiltClose();
-      } else if (targetPercent100ths != null && this.features.absolutePosition) {
+      } else if (targetPercent100ths != null && this.features.positionAwareTilt) {
         this.handleGoToTiltPosition(targetPercent100ths);
       } else if (direction === MovementDirection.Open) {
         this.handleTiltOpen();
@@ -172353,9 +172582,10 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
     const timeSinceLastCommand = now - this.lastLiftCommandTime;
     this.lastLiftCommandTime = now;
     const isFirstInSequence = timeSinceLastCommand > _WindowCoveringServerBase.COMMAND_SEQUENCE_THRESHOLD_MS;
-    const debounceMs = isFirstInSequence ? _WindowCoveringServerBase.DEBOUNCE_INITIAL_MS : _WindowCoveringServerBase.DEBOUNCE_SUBSEQUENT_MS;
+    const overrideMs = this.resolveDebounceOverride(homeAssistant);
+    const debounceMs = overrideMs != null ? overrideMs : isFirstInSequence ? _WindowCoveringServerBase.DEBOUNCE_INITIAL_MS : _WindowCoveringServerBase.DEBOUNCE_SUBSEQUENT_MS;
     logger179.debug(
-      `Lift command: target=${targetPosition}%, debounce=${debounceMs}ms (${isFirstInSequence ? "initial" : "subsequent"})`
+      `Lift command: target=${targetPosition}%, debounce=${debounceMs}ms (${overrideMs != null ? "override" : isFirstInSequence ? "initial" : "subsequent"})`
     );
     if (this.liftDebounceTimer) {
       clearTimeout(this.liftDebounceTimer);
@@ -172402,9 +172632,10 @@ var WindowCoveringServerBase = class _WindowCoveringServerBase extends FeaturedB
     const timeSinceLastCommand = now - this.lastTiltCommandTime;
     this.lastTiltCommandTime = now;
     const isFirstInSequence = timeSinceLastCommand > _WindowCoveringServerBase.COMMAND_SEQUENCE_THRESHOLD_MS;
-    const debounceMs = isFirstInSequence ? _WindowCoveringServerBase.DEBOUNCE_INITIAL_MS : _WindowCoveringServerBase.DEBOUNCE_SUBSEQUENT_MS;
+    const overrideMs = this.resolveDebounceOverride(homeAssistant);
+    const debounceMs = overrideMs != null ? overrideMs : isFirstInSequence ? _WindowCoveringServerBase.DEBOUNCE_INITIAL_MS : _WindowCoveringServerBase.DEBOUNCE_SUBSEQUENT_MS;
     logger179.debug(
-      `Tilt command: target=${targetPosition}%, debounce=${debounceMs}ms (${isFirstInSequence ? "initial" : "subsequent"})`
+      `Tilt command: target=${targetPosition}%, debounce=${debounceMs}ms (${overrideMs != null ? "override" : isFirstInSequence ? "initial" : "subsequent"})`
     );
     if (this.tiltDebounceTimer) {
       clearTimeout(this.tiltDebounceTimer);
@@ -172478,12 +172709,13 @@ var DEVICE_CLASS_TO_MATTER_TYPE = {
     type: WindowCovering3.WindowCoveringType.Rollershade,
     endProductType: WindowCovering3.EndProductType.RollerShade
   },
-  // Velux-style motorized roof/casement windows. There's no Matter
-  // WindowCoveringType for "window", so we map to lift-only Rollershade
-  // and use Unknown end-product to avoid implying a specific physical form.
+  // Velux-style motorized roof/casement windows. No Matter WindowCoveringType
+  // for "window", so map to Rollershade + RollerShade (the spec default pair).
+  // EndProductType is a FixedAttribute, and Alexa's routine picker drops
+  // devices it can't categorize - Unknown (255) lands there (#312).
   window: {
     type: WindowCovering3.WindowCoveringType.Rollershade,
-    endProductType: WindowCovering3.EndProductType.Unknown
+    endProductType: WindowCovering3.EndProductType.RollerShade
   }
 };
 var deviceClassMapping = (entity) => {
@@ -172636,24 +172868,17 @@ var CoverWindowCoveringServer = WindowCoveringServer2(config5);
 
 // src/matter/endpoints/legacy/cover/index.ts
 var logger181 = Logger.get("CoverDevice");
-var DISCRETE_COVER_CLASSES = /* @__PURE__ */ new Set(["garage", "gate"]);
-var CoverDeviceType = (supportedFeatures, hasBattery, entityId, isDiscrete) => {
+var CoverDeviceType = (supportedFeatures, hasBattery, entityId) => {
   const features2 = /* @__PURE__ */ new Set();
   if (testBit(supportedFeatures, CoverSupportedFeatures.support_open)) {
     features2.add("Lift");
     features2.add("PositionAwareLift");
-    if (!isDiscrete) {
-      features2.add("AbsolutePosition");
-    }
   } else {
     logger181.warn(
       `[${entityId}] Cover has no support_open feature (supported_features=${supportedFeatures}), adding Lift anyway`
     );
     features2.add("Lift");
     features2.add("PositionAwareLift");
-    if (!isDiscrete) {
-      features2.add("AbsolutePosition");
-    }
   }
   if (testBit(supportedFeatures, CoverSupportedFeatures.support_open_tilt)) {
     features2.add("Tilt");
@@ -172662,7 +172887,6 @@ var CoverDeviceType = (supportedFeatures, hasBattery, entityId, isDiscrete) => {
       CoverSupportedFeatures.support_set_tilt_position
     )) {
       features2.add("PositionAwareTilt");
-      features2.add("AbsolutePosition");
     }
   }
   logger181.info(
@@ -172697,18 +172921,10 @@ function CoverDevice(homeAssistantEntity) {
       `[${entityId}] Creating cover without battery (batteryAttr=${hasBatteryAttr}, batteryEntity=${homeAssistantEntity.mapping?.batteryEntity ?? "none"})`
     );
   }
-  const deviceClass = attributes7.device_class;
-  const isDiscrete = typeof deviceClass === "string" && DISCRETE_COVER_CLASSES.has(deviceClass.toLowerCase());
-  if (isDiscrete) {
-    logger181.info(
-      `[${entityId}] Garage/gate cover (device_class=${deviceClass}): using discrete Open/Close mode`
-    );
-  }
   return CoverDeviceType(
     attributes7.supported_features ?? 0,
     hasBattery,
-    entityId,
-    isDiscrete
+    entityId
   ).set({
     homeAssistantEntity
   });
@@ -173775,6 +173991,9 @@ function LightDevice(homeAssistantEntity) {
   const hasPowerEntity = !!homeAssistantEntity.mapping?.powerEntity;
   const hasEnergyEntity = !!homeAssistantEntity.mapping?.energyEntity;
   let device = deviceType;
+  if (hasPowerEntity || hasEnergyEntity) {
+    device = device.with(HaPowerTopologyServer);
+  }
   if (hasPowerEntity) {
     device = device.with(HaElectricalPowerMeasurementServer);
   }
@@ -175300,6 +175519,10 @@ var StandalonePowerServer = class extends ElectricalPowerMeasurementServer {
 var PowerServer = StandalonePowerServer.set({
   powerMode: ElectricalPowerMeasurement3.PowerMode.Ac,
   numberOfMeasurementTypes: 1,
+  // SmartThings keeps the endpoint in a "device not yet updated" state
+  // when activePower stays null. Seed 0 so the cluster reports a value
+  // for energy/voltage/current-only sensors that never feed activePower.
+  activePower: 0,
   accuracy: [
     {
       measurementType: ElectricalPowerMeasurement3.MeasurementType.ActivePower,
@@ -175352,6 +175575,9 @@ var StandaloneEnergyServer = class extends EnergyFeaturedBase {
   StandaloneEnergyServer2.State = State;
 })(StandaloneEnergyServer || (StandaloneEnergyServer = {}));
 var EnergyServer = StandaloneEnergyServer.set({
+  // Match the activePower=0 default so SmartThings doesn't show "- kWh"
+  // on a SolarPower endpoint whose mapped entity only carries power data.
+  cumulativeEnergyImported: { energy: 0 },
   accuracy: {
     measurementType: ElectricalPowerMeasurement3.MeasurementType.ElectricalEnergy,
     measured: true,
@@ -175370,6 +175596,7 @@ var ElectricalSensorType = SolarPowerDevice.with(
   BasicInformationServer2,
   IdentifyServer2,
   HomeAssistantEntityBehavior,
+  HaPowerTopologyServer,
   PowerServer,
   EnergyServer
 );
@@ -176812,6 +177039,9 @@ function SwitchDevice(homeAssistantEntity) {
   const hasPowerEntity = !!homeAssistantEntity.mapping?.powerEntity;
   const hasEnergyEntity = !!homeAssistantEntity.mapping?.energyEntity;
   let device = hasBatteryAttr || hasBatteryEntity ? SwitchWithBatteryEndpointType : SwitchEndpointType;
+  if (hasPowerEntity || hasEnergyEntity) {
+    device = device.with(HaPowerTopologyServer);
+  }
   if (hasPowerEntity) {
     device = device.with(HaElectricalPowerMeasurementServer);
   }
@@ -176907,7 +177137,9 @@ function getSession(endpoint) {
       completedAreas: /* @__PURE__ */ new Set(),
       lastCurrentArea: null,
       activeAreas: [],
-      loggedShortCircuits: /* @__PURE__ */ new Set()
+      loggedShortCircuits: /* @__PURE__ */ new Set(),
+      observedCleaning: false,
+      pendingDispatches: []
     };
     cleaningSessions.set(endpoint, session);
   }
@@ -176938,17 +177170,45 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
       },
       { force: true }
     );
+    if (newMode === 1 /* Cleaning */) {
+      s.observedCleaning = true;
+    }
     if (previousMode !== newMode) {
       if (newMode === 0 /* Idle */) {
         if (s.lastCurrentArea !== null) {
           s.completedAreas.add(s.lastCurrentArea);
           s.lastCurrentArea = null;
+        }
+        if (s.pendingDispatches.length > 0 && s.observedCleaning) {
           try {
             const serviceArea = this.agent.get(ServiceAreaBehavior);
-            serviceArea.state.currentArea = null;
+            const prev = serviceArea.state.currentArea;
+            if (typeof prev === "number") {
+              s.completedAreas.add(prev);
+            }
+            const next = s.pendingDispatches.shift();
+            if (next) {
+              const homeAssistant = this.agent.get(HomeAssistantEntityBehavior);
+              homeAssistant.callAction(next.action);
+              this.trySetCurrentArea(next.areaId);
+            }
+          } catch {
+          }
+          s.loggedShortCircuits.clear();
+          return;
+        }
+        if (s.observedCleaning) {
+          try {
+            const serviceArea = this.agent.get(ServiceAreaBehavior);
+            const last = serviceArea.state.currentArea;
+            if (typeof last === "number") {
+              s.completedAreas.add(last);
+              serviceArea.state.currentArea = null;
+            }
             this.updateProgressFromTracking(serviceArea);
           } catch {
           }
+          s.observedCleaning = false;
         }
         s.loggedShortCircuits.clear();
       } else if (newMode === 1 /* Cleaning */) {
@@ -176962,6 +177222,15 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
         }
       }
     }
+    if (newMode === 0 /* Idle */ && s.activeAreas.length === 0) {
+      try {
+        const serviceArea = this.agent.get(ServiceAreaBehavior);
+        if (serviceArea.state.currentArea !== null) {
+          serviceArea.state.currentArea = null;
+        }
+      } catch {
+      }
+    }
     if (newMode === 1 /* Cleaning */) {
       this.updateCurrentRoomFromSensor();
     }
@@ -177146,6 +177415,7 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
           s.completedAreas.clear();
           s.lastCurrentArea = null;
           s.loggedShortCircuits.clear();
+          s.pendingDispatches = [];
           this.trySetCurrentArea(s.activeAreas[0]);
           homeAssistant.callAction(this.state.config.start(void 0, this.agent));
           this.state.currentMode = newMode;
@@ -177162,6 +177432,7 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
         s.completedAreas.clear();
         s.lastCurrentArea = null;
         s.loggedShortCircuits.clear();
+        s.pendingDispatches = [];
         this.trySetCurrentArea(areaId);
         homeAssistant.callAction(
           this.state.config.cleanRoom(newMode, this.agent)
@@ -177182,6 +177453,7 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
             s.completedAreas.clear();
             s.lastCurrentArea = null;
             s.loggedShortCircuits.clear();
+            s.pendingDispatches = [];
             this.trySetCurrentArea(s.activeAreas[0]);
           }
         } catch {
@@ -177195,6 +177467,8 @@ var RvcRunModeServerBase = class extends RvcRunModeServer {
         s.lastCurrentArea = null;
         s.activeAreas = [];
         s.loggedShortCircuits.clear();
+        s.pendingDispatches = [];
+        s.observedCleaning = false;
         homeAssistant.callAction(
           this.state.config.returnToBase(void 0, this.agent)
         );
@@ -177771,8 +178045,8 @@ function buildSupportedModes2(attributes7, includeUnnamedRooms = false, customAr
   }
   return modes;
 }
-function handleCustomServiceAreas(selectedAreas, customAreas, homeAssistant) {
-  const matched = selectedAreas.map((areaId) => customAreas[areaId - 1]).filter(Boolean);
+function handleCustomServiceAreas(selectedAreas, customAreas, session) {
+  const matched = selectedAreas.map((areaId) => ({ areaId, area: customAreas[areaId - 1] })).filter((m) => !!m.area);
   if (matched.length === 0) {
     logger194.warn(
       `Custom service areas: no match for selected IDs ${selectedAreas.join(", ")}`
@@ -177780,17 +178054,13 @@ function handleCustomServiceAreas(selectedAreas, customAreas, homeAssistant) {
     return { action: "vacuum.start" };
   }
   logger194.info(
-    `Custom service areas: calling ${matched.length} service(s): ${matched.map((a) => `${a.service} (${a.name})`).join(", ")}`
+    `Custom service areas: ${matched.length} room(s) queued: ${matched.map(({ area }) => `${area.service} (${area.name})`).join(", ")}`
   );
-  for (let i = 1; i < matched.length; i++) {
-    const area = matched[i];
-    homeAssistant.callAction({
-      action: area.service,
-      target: area.target,
-      data: area.data
-    });
-  }
-  const first = matched[0];
+  session.pendingDispatches = matched.slice(1).map(({ areaId, area }) => ({
+    areaId,
+    action: { action: area.service, target: area.target, data: area.data }
+  }));
+  const first = matched[0].area;
   return {
     action: first.service,
     target: first.target,
@@ -177824,9 +178094,14 @@ var vacuumRvcRunModeConfig = {
     );
     return isCleaning ? 1 /* Cleaning */ : 0 /* Idle */;
   },
-  getSupportedModes: (entity) => {
+  getSupportedModes: (entity, agent) => {
     const attributes7 = entity.attributes;
-    return buildSupportedModes2(attributes7);
+    const customAreas = agent.get(HomeAssistantEntityBehavior).state.mapping?.customServiceAreas;
+    return buildSupportedModes2(
+      attributes7,
+      false,
+      customAreas && customAreas.length > 0 ? customAreas : void 0
+    );
   },
   // biome-ignore lint/suspicious/noConfusingVoidType: Required by ValueSetter<void> interface
   start: (_, agent) => {
@@ -177837,13 +178112,10 @@ var vacuumRvcRunModeConfig = {
         const homeAssistant = agent.get(HomeAssistantEntityBehavior);
         const entity = homeAssistant.entity;
         const attributes7 = entity.state.attributes;
+        const session = getSession(homeAssistant.endpoint);
         const customAreas = homeAssistant.state.mapping?.customServiceAreas;
         if (customAreas && customAreas.length > 0) {
-          return handleCustomServiceAreas(
-            selectedAreas,
-            customAreas,
-            homeAssistant
-          );
+          return handleCustomServiceAreas(selectedAreas, customAreas, session);
         }
         const cleanAreaRooms = homeAssistant.state.mapping?.cleanAreaRooms;
         if (cleanAreaRooms && cleanAreaRooms.length > 0) {
@@ -177860,28 +178132,24 @@ var vacuumRvcRunModeConfig = {
         }
         const roomEntities = homeAssistant.state.mapping?.roomEntities;
         if (roomEntities && roomEntities.length > 0) {
-          const buttonEntityIds = [];
+          const matched = [];
           for (const areaId of selectedAreas) {
-            const buttonEntityId = roomEntities.find(
-              (id) => toAreaId(id) === areaId
-            );
-            if (buttonEntityId) {
-              buttonEntityIds.push(buttonEntityId);
+            const entityId = roomEntities.find((id) => toAreaId(id) === areaId);
+            if (entityId) {
+              matched.push({ areaId, entityId });
             }
           }
-          if (buttonEntityIds.length > 0) {
+          if (matched.length > 0) {
             logger194.info(
-              `Roborock: Pressing button entities for selected rooms: ${buttonEntityIds.join(", ")}`
+              `Roborock: ${matched.length} room button(s) queued: ${matched.map((m) => m.entityId).join(", ")}`
             );
-            for (let i = 1; i < buttonEntityIds.length; i++) {
-              homeAssistant.callAction({
-                action: "button.press",
-                target: buttonEntityIds[i]
-              });
-            }
+            session.pendingDispatches = matched.slice(1).map(({ areaId, entityId }) => ({
+              areaId,
+              action: { action: "button.press", target: entityId }
+            }));
             return {
               action: "button.press",
-              target: buttonEntityIds[0]
+              target: matched[0].entityId
             };
           }
         }
@@ -178218,7 +178486,7 @@ var RvcCleanModeServerBase = class _RvcCleanModeServerBase extends RvcCleanModeS
     await super.initialize();
     const homeAssistant = await this.agent.load(HomeAssistantEntityBehavior);
     this.update(homeAssistant.entity);
-    this.reactTo(homeAssistant.onChange, this.update);
+    this.reactTo(homeAssistant.onChange, this.update, { offline: true });
   }
   update(entity) {
     if (!entity.state || !entity.state.attributes) {
@@ -178237,13 +178505,17 @@ var RvcCleanModeServerBase = class _RvcCleanModeServerBase extends RvcCleanModeS
         currentMode = this.pendingMode;
       }
     }
-    applyPatchState(this.state, {
-      currentMode,
-      supportedModes: this.state.config.getSupportedModes(
-        entity.state,
-        this.agent
-      )
-    });
+    applyPatchState(
+      this.state,
+      {
+        currentMode,
+        supportedModes: this.state.config.getSupportedModes(
+          entity.state,
+          this.agent
+        )
+      },
+      { force: true }
+    );
   }
   changeToMode(request) {
     const homeAssistant = this.agent.get(HomeAssistantEntityBehavior);
@@ -179046,58 +179318,65 @@ function RvcOperationalStateServer2(config10) {
 var logger198 = Logger.get("VacuumRvcOperationalStateServer");
 function isCharging(entity) {
   const attrs = entity.attributes;
-  if (attrs.battery_icon?.includes("charging")) return true;
   if (attrs.is_charging === true || attrs.charging === true) return true;
+  if (attrs.is_charging === false || attrs.charging === false) return false;
+  const raw = attrs.battery_level ?? attrs.battery;
+  const level = typeof raw === "number" ? raw : Number.parseFloat(String(raw ?? ""));
+  if (Number.isFinite(level) && level >= 100) return false;
+  if (attrs.battery_icon?.includes("charging")) return true;
   if (typeof attrs.status === "string" && attrs.status.toLowerCase().includes("charg"))
     return true;
   return false;
 }
-var VacuumRvcOperationalStateServer = RvcOperationalStateServer2({
-  getOperationalState(entity) {
-    const state = entity.state;
-    const cleaningStates = [
-      VacuumState.cleaning,
-      VacuumState.segment_cleaning,
-      VacuumState.zone_cleaning,
-      VacuumState.spot_cleaning,
-      VacuumState.mop_cleaning
-    ];
-    let operationalState;
-    if (state === VacuumState.docked) {
-      if (isCharging(entity)) {
-        operationalState = RvcOperationalState3.OperationalState.Charging;
-      } else {
-        operationalState = RvcOperationalState3.OperationalState.Docked;
-      }
-    } else if (state === VacuumState.returning) {
-      operationalState = RvcOperationalState3.OperationalState.SeekingCharger;
-    } else if (cleaningStates.includes(state)) {
+function mapVacuumOperationalState(entity) {
+  const state = entity.state;
+  const cleaningStates = [
+    VacuumState.cleaning,
+    VacuumState.segment_cleaning,
+    VacuumState.zone_cleaning,
+    VacuumState.spot_cleaning,
+    VacuumState.mop_cleaning
+  ];
+  let operationalState;
+  if (state === VacuumState.docked) {
+    if (isCharging(entity)) {
+      operationalState = RvcOperationalState3.OperationalState.Charging;
+    } else {
+      operationalState = RvcOperationalState3.OperationalState.Docked;
+    }
+  } else if (state === VacuumState.returning) {
+    operationalState = RvcOperationalState3.OperationalState.SeekingCharger;
+  } else if (cleaningStates.includes(state)) {
+    operationalState = RvcOperationalState3.OperationalState.Running;
+  } else if (state === VacuumState.paused) {
+    operationalState = RvcOperationalState3.OperationalState.Paused;
+  } else if (state === VacuumState.idle) {
+    if (isCharging(entity)) {
+      operationalState = RvcOperationalState3.OperationalState.Charging;
+    } else {
+      operationalState = RvcOperationalState3.OperationalState.Stopped;
+    }
+  } else if (state === VacuumState.error || state === "unavailable") {
+    operationalState = RvcOperationalState3.OperationalState.Error;
+  } else {
+    if (state.toLowerCase().includes("clean")) {
+      logger198.info(
+        `Unknown vacuum state "${state}" contains 'clean', treating as Running`
+      );
       operationalState = RvcOperationalState3.OperationalState.Running;
-    } else if (state === VacuumState.paused) {
-      operationalState = RvcOperationalState3.OperationalState.Paused;
-    } else if (state === VacuumState.idle) {
-      if (isCharging(entity)) {
-        operationalState = RvcOperationalState3.OperationalState.Charging;
-      } else {
-        operationalState = RvcOperationalState3.OperationalState.Stopped;
-      }
-    } else if (state === VacuumState.error || state === "unavailable") {
-      operationalState = RvcOperationalState3.OperationalState.Error;
     } else {
-      if (state.toLowerCase().includes("clean")) {
-        logger198.info(
-          `Unknown vacuum state "${state}" contains 'clean', treating as Running`
-        );
-        operationalState = RvcOperationalState3.OperationalState.Running;
-      } else {
-        logger198.info(`Unknown vacuum state "${state}", treating as Stopped`);
-        operationalState = RvcOperationalState3.OperationalState.Stopped;
-      }
+      logger198.info(`Unknown vacuum state "${state}", treating as Stopped`);
+      operationalState = RvcOperationalState3.OperationalState.Stopped;
     }
-    logger198.debug(
-      `Vacuum operationalState: "${state}" -> ${RvcOperationalState3.OperationalState[operationalState]}`
-    );
-    return operationalState;
+  }
+  logger198.debug(
+    `Vacuum operationalState: "${state}" -> ${RvcOperationalState3.OperationalState[operationalState]}`
+  );
+  return operationalState;
+}
+var VacuumRvcOperationalStateServer = RvcOperationalStateServer2({
+  getOperationalState(entity) {
+    return mapVacuumOperationalState(entity);
   },
   pause: (_, agent) => {
     const supportedFeatures = agent.get(HomeAssistantEntityBehavior).entity.state.attributes.supported_features ?? 0;
@@ -181561,6 +181840,19 @@ init_dist();
 init_diagnostic_event_bus();
 var AUTO_FORCE_SYNC_INTERVAL_MS2 = 9e4;
 var DEAD_SESSION_TIMEOUT_MS2 = 6e4;
+var DEFAULT_SESSION_MAX_AGE_HOURS = 4;
+var SESSION_MAX_AGE_HOURS_RANGE = { min: 1, max: 168 };
+var ROTATION_CHECK_INTERVAL_MS = 5 * 60 * 1e3;
+function parseSessionMaxAgeHours(raw) {
+  if (raw == null || raw === "") return DEFAULT_SESSION_MAX_AGE_HOURS;
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0) return null;
+  if (n === 0) return 0;
+  const { min, max } = SESSION_MAX_AGE_HOURS_RANGE;
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
 var ServerModeBridge = class {
   constructor(logger207, dataProvider, endpointManager, server) {
     this.dataProvider = dataProvider;
@@ -181583,6 +181875,10 @@ var ServerModeBridge = class {
   deadSessionTimer = null;
   staleSessionTimers = /* @__PURE__ */ new Map();
   warmStartTimer = null;
+  // Tracks when each session opened, used for age-based rotation (#287).
+  sessionStartedAt = /* @__PURE__ */ new Map();
+  rotationTimer = null;
+  maxSessionAgeMs = 0;
   // Tracks the last synced state JSON per entity to avoid pushing unchanged states.
   lastSyncedState;
   // Session lifecycle diagnostic handlers (non-destructive, logging only).
@@ -181667,6 +181963,7 @@ var ServerModeBridge = class {
         });
       }
       this.wireSessionDiagnostics();
+      this.startSessionRotation();
       this.scheduleWarmStart();
       logMemoryUsage(this.log, "server mode bridge running");
       this.log.info("Server mode bridge started");
@@ -181682,6 +181979,7 @@ ${e?.toString()}`);
     }
   }
   async stop(code = BridgeStatus.Stopped, reason = "Manually stopped") {
+    this.stopSessionRotation();
     this.unwireSessionDiagnostics();
     this.cancelWarmStart();
     this.stopAutoForceSync();
@@ -181710,6 +182008,7 @@ ${e?.toString()}`);
       await this.refreshDevices();
       if (this.status.code === BridgeStatus.Running) {
         this.startAutoForceSyncIfEnabled();
+        this.startSessionRotation();
       }
     } catch (e) {
       const reason = "Failed to update server mode bridge due to error:";
@@ -181799,6 +182098,7 @@ ${e?.toString()}`);
       };
       sessionManager.subscriptionsChanged.on(this.sessionDiagHandler);
       this.sessionAddedHandler = (newSession) => {
+        this.sessionStartedAt.set(newSession.id, Date.now());
         this.log.info(
           `Session opened: id=${newSession.id} peer=${newSession.peerNodeId}`
         );
@@ -181813,6 +182113,7 @@ ${e?.toString()}`);
         }
       };
       this.sessionDeletedHandler = (session) => {
+        this.sessionStartedAt.delete(session.id);
         const sessions = [...sessionManager.sessions];
         this.log.warn(
           `Session closed: id=${session.id} peer=${session.peerNodeId} | remaining sessions=${sessions.length}`
@@ -181904,6 +182205,85 @@ ${e?.toString()}`);
       clearTimeout(timer);
     }
     this.staleSessionTimers.clear();
+    this.sessionStartedAt.clear();
+  }
+  // Start the periodic age-based session rotation (#287).
+  startSessionRotation() {
+    this.stopSessionRotation();
+    const hours = this.readSessionMaxAgeHours();
+    if (hours === 0) {
+      this.log.info(
+        "Session rotation disabled (HAMH_MATTER_SESSION_MAX_AGE_HOURS=0)"
+      );
+      return;
+    }
+    this.maxSessionAgeMs = hours * 60 * 60 * 1e3;
+    this.rotationTimer = setInterval(
+      () => this.rotateAgedSessions(),
+      ROTATION_CHECK_INTERVAL_MS
+    );
+    this.log.info(
+      `Session rotation: max age ${hours}h, check every ${ROTATION_CHECK_INTERVAL_MS / 6e4}min`
+    );
+  }
+  stopSessionRotation() {
+    if (this.rotationTimer) {
+      clearInterval(this.rotationTimer);
+      this.rotationTimer = null;
+    }
+  }
+  // Resolve session rotation max age. Bridge config wins, then env var,
+  // then built-in default. 0 disables, otherwise clamped to range.
+  readSessionMaxAgeHours() {
+    const { min, max } = SESSION_MAX_AGE_HOURS_RANGE;
+    const fromConfig = this.dataProvider.sessionMaxAgeHours;
+    if (fromConfig != null && Number.isFinite(fromConfig) && fromConfig >= 0) {
+      if (fromConfig === 0) return 0;
+      if (fromConfig < min) return min;
+      if (fromConfig > max) return max;
+      return fromConfig;
+    }
+    const raw = process.env.HAMH_MATTER_SESSION_MAX_AGE_HOURS;
+    const parsed = parseSessionMaxAgeHours(raw);
+    if (parsed == null) {
+      this.log.warn(
+        `Invalid HAMH_MATTER_SESSION_MAX_AGE_HOURS=${raw}, falling back to ${DEFAULT_SESSION_MAX_AGE_HOURS}h`
+      );
+      return DEFAULT_SESSION_MAX_AGE_HOURS;
+    }
+    return parsed;
+  }
+  // Gracefully close sessions older than maxSessionAgeMs so controllers
+  // re-establish CASE and re-subscribe. Stale (0-sub) sessions are handled
+  // by the existing dead-session path, so only rotate ones with subscriptions.
+  rotateAgedSessions() {
+    if (this.maxSessionAgeMs === 0) return;
+    try {
+      const sessionManager = this.server.env.get(SessionManager);
+      const now = Date.now();
+      const closes = [];
+      for (const s of [...sessionManager.sessions]) {
+        const startedAt = this.sessionStartedAt.get(s.id);
+        if (startedAt == null) continue;
+        const ageMs = now - startedAt;
+        if (ageMs < this.maxSessionAgeMs || s.isClosing || s.subscriptions.size === 0) {
+          continue;
+        }
+        const ageMin = Math.round(ageMs / 6e4);
+        this.log.info(
+          `Rotating session ${s.id} (peer ${s.peerNodeId}, age ${ageMin}min, subs ${s.subscriptions.size})`
+        );
+        closes.push(
+          s.initiateClose().catch(() => {
+            return s.initiateForceClose();
+          })
+        );
+      }
+      if (closes.length > 0) {
+        Promise.allSettled(closes).then(() => this.triggerMdnsReAnnounce());
+      }
+    } catch {
+    }
   }
   stopAutoForceSync() {
     if (this.autoForceSyncTimer) {
@@ -182320,6 +182700,11 @@ var ServerModeVacuumEndpoint = class _ServerModeVacuumEndpoint extends EntityEnd
    * unlike errorStateLabel (id 1) which requires errorStateId 128-191.
    */
   async pushKeepalive() {
+    try {
+      await this.construction.ready;
+    } catch {
+      return;
+    }
     try {
       this.keepaliveCounter++;
       const counter = this.keepaliveCounter;
@@ -183094,6 +183479,10 @@ function startOptionsBuilder(yargs2) {
     type: "number",
     description: "The refresh rate (in seconds) to detect new devices & entities or their configurations",
     default: 60
+  }).option("ha-message-timeout", {
+    type: "number",
+    description: "Timeout in milliseconds for individual Home Assistant WebSocket requests (registry fetches, action calls). Raise this if you see 'HA message ... timed out' warnings on a large or slow HA instance.",
+    default: 6e4
   }).option("http-auth-username", {
     type: "string",
     description: "Username for HTTP basic authentication (optional)"