@apocaliss92/nodedreame 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -710,6 +710,51 @@ declare enum TaskStatus {
     CustomCleaningWashingPaused = 33
 }
 
+/**
+ * AI obstacle-detection codec. The robot packs ALL AI-obstacle toggles into a
+ * SINGLE MIoT property — `AI_DETECTION` (siid 4 piid 22) — whose value is EITHER
+ * an `int` bitmask OR a `str` JSON object, depending on firmware generation.
+ * Ported from the Tasshack `dreame-vacuum` HA integration (v2.0.0b25):
+ *   - INT  ←→ `DreameVacuumAIProperty`     (bitwise flags)
+ *   - JSON ←→ `DreameVacuumStrAIProperty`  ({ "<key>": bool })
+ *
+ * This module exposes per-feature decode + a read-modify-write encode that
+ * preserves the other features, so a consumer can present each AI toggle as an
+ * independent boolean without knowing which on-wire encoding the model uses.
+ */
+/** Canonical AI-obstacle feature keys. A given model exposes a subset. */
+type DreameAiFeature = 'furnitureDetection' | 'obstacleDetection' | 'obstaclePicture' | 'fluidDetection' | 'petDetection' | 'obstacleImageUpload' | 'petAvoidance' | 'fuzzyObstacleDetection' | 'petPicture' | 'petFocusedDetection' | 'largeParticlesBoost' | 'humanDetection';
+/**
+ * Bit value in the INT-encoded `AI_DETECTION` (Tasshack `DreameVacuumAIProperty`).
+ * A feature absent here has no int representation (JSON-only).
+ */
+declare const AI_FEATURE_BIT: Readonly<Partial<Record<DreameAiFeature, number>>>;
+/**
+ * Key in the JSON-string-encoded `AI_DETECTION` (Tasshack
+ * `DreameVacuumStrAIProperty`). A feature absent here has no JSON representation.
+ */
+declare const AI_FEATURE_JSON_KEY: Readonly<Partial<Record<DreameAiFeature, string>>>;
+/** The raw on-wire `AI_DETECTION` value: an int bitmask, a JSON string, or absent. */
+type AiDetectionRaw = number | string | null;
+/**
+ * Decode ONE AI feature's on/off state from the raw `AI_DETECTION` value,
+ * transparently handling both the int-bitmask and JSON-string encodings.
+ * Returns `null` when the value is absent, the encoding cannot represent the
+ * feature, or the JSON payload omits the key.
+ */
+declare function decodeAiFeature(raw: AiDetectionRaw, feature: DreameAiFeature): boolean | null;
+/**
+ * Compute the value to WRITE back to `AI_DETECTION` after toggling ONE feature,
+ * preserving the on-wire encoding and the other features. Mirrors Tasshack
+ * `set_ai_detection`: an int payload is the full new bitmask; a JSON payload
+ * carries ONLY the changed key (the device merges it server-side).
+ *
+ * Throws when the current value/encoding is unknown (a blind read-modify-write
+ * could clobber the other features) or the feature has no representation in the
+ * active encoding.
+ */
+declare function encodeAiFeatureWrite(raw: AiDetectionRaw, feature: DreameAiFeature, value: boolean): number | string;
+
 /**
  * Per-model vacuum capability records (ported from malard/node-dreame
  * src/capabilities.ts, MIT — attribution retained) plus a resolver that
@@ -743,6 +788,12 @@ interface VacuumCapabilities {
     canMap: boolean;
     supportedSuctionLevels: readonly SuctionLevel[];
     supportedWaterVolumes: readonly WaterVolume[];
+    /**
+     * The AI-obstacle toggles this model exposes (subset of {@link DreameAiFeature}),
+     * each surfaced as an independent boolean from the packed `AI_DETECTION` property.
+     * Empty when `hasAiObstacleDetection` is false.
+     */
+    supportedAiFeatures: readonly DreameAiFeature[];
 }
 declare const MODEL_CAPABILITIES$1: Readonly<Record<string, VacuumCapabilities>>;
 /** Resolve a model to its rich vacuum capability record (frozen / fallback). */
@@ -1215,6 +1266,27 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     get sideBrushLeftPct(): number | null;
     get filterLeftPct(): number | null;
     get volume(): number | null;
+    /**
+     * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
+     * string, depending on firmware — or `null` when not yet observed. Prefer the
+     * decoded {@link aiFeature} / {@link supportedAiFeatures} surface.
+     */
+    get aiDetectionRaw(): AiDetectionRaw;
+    /** The AI-obstacle toggles this model exposes (from its capability record). */
+    get supportedAiFeatures(): readonly DreameAiFeature[];
+    /**
+     * Read ONE AI-obstacle toggle's on/off state, decoded from the packed
+     * `AI_DETECTION` value (transparent across the int / JSON encodings). `null`
+     * when the value is unobserved or the feature is not representable.
+     */
+    aiFeature(feature: DreameAiFeature): boolean | null;
+    /**
+     * Toggle ONE AI-obstacle feature, preserving the others via a read-modify-write
+     * of the packed `AI_DETECTION` property (mirrors Tasshack `set_ai_detection`).
+     * Capability-gated on `hasAiObstacleDetection`; rejects when the current value
+     * is unknown (a blind write would clobber the other toggles).
+     */
+    setAiFeature(feature: DreameAiFeature, value: boolean): Promise<unknown>;
     /**
      * Start cleaning (MIoT action siid 2 aiid 1). Named `startCleaning` — NOT
      * `start` — because `BaseDevice.start()` is the lifecycle method that opens
@@ -1289,6 +1361,19 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
      * forwarded verbatim.
      */
     fetchLatestMap(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
+    /**
+     * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+     * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+     * surface its LAST cleaning map without a fresh clean. Emits the usual
+     * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+     * returns the resolved {@link mapFilename} (null when the model has no map or
+     * the shadow carries no map path yet).
+     *
+     * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+     * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+     * that as "no saved map available".
+     */
+    refreshSavedMapFilename(): Promise<string | null>;
     /**
      * The current room/segment id, derived from the most-recently-decoded map's
      * active-segment set (`sa`). `null` when no map has been fetched or no
@@ -1334,6 +1419,9 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     }, {
         readonly siid: 4;
         readonly piid: 63;
+    }, {
+        readonly siid: 4;
+        readonly piid: 22;
     }, {
         readonly siid: 3;
         readonly piid: 1;
@@ -2147,4 +2235,4 @@ declare function createDumper(target: DumperDevice, options?: DumperOptions): Du
  */
 declare function createClientDumper(client: Nodreame, options?: DumperOptions): Dumper[];
 
-export { BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, type AiDetectionRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, decodeAiFeature, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };

package/dist/index.d.ts

@@ -710,6 +710,51 @@ declare enum TaskStatus {
     CustomCleaningWashingPaused = 33
 }
 
+/**
+ * AI obstacle-detection codec. The robot packs ALL AI-obstacle toggles into a
+ * SINGLE MIoT property — `AI_DETECTION` (siid 4 piid 22) — whose value is EITHER
+ * an `int` bitmask OR a `str` JSON object, depending on firmware generation.
+ * Ported from the Tasshack `dreame-vacuum` HA integration (v2.0.0b25):
+ *   - INT  ←→ `DreameVacuumAIProperty`     (bitwise flags)
+ *   - JSON ←→ `DreameVacuumStrAIProperty`  ({ "<key>": bool })
+ *
+ * This module exposes per-feature decode + a read-modify-write encode that
+ * preserves the other features, so a consumer can present each AI toggle as an
+ * independent boolean without knowing which on-wire encoding the model uses.
+ */
+/** Canonical AI-obstacle feature keys. A given model exposes a subset. */
+type DreameAiFeature = 'furnitureDetection' | 'obstacleDetection' | 'obstaclePicture' | 'fluidDetection' | 'petDetection' | 'obstacleImageUpload' | 'petAvoidance' | 'fuzzyObstacleDetection' | 'petPicture' | 'petFocusedDetection' | 'largeParticlesBoost' | 'humanDetection';
+/**
+ * Bit value in the INT-encoded `AI_DETECTION` (Tasshack `DreameVacuumAIProperty`).
+ * A feature absent here has no int representation (JSON-only).
+ */
+declare const AI_FEATURE_BIT: Readonly<Partial<Record<DreameAiFeature, number>>>;
+/**
+ * Key in the JSON-string-encoded `AI_DETECTION` (Tasshack
+ * `DreameVacuumStrAIProperty`). A feature absent here has no JSON representation.
+ */
+declare const AI_FEATURE_JSON_KEY: Readonly<Partial<Record<DreameAiFeature, string>>>;
+/** The raw on-wire `AI_DETECTION` value: an int bitmask, a JSON string, or absent. */
+type AiDetectionRaw = number | string | null;
+/**
+ * Decode ONE AI feature's on/off state from the raw `AI_DETECTION` value,
+ * transparently handling both the int-bitmask and JSON-string encodings.
+ * Returns `null` when the value is absent, the encoding cannot represent the
+ * feature, or the JSON payload omits the key.
+ */
+declare function decodeAiFeature(raw: AiDetectionRaw, feature: DreameAiFeature): boolean | null;
+/**
+ * Compute the value to WRITE back to `AI_DETECTION` after toggling ONE feature,
+ * preserving the on-wire encoding and the other features. Mirrors Tasshack
+ * `set_ai_detection`: an int payload is the full new bitmask; a JSON payload
+ * carries ONLY the changed key (the device merges it server-side).
+ *
+ * Throws when the current value/encoding is unknown (a blind read-modify-write
+ * could clobber the other features) or the feature has no representation in the
+ * active encoding.
+ */
+declare function encodeAiFeatureWrite(raw: AiDetectionRaw, feature: DreameAiFeature, value: boolean): number | string;
+
 /**
  * Per-model vacuum capability records (ported from malard/node-dreame
  * src/capabilities.ts, MIT — attribution retained) plus a resolver that
@@ -743,6 +788,12 @@ interface VacuumCapabilities {
     canMap: boolean;
     supportedSuctionLevels: readonly SuctionLevel[];
     supportedWaterVolumes: readonly WaterVolume[];
+    /**
+     * The AI-obstacle toggles this model exposes (subset of {@link DreameAiFeature}),
+     * each surfaced as an independent boolean from the packed `AI_DETECTION` property.
+     * Empty when `hasAiObstacleDetection` is false.
+     */
+    supportedAiFeatures: readonly DreameAiFeature[];
 }
 declare const MODEL_CAPABILITIES$1: Readonly<Record<string, VacuumCapabilities>>;
 /** Resolve a model to its rich vacuum capability record (frozen / fallback). */
@@ -1215,6 +1266,27 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     get sideBrushLeftPct(): number | null;
     get filterLeftPct(): number | null;
     get volume(): number | null;
+    /**
+     * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
+     * string, depending on firmware — or `null` when not yet observed. Prefer the
+     * decoded {@link aiFeature} / {@link supportedAiFeatures} surface.
+     */
+    get aiDetectionRaw(): AiDetectionRaw;
+    /** The AI-obstacle toggles this model exposes (from its capability record). */
+    get supportedAiFeatures(): readonly DreameAiFeature[];
+    /**
+     * Read ONE AI-obstacle toggle's on/off state, decoded from the packed
+     * `AI_DETECTION` value (transparent across the int / JSON encodings). `null`
+     * when the value is unobserved or the feature is not representable.
+     */
+    aiFeature(feature: DreameAiFeature): boolean | null;
+    /**
+     * Toggle ONE AI-obstacle feature, preserving the others via a read-modify-write
+     * of the packed `AI_DETECTION` property (mirrors Tasshack `set_ai_detection`).
+     * Capability-gated on `hasAiObstacleDetection`; rejects when the current value
+     * is unknown (a blind write would clobber the other toggles).
+     */
+    setAiFeature(feature: DreameAiFeature, value: boolean): Promise<unknown>;
     /**
      * Start cleaning (MIoT action siid 2 aiid 1). Named `startCleaning` — NOT
      * `start` — because `BaseDevice.start()` is the lifecycle method that opens
@@ -1289,6 +1361,19 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
      * forwarded verbatim.
      */
     fetchLatestMap(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
+    /**
+     * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+     * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+     * surface its LAST cleaning map without a fresh clean. Emits the usual
+     * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+     * returns the resolved {@link mapFilename} (null when the model has no map or
+     * the shadow carries no map path yet).
+     *
+     * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+     * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+     * that as "no saved map available".
+     */
+    refreshSavedMapFilename(): Promise<string | null>;
     /**
      * The current room/segment id, derived from the most-recently-decoded map's
      * active-segment set (`sa`). `null` when no map has been fetched or no
@@ -1334,6 +1419,9 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     }, {
         readonly siid: 4;
         readonly piid: 63;
+    }, {
+        readonly siid: 4;
+        readonly piid: 22;
     }, {
         readonly siid: 3;
         readonly piid: 1;
@@ -2147,4 +2235,4 @@ declare function createDumper(target: DumperDevice, options?: DumperOptions): Du
  */
 declare function createClientDumper(client: Nodreame, options?: DumperOptions): Dumper[];
 
-export { BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, type AiDetectionRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, decodeAiFeature, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
-var LIBRARY_VERSION = "1.3.1";
+var LIBRARY_VERSION = "1.6.0";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -1149,6 +1149,14 @@ var VACUUM_PROP = {
   CLEANING_MODE: { siid: 4, piid: 23 },
   /** VERIFIED r2532a — Child Lock boolean. */
   CHILD_LOCK: { siid: 4, piid: 27 },
+  /**
+   * AI obstacle-detection toggle bundle (Tasshack types.py:1609 — `AI_DETECTION`,
+   * siid 4 piid 22). The value packs ALL AI-obstacle switches into ONE property,
+   * encoded as EITHER an int bitmask (`DreameVacuumAIProperty`) OR a JSON string
+   * (`DreameVacuumStrAIProperty`) depending on firmware. Decode/encode per-feature
+   * via `ai-detection.ts` ({@link decodeAiFeature} / {@link encodeAiFeatureWrite}).
+   */
+  AI_DETECTION: { siid: 4, piid: 22 },
   /** VERIFIED r2532a 2026-05-03 — task progress percentage 0..100. */
   TASK_PROGRESS_PCT: { siid: 4, piid: 63 },
   /** VERIFIED r2532a — mop-drying progress (minutes ticking during MopDrying). */
@@ -1487,7 +1495,91 @@ function parseFaultList(value) {
   return codes;
 }
 
+// src/models/vacuum/ai-detection.ts
+var AI_FEATURE_BIT = {
+  furnitureDetection: 1,
+  obstacleDetection: 2,
+  obstaclePicture: 4,
+  fluidDetection: 8,
+  petDetection: 16,
+  obstacleImageUpload: 32,
+  // AI_IMAGE = 64 is an internal flag, not a user toggle — intentionally omitted.
+  petAvoidance: 128,
+  fuzzyObstacleDetection: 256,
+  petPicture: 512,
+  petFocusedDetection: 1024,
+  largeParticlesBoost: 2048
+};
+var AI_FEATURE_JSON_KEY = {
+  obstacleDetection: "obstacle_detect_switch",
+  obstacleImageUpload: "obstacle_app_display_switch",
+  petDetection: "whether_have_pet",
+  humanDetection: "human_detect_switch",
+  furnitureDetection: "furniture_detect_switch",
+  fluidDetection: "fluid_detect_switch"
+};
+function isRecord(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function parseJsonPayload(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function coerceBool(v) {
+  if (typeof v === "boolean") return v;
+  if (v === 1 || v === "1") return true;
+  if (v === 0 || v === "0") return false;
+  return null;
+}
+function decodeAiFeature(raw, feature) {
+  if (typeof raw === "number") {
+    const bit = AI_FEATURE_BIT[feature];
+    if (bit === void 0) return null;
+    return (raw & bit) === bit;
+  }
+  if (typeof raw === "string") {
+    const key2 = AI_FEATURE_JSON_KEY[feature];
+    if (key2 === void 0) return null;
+    const payload = parseJsonPayload(raw);
+    if (payload === null) return null;
+    return coerceBool(payload[key2]);
+  }
+  return null;
+}
+function encodeAiFeatureWrite(raw, feature, value) {
+  if (typeof raw === "number") {
+    const bit = AI_FEATURE_BIT[feature];
+    if (bit === void 0) {
+      throw new Error(`encodeAiFeatureWrite: feature "${feature}" has no int-bitmask representation`);
+    }
+    return value ? raw | bit : raw & ~bit;
+  }
+  if (typeof raw === "string") {
+    const key2 = AI_FEATURE_JSON_KEY[feature];
+    if (key2 === void 0) {
+      throw new Error(`encodeAiFeatureWrite: feature "${feature}" has no JSON-key representation`);
+    }
+    return JSON.stringify({ [key2]: value });
+  }
+  throw new Error(
+    `encodeAiFeatureWrite: AI_DETECTION value not yet known \u2014 cannot safely toggle "${feature}"`
+  );
+}
+
 // src/models/vacuum/capabilities.ts
+var X50_AI_FEATURES = [
+  "obstacleDetection",
+  "petDetection",
+  "furnitureDetection",
+  "fluidDetection",
+  "obstaclePicture",
+  "obstacleImageUpload",
+  "fuzzyObstacleDetection"
+];
 var FALLBACK = {
   verified: false,
   canMop: false,
@@ -1516,7 +1608,9 @@ var FALLBACK = {
     2 /* Intense */,
     3 /* Max */
   ],
-  supportedWaterVolumes: [1 /* Low */, 2 /* Medium */, 3 /* High */]
+  supportedWaterVolumes: [1 /* Low */, 2 /* Medium */, 3 /* High */],
+  // An unknown model advertises no AI toggles until its feature set is verified.
+  supportedAiFeatures: []
 };
 var X50_FAMILY = {
   canMop: true,
@@ -1542,7 +1636,8 @@ var X50_FAMILY = {
     2 /* Intense */,
     3 /* Max */
   ],
-  supportedWaterVolumes: [1 /* Low */, 2 /* Medium */, 3 /* High */]
+  supportedWaterVolumes: [1 /* Low */, 2 /* Medium */, 3 /* High */],
+  supportedAiFeatures: X50_AI_FEATURES
 };
 function deepFreeze(obj) {
   if (obj && typeof obj === "object" && !Object.isFrozen(obj)) {
@@ -2676,6 +2771,39 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
   get volume() {
     return this.#num(SETTINGS_PROP.VOLUME.siid, SETTINGS_PROP.VOLUME.piid);
   }
+  // -- AI obstacle-detection ----------------------------------------------
+  /**
+   * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
+   * string, depending on firmware — or `null` when not yet observed. Prefer the
+   * decoded {@link aiFeature} / {@link supportedAiFeatures} surface.
+   */
+  get aiDetectionRaw() {
+    const v = this.getProperty(VACUUM_PROP.AI_DETECTION.siid, VACUUM_PROP.AI_DETECTION.piid)?.value;
+    return typeof v === "number" || typeof v === "string" ? v : null;
+  }
+  /** The AI-obstacle toggles this model exposes (from its capability record). */
+  get supportedAiFeatures() {
+    return this.#caps.supportedAiFeatures;
+  }
+  /**
+   * Read ONE AI-obstacle toggle's on/off state, decoded from the packed
+   * `AI_DETECTION` value (transparent across the int / JSON encodings). `null`
+   * when the value is unobserved or the feature is not representable.
+   */
+  aiFeature(feature) {
+    return decodeAiFeature(this.aiDetectionRaw, feature);
+  }
+  /**
+   * Toggle ONE AI-obstacle feature, preserving the others via a read-modify-write
+   * of the packed `AI_DETECTION` property (mirrors Tasshack `set_ai_detection`).
+   * Capability-gated on `hasAiObstacleDetection`; rejects when the current value
+   * is unknown (a blind write would clobber the other toggles).
+   */
+  async setAiFeature(feature, value) {
+    this.#requireCap(this.#caps.hasAiObstacleDetection, "setAiFeature", "AI obstacle detection");
+    const next = encodeAiFeatureWrite(this.aiDetectionRaw, feature, value);
+    return this.setProperty({ ...VACUUM_PROP.AI_DETECTION, value: next });
+  }
   // -- command helpers ----------------------------------------------------
   #resolveCleanOpts(opts) {
     const repeats = Math.max(1, Math.trunc(opts.repeats ?? 1));
@@ -2839,6 +2967,23 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
     if (filename === null) return null;
     return this.getMap({ filename, ...opts });
   }
+  /**
+   * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+   * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+   * surface its LAST cleaning map without a fresh clean. Emits the usual
+   * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+   * returns the resolved {@link mapFilename} (null when the model has no map or
+   * the shadow carries no map path yet).
+   *
+   * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+   * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+   * that as "no saved map available".
+   */
+  async refreshSavedMapFilename() {
+    if (!this.#caps.canMap) return null;
+    await this.refreshCachedProperties([VACUUM_PROP.MAP_PATH]);
+    return this.mapFilename;
+  }
   /**
    * The current room/segment id, derived from the most-recently-decoded map's
    * active-segment set (`sa`). `null` when no map has been fetched or no
@@ -2894,6 +3039,7 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
     VACUUM_PROP.WATER_VOLUME,
     VACUUM_PROP.CLEAN_MODE_SETTING,
     VACUUM_PROP.TASK_PROGRESS_PCT,
+    VACUUM_PROP.AI_DETECTION,
     BATTERY_PROP.LEVEL,
     BATTERY_PROP.CHARGING_STATUS,
     CONSUMABLE_PROP.MAIN_BRUSH_LEFT,
@@ -3066,7 +3212,7 @@ var MowerFault = /* @__PURE__ */ ((MowerFault2) => {
 })(MowerFault || {});
 
 // src/models/mower/decode.ts
-function isRecord(v) {
+function isRecord2(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function numArrayOrNull(v) {
@@ -3083,12 +3229,12 @@ function numArrayOrNull(v) {
   return out;
 }
 function parseTaskDescriptor(value) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     return null;
   }
   const t = value["t"];
   const d = value["d"];
-  if (typeof t !== "string" || !isRecord(d)) {
+  if (typeof t !== "string" || !isRecord2(d)) {
     return null;
   }
   const exe = d["exe"];
@@ -3117,7 +3263,7 @@ function controlActionFor(code) {
   return controlLookup(code);
 }
 function parseControlStatus(value) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     return null;
   }
   const status = value["status"];
@@ -3227,7 +3373,7 @@ var MowerCapabilityResolver = class {
 // src/models/mower/map/parser.ts
 var PATH_SENTINEL_X = 32767;
 var PATH_SENTINEL_Y = -32768;
-function isRecord2(v) {
+function isRecord3(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function asNumber(v, fallback) {
@@ -3265,7 +3411,7 @@ function parseSplitPos(info) {
   return 0;
 }
 function parsePolygonList(dataMap) {
-  if (!isRecord2(dataMap) || dataMap["dataType"] !== "Map") {
+  if (!isRecord3(dataMap) || dataMap["dataType"] !== "Map") {
     return [];
   }
   const value = dataMap["value"];
@@ -3277,7 +3423,7 @@ function extractPathCoords(pathList) {
   }
   const out = [];
   for (const p of pathList) {
-    if (isRecord2(p) && typeof p["x"] === "number" && typeof p["y"] === "number") {
+    if (isRecord3(p) && typeof p["x"] === "number" && typeof p["y"] === "number") {
       out.push({ x: p["x"], y: p["y"] });
     }
   }
@@ -3312,7 +3458,7 @@ function asEntry(entry) {
   }
   const tuple = entry;
   const data = tuple[1];
-  if (!isRecord2(data)) {
+  if (!isRecord3(data)) {
     return null;
   }
   return { id: tuple[0], data };
@@ -3390,7 +3536,7 @@ function parseContours(list) {
   return out;
 }
 function parseBoundary(raw) {
-  if (!isRecord2(raw)) {
+  if (!isRecord3(raw)) {
     return null;
   }
   const { x1, y1, x2, y2 } = raw;
@@ -3401,7 +3547,7 @@ function parseBoundary(raw) {
 }
 function parseMowerMap(mapJsonStr) {
   const data = JSON.parse(mapJsonStr);
-  if (!isRecord2(data)) {
+  if (!isRecord3(data)) {
     throw new Error("Map JSON is not an object");
   }
   const mapIndex = asNumber(data["mapIndex"], 0);
@@ -4570,6 +4716,8 @@ function createClientDumper(client, options) {
   return client.devices.map((d) => createDumper(d, options));
 }
 export {
+  AI_FEATURE_BIT,
+  AI_FEATURE_JSON_KEY,
   BaseDevice,
   ChargingStatus,
   CleaningMode,
@@ -4599,6 +4747,8 @@ export {
   WaterVolume,
   createClientDumper,
   createDumper,
+  decodeAiFeature,
+  encodeAiFeatureWrite,
   getMowerCapabilities,
   getVacuumCapabilities,
   renderMowerSvg,