@apocaliss92/nodedreame 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1493 @@
+import { fetch } from 'undici';
+
+/** Public name of this library. */
+declare const LIBRARY_NAME = "nodedreame";
+
+declare class DreameError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class DreameAuthError extends DreameError {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined, cause?: unknown);
+}
+declare class DreameApiError extends DreameError {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined, cause?: unknown);
+}
+/**
+ * Thrown when the cloud returns code 80001. The literal `msg` claims the
+ * device is offline — that interpretation is FREQUENTLY WRONG. 80001 means
+ * the cloud's HTTP-side waiter for the device's MQTT ACK gave up after ~8s.
+ * It does NOT prove the action failed to reach the device. The MQTT
+ * subscription is the source of truth for reachability. The only true
+ * positive is a genuinely unreachable device (powered off / network lost /
+ * rebooting) — in which case no MQTT echo arrives either.
+ */
+declare class DreameDeviceOfflineError extends DreameApiError {
+    constructor(message: string, status: number, body?: unknown);
+}
+declare class DreameTransportError extends DreameError {
+    constructor(message: string, cause?: unknown);
+}
+
+/** Supported Dreame cloud regions. */
+type DreameRegion = 'eu' | 'us' | 'cn' | 'ru' | 'sg' | 'in' | 'de' | 'tw';
+
+interface DreameSession {
+    accessToken: string;
+    refreshToken?: string | undefined;
+    uid: string;
+    /** Epoch-ms at which `accessToken` expires (`Date.now() + expires_in*1000`). */
+    expiresAt: number;
+    region: DreameRegion;
+}
+interface DreameDevice {
+    did: string;
+    model: string;
+    name: string;
+    mac?: string | undefined;
+    online: boolean;
+    /** Raw record from the cloud, kept for forward compatibility (incl. bindDomain). */
+    raw: Record<string, unknown>;
+    firmwareVersion?: string;
+    serialNumber?: string;
+    cloudState?: DreameCloudState;
+}
+/** Cloud-cached subset of device state distilled from the device-list response. */
+interface DreameCloudState {
+    /** Most-recent MIoT state int (siid 2 piid 1). */
+    latestStatus: number | null;
+    /** Battery percentage 0-100. */
+    battery: number | null;
+    /** Camera/LinkVisual session active? Derived from the `videoStatus` JSON string. */
+    videoActive: boolean | null;
+    /** `featureCode2` capability bitfield. */
+    featureCode2: number | null;
+}
+/** A single MIoT property reference (service + property id). */
+interface MiotProp {
+    siid: number;
+    piid: number;
+}
+/** A single MIoT action reference (service + action id) with optional inputs. */
+interface MiotAction {
+    siid: number;
+    aiid: number;
+    in?: unknown[];
+}
+/** Property write — `MiotProp` plus the value to set. */
+interface PropertyWrite extends MiotProp {
+    value: unknown;
+}
+/**
+ * Per-property result returned by the cloud. All fields are optional: the cloud
+ * response shape is not fully observed (the command path is not exercised by the
+ * live e2e), so we validate structure leniently rather than risk rejecting real
+ * data. Mirrors `PropertyResultSchema` in transport/schemas.ts.
+ */
+interface PropertyResult {
+    siid?: number | undefined;
+    piid?: number | undefined;
+    value?: unknown;
+    code?: number | undefined;
+    [key: string]: unknown;
+}
+
+/**
+ * Narrow fetch-shaped function type backed by undici. Defined here so all
+ * callers share one declaration — no DOM lib globals, no casts.
+ *
+ * We re-export `FetchImpl` from this module as the canonical definition;
+ * `transport/http.ts` re-exports it from here so downstream modules have a
+ * single import path.
+ */
+type FetchImpl = typeof fetch;
+
+interface RequestContextOpts {
+    region: DreameRegion;
+    country?: string;
+    lang?: string;
+    host?: string;
+    fetchImpl?: FetchImpl;
+}
+interface RequestContextInput {
+    region: DreameRegion;
+    country?: string | undefined;
+    lang?: string | undefined;
+    /** Override host. Some callers spell this `authHost`/`apiHost` — pass that here. */
+    host?: string | undefined;
+    fetchImpl?: FetchImpl | undefined;
+}
+declare class RequestContext {
+    readonly region: DreameRegion;
+    readonly country: string;
+    readonly lang: string;
+    readonly host: string;
+    readonly fetchImpl: FetchImpl;
+    constructor(opts: RequestContextOpts);
+    static from(input: RequestContextInput): RequestContext;
+    /** `https://<host><path>` — pass a path with a leading slash. */
+    url(path: string): string;
+    /** Build the static Dreame headers, optionally with a bearer token + content-type. */
+    headers(opts?: {
+        accessToken?: string | null;
+        contentType?: string;
+    }): Record<string, string>;
+}
+
+interface CommonInput {
+    session: DreameSession;
+    region: DreameRegion;
+    did: string;
+    ctx?: RequestContext;
+    country?: string;
+    lang?: string;
+    apiHost?: string;
+    /**
+     * Inject a fetch implementation. Placed here (on `CommonInput`) so tests can
+     * pass a mock via the first argument without any casts. Do NOT put this on
+     * `CallOptions` — it belongs on the base/donor argument only.
+     */
+    fetchImpl?: FetchImpl;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+
+/** A strongly-typed wrapper over Node's EventEmitter. */
+declare class TypedEmitter<Events extends Record<string, unknown[]>> {
+    #private;
+    on<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    off<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    emit<K extends keyof Events & string>(event: K, ...args: Events[K]): boolean;
+    removeAllListeners(): this;
+}
+
+/** A single property update pushed by the device. */
+interface PropertyChange {
+    did: string;
+    siid: number;
+    piid: number;
+    value: unknown;
+}
+
+/**
+ * A read-only set of capability tokens a device model supports. Phase 2 ships
+ * only the shape + a no-op default; P3/P4 populate per-model tables behind the
+ * same {@link CapabilityResolver} interface.
+ */
+interface DeviceCapabilities {
+    readonly model: string;
+    /** Whether the model is known to support a capability token. */
+    has(token: string): boolean;
+    /** All known capability tokens for the model. */
+    list(): readonly string[];
+}
+/** Resolves the capability set for a device model string. */
+interface CapabilityResolver {
+    resolve(model: string): DeviceCapabilities;
+}
+/**
+ * Default resolver: every model resolves to an EMPTY capability set. This is a
+ * deliberate no-op scaffold — device-family resolvers (vacuum/mower) override
+ * `resolve` in later phases while keeping this interface stable.
+ */
+declare class DefaultCapabilityResolver implements CapabilityResolver {
+    resolve(model: string): DeviceCapabilities;
+}
+/** Convenience: resolve capabilities via the shared default resolver. */
+declare function resolveCapabilities(model: string): DeviceCapabilities;
+
+/** Options for constructing a {@link Nodreame} facade. */
+interface NodreameOptions {
+    /** Account email / username for the Dreamehome cloud. */
+    username: string;
+    /** Account password (hashed client-side before transmission). */
+    password: string;
+    /** Dreame cloud region. */
+    region: DreameRegion;
+    /** ISO-3166 alpha-2 country override (defaults from region). */
+    country?: string;
+    /** ISO-639-1 language override (defaults from region). */
+    lang?: string;
+    /**
+     * Brand tenant. Reserved for Mova devices; Phase 2 only wires Dreame, so this
+     * is accepted but not yet branched on. Defaults to `'dreame'`.
+     */
+    accountType?: 'dreame' | 'mova';
+    /**
+     * Seconds before access-token expiry at which the session is proactively
+     * refreshed. Defaults to 100 (parity with the donor client).
+     */
+    refreshLeewaySecs?: number;
+    /**
+     * Poll interval (ms) used as a fallback when a device's MQTT push is down.
+     * Defaults to 30000. Set to 0 to disable poll fallback entirely.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Whether each device should eagerly seed its property cache on construction
+     * via a `get_properties` read. Defaults to `true` (opt-out).
+     */
+    fetchInitialValues?: boolean;
+    /** Inject a fetch implementation (testing/advanced). */
+    fetchImpl?: FetchImpl;
+}
+/** One cached property value plus when it was last observed. */
+interface PropertyState {
+    siid: number;
+    piid: number;
+    value: unknown;
+    /** Epoch-ms of the last update (push or live read). */
+    updatedAt: number;
+}
+/** Emitted when a single property changes (cache delta). */
+interface PropertyChangedEvent {
+    deviceId: string;
+    siid: number;
+    piid: number;
+    value: unknown;
+    /** Prior cached value, or `null` if the property was previously unknown. */
+    previousValue: unknown;
+}
+/** Emitted once per push batch, aggregating all property changes in it. */
+interface StateChangedEvent {
+    deviceId: string;
+    changes: PropertyChangedEvent[];
+}
+/** Emitted on a device MIoT event (`event_occured`). */
+interface DeviceEvent {
+    deviceId: string;
+    siid: number;
+    eiid: number;
+    arguments: unknown[];
+}
+
+/**
+ * The slice of {@link DreamePush} that {@link BaseDevice} depends on. Declaring
+ * it as an interface lets tests inject a fake emitter with no casts; the real
+ * `DreamePush` structurally satisfies it.
+ */
+interface PushLike {
+    on(event: 'properties', cb: (changes: PropertyChange[]) => void): this;
+    on(event: 'event', cb: (ev: {
+        did: string;
+        siid: number;
+        eiid: number;
+        arguments: unknown[];
+    }) => void): this;
+    on(event: 'connect', cb: () => void): this;
+    on(event: 'close', cb: () => void): this;
+    on(event: 'error', cb: (err: Error) => void): this;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    refreshSession(session: DreameSession): Promise<void>;
+}
+/** Injectable collaborators — defaults wire the real transport + command layer. */
+interface BaseDeviceDeps {
+    createPush(device: DreameDevice, session: DreameSession, region: DreameRegion): PushLike;
+    getProperties(base: CommonInput, props: MiotProp[]): Promise<PropertyResult[]>;
+    setProperties(base: CommonInput, writes: PropertyWrite[]): Promise<PropertyResult[]>;
+    callAction(base: CommonInput, action: {
+        siid: number;
+        aiid: number;
+        in?: unknown[];
+    }): Promise<unknown>;
+}
+type BaseDeviceEvents = {
+    propertyChanged: [PropertyChangedEvent];
+    stateChanged: [StateChangedEvent];
+    event: [DeviceEvent];
+    error: [Error];
+};
+interface BaseDeviceInput {
+    device: DreameDevice;
+    region: DreameRegion;
+    /** Always reads the LATEST session — the facade owns the variable. */
+    sessionRef: () => DreameSession;
+    deps?: BaseDeviceDeps;
+    /** Eager-seed the cache on `start()`. Default true. */
+    fetchInitialValues?: boolean;
+    /** Properties to seed when `fetchInitialValues` is true. Default `[]`. */
+    initialProps?: MiotProp[];
+    /** Poll interval (ms) while MQTT is down. Default 30000; 0 disables. */
+    pollIntervalMs?: number;
+    /** Capability set (defaults to the no-op resolver). */
+    capabilities?: DeviceCapabilities;
+}
+/**
+ * A device-type-agnostic live handle for one Dreame device.
+ *
+ * Generic over its event map so subclasses can WIDEN the typed emitter with
+ * their own events (e.g. the vacuum's `'map'` event) without a banned cast.
+ * `Events` is constrained to extend {@link BaseDeviceEvents} so every internal
+ * `emit(...)` call stays type-safe, and it defaults to {@link BaseDeviceEvents}
+ * so a bare `BaseDevice` reference behaves exactly as before.
+ */
+declare class BaseDevice<Events extends BaseDeviceEvents = BaseDeviceEvents> extends TypedEmitter<Events> {
+    #private;
+    constructor(input: BaseDeviceInput);
+    get deviceId(): string;
+    get model(): string;
+    get name(): string;
+    get capabilities(): DeviceCapabilities;
+    /** Snapshot of all cached property states. */
+    get properties(): readonly PropertyState[];
+    /** Read a cached property, or `undefined` if never observed. */
+    getProperty(siid: number, piid: number): PropertyState | undefined;
+    /** The region this handle is bound to. Subclasses use it to build map fetches. */
+    protected get region(): DreameRegion;
+    /** Latest session snapshot. Subclasses use it for out-of-band fetches (maps). */
+    protected currentSession(): DreameSession;
+    /** Open the push, wire events, optionally seed the cache. */
+    start(): Promise<void>;
+    /** Live-read properties, update the cache, return the raw results. */
+    refreshProperties(props: MiotProp[]): Promise<PropertyResult[]>;
+    /** Write a property to the device. */
+    setProperty(write: PropertyWrite): Promise<PropertyResult[]>;
+    /** Invoke a MIoT action on the device. */
+    callAction(siid: number, aiid: number, input?: unknown[]): Promise<unknown>;
+    /** Propagate a refreshed session to the underlying push. */
+    applySession(session: DreameSession): Promise<void>;
+    /** Tear down: stop polling, close the push. */
+    close(): Promise<void>;
+}
+
+/** Args the facade passes to `createDevice` (a seam for tests). */
+interface CreateDeviceArgs {
+    device: DreameDevice;
+    region: DreameRegion;
+    sessionRef: () => DreameSession;
+}
+/** Injectable collaborators — defaults wire the real P1 modules. */
+interface NodreameDeps {
+    login(input: {
+        email: string;
+        password: string;
+        region: DreameRegion;
+        country?: string;
+        lang?: string;
+        fetchImpl?: FetchImpl;
+    }): Promise<DreameSession>;
+    refresh(input: {
+        refreshToken: string;
+        region: DreameRegion;
+        country?: string;
+        lang?: string;
+        fetchImpl?: FetchImpl;
+    }): Promise<DreameSession>;
+    listDevices(input: {
+        session: DreameSession;
+        region: DreameRegion;
+        fetchImpl?: FetchImpl;
+    }): Promise<DreameDevice[]>;
+    createDevice(args: CreateDeviceArgs): BaseDevice;
+}
+type NodreameEvents = {
+    /** Re-emitted device state change, tagged with the deviceId. */
+    stateChanged: [StateChangedEvent];
+    /** Re-emitted device event, tagged with the deviceId. */
+    event: [DeviceEvent];
+    error: [Error];
+};
+/** Public facade for the Dreamehome cloud. */
+declare class Nodreame extends TypedEmitter<NodreameEvents> {
+    #private;
+    constructor(opts: NodreameOptions, deps?: NodreameDeps);
+    get region(): DreameRegion;
+    get session(): DreameSession | null;
+    get devices(): readonly BaseDevice[];
+    /** Authenticate and stash the single shared session. */
+    login(): Promise<DreameSession>;
+    /** Return a valid session, refreshing proactively within the leeway window. */
+    ensureSession(): Promise<DreameSession>;
+    /** Discover devices and build a live handle per device. */
+    discoverDevices(): Promise<readonly BaseDevice[]>;
+    /** Tear everything down: close every device push and clear timers. */
+    close(): Promise<void>;
+}
+
+/**
+ * Vacuum MIoT enum definitions (ported from malard/node-dreame
+ * src/spec/enums.ts, MIT — attribution retained). Only the state/command
+ * enums P3 needs are ported here; dock/schedule enums land in later phases.
+ * Annotations (VERIFIED <date> / ASSUMED from Tasshack) are preserved.
+ */
+/**
+ * VERIFIED on r2532a 2026-05-02 — MIoT STATE (siid 2 piid 1). Sourced from
+ * the device's keyDefine v8 JSON. 19 values verified live across a full
+ * cleaning task; sub-mode: value 1 = vacuum-only, value 12 = vacuum+mop.
+ */
+declare enum MiotState {
+    Cleaning = 1,
+    Standby = 2,
+    Paused = 3,
+    PausedAlt = 4,
+    ReturningToCharge = 5,
+    Charging = 6,
+    Mopping = 7,
+    MopDrying = 8,
+    MopCleaning = 9,
+    ReturningToWash = 10,
+    Mapping = 11,
+    CleaningAlt = 12,
+    ChargingComplete = 13,
+    Updating = 14,
+    CallToClean = 15,
+    AutoRepairBase = 16,
+    ReturnInstallMop = 17,
+    ReturnRemoveMop = 18,
+    WaterSupplyDrainTest = 19,
+    CleanMopRefillWater = 20,
+    PausedCleaning = 21,
+    AutoEmptying = 22,
+    RemoteCleaning = 23,
+    IntelligentCharging = 24,
+    SecondCleaning = 25,
+    Following = 26,
+    PartialCleaning = 27,
+    ReturnToEmpty = 28,
+    WaitingForTask = 29,
+    CleanWashboardBase = 30,
+    AutoWaterDraining = 33,
+    ShortcutRunning = 97,
+    CameraMonitoring = 98,
+    CameraMonitoringPaused = 99,
+    InitialDeepClean = 101
+}
+/** VERIFIED on r2532a 2026-05-02 — ChargingStatus (siid 3 piid 2). */
+declare enum ChargingStatus {
+    Charging = 1,
+    Discharging = 2,
+    Returning = 5
+}
+/** VERIFIED on r2532a 2026-05-02 — SuctionLevel (siid 4 piid 4). X50 labels. */
+declare enum SuctionLevel {
+    Quiet = 0,
+    Standard = 1,
+    Intense = 2,
+    Max = 3
+}
+/** ASSUMED from Tasshack — WaterVolume (siid 4 piid 5). NOT YET verified on r2532a. */
+declare enum WaterVolume {
+    Low = 1,
+    Medium = 2,
+    High = 3
+}
+/**
+ * VERIFIED on r2449a 2026-05-21 — plain 0..3 value space written via
+ * CLEAN_MODE_SETTING (siid 2 piid 6). The raw CLEANING_MODE field (siid 4
+ * piid 23) packs this in its low 2 bits OR'd with a 0x1400 capability mask;
+ * prefer CLEAN_MODE_SETTING to avoid the bitfield trap.
+ */
+declare enum CleaningMode {
+    Sweeping = 0,
+    Mopping = 1,
+    SweepAndMop = 2,
+    MopAfterSweep = 3
+}
+/**
+ * Error / fault value space for ERROR (siid 2 piid 2) and FAULTS_STR
+ * (siid 4 piid 18). VERIFIED members confirmed live on r2532a; the rest are
+ * ASSUMED from Tasshack types.py — the integer is the source of truth.
+ */
+declare enum MiotError {
+    Clear = 0,
+    WheelRotationAnomaly = 1,
+    RobotLifted = 18,
+    TaskComplete = 68,
+    ManualMopInstallRequired = 74,
+    WastewaterTankFull = 105,
+    CleanWaterTankEmpty = 107,
+    WashboardFilterNeedsCleaning = 114,
+    MopPadsMissing = 120,
+    BatteryLow = 20,
+    ChargeFault = 21,
+    BatteryPercentageAnomaly = 22,
+    ChargeNoElectric = 28,
+    BatteryFault = 29,
+    LowBatteryTurnOff = 75,
+    RobotStuck = 80,
+    RobotStuckRepeat = 81,
+    RobotStuck2 = 90,
+    RobotStuckOnTables = 91,
+    RobotStuckOnPassage = 92,
+    RobotStuckOnThreshold = 93,
+    RobotStuckOnLowLyingArea = 94,
+    RobotStuckOnRamp = 95,
+    RobotStuckOnObstacle = 96,
+    RobotStuckOnPet = 97,
+    RobotStuckOnSlipperySurface = 98,
+    RobotStuckOnCarpet = 99,
+    RobotStuckOnCurtain = 200,
+    BinFull = 101,
+    StationDisconnected = 117,
+    DustBagFull = 121
+}
+/** VERIFIED on r2532a 2026-05-02 — TASK_STATUS (siid 4 piid 1). */
+declare enum TaskStatus {
+    InterruptedOrPaused = 1,
+    Active = 2,
+    Transitioning = 3,
+    OnDockIdle = 6,
+    TransientPauseEdge = 12,
+    NeedsIntervention = 14
+}
+
+/**
+ * Per-model vacuum capability records (ported from malard/node-dreame
+ * src/capabilities.ts, MIT — attribution retained) plus a resolver that
+ * adapts the rich record into the generic CapabilityResolver the BaseDevice
+ * expects. r2538z is added mirroring r2532a (X50 sibling), marked unverified
+ * until live-confirmed.
+ */
+
+/** Rich vacuum capability record. `canX` = behaviour, `hasX` = hardware. */
+interface VacuumCapabilities {
+    model: string;
+    /** true when the record came from the curated table (false = fallback / assumed). */
+    verified: boolean;
+    canMop: boolean;
+    canAutoInstallMop: boolean;
+    hasSideBrush: boolean;
+    hasCamera: boolean;
+    hasCarpetSensor: boolean;
+    hasAiObstacleDetection: boolean;
+    canAutoEmpty: boolean;
+    canMopWash: boolean;
+    canMopDry: boolean;
+    canHeatMopWater: boolean;
+    hasDetergentReservoir: boolean;
+    canCleanPerRoom: boolean;
+    supportsVirtualWalls: boolean;
+    supportsNoGoZones: boolean;
+    hasChildLock: boolean;
+    supportsMultiFloor: boolean;
+    /** Decodes/fetches the binary live/saved map (envelope → pixel grid → segments). */
+    canMap: boolean;
+    supportedSuctionLevels: readonly SuctionLevel[];
+    supportedWaterVolumes: readonly WaterVolume[];
+}
+declare const MODEL_CAPABILITIES$1: Readonly<Record<string, VacuumCapabilities>>;
+/** Resolve a model to its rich vacuum capability record (frozen / fallback). */
+declare function getVacuumCapabilities(model: string): VacuumCapabilities;
+/** Resolver that the BaseDevice accepts via BaseDeviceInput.capabilities. */
+declare class VacuumCapabilityResolver implements CapabilityResolver {
+    resolve(model: string): DeviceCapabilities;
+}
+
+/**
+ * Public types for the live-map decoder.
+ *
+ * All coordinates are millimetres in the device's world frame, exactly as
+ * Dreame's binary encodes them — no Y-flip, no centimetre rescale, no
+ * origin shift. The consumer is expected to apply whichever transform
+ * fits its rendering library. This is a deliberate departure from the
+ * Valetudo schema; see `docs/live-map-format.md` for the rationale.
+ */
+/** Frame type byte from the 27-byte map header. */
+type MapFrameType = 'I' | 'P' | 'W';
+/** Cleaning-path op classes — the four `tr` regex ops collapsed into named runs. */
+type MapPathType = 'mop' | 'sweep' | 'sweep-and-mop' | 'line';
+/**
+ * Pixel-grid layer kind. `wall`, `floor`, and `segment` are mutually
+ * exclusive primary classifications — one per pixel. `carpet` is an
+ * independent overlay (low-bits=11 in fsm:1 path B): a carpet pixel
+ * also has a primary classification, and the renderer paints the carpet
+ * texture on top of whatever colour the underlying layer chose.
+ */
+type MapLayerType = 'wall' | 'floor' | 'segment' | 'carpet';
+interface MapPose {
+    /** mm, world-frame. */
+    x: number;
+    /** mm, world-frame. */
+    y: number;
+    /** Degrees. Raw — the renderer applies `VacuumMap.rotation` if it cares. */
+    angle: number;
+}
+interface MapDimensions {
+    /** mm, world-x of pixel column 0. */
+    left: number;
+    /** mm, world-y of pixel row 0. */
+    top: number;
+    /** Pixels. */
+    width: number;
+    /** Pixels. */
+    height: number;
+    /** mm per pixel. */
+    gridSize: number;
+}
+interface MapBoundingBox {
+    /** mm. */
+    xMin: number;
+    /** mm. */
+    yMin: number;
+    /** mm. */
+    xMax: number;
+    /** mm. */
+    yMax: number;
+}
+interface MapPoint {
+    /** mm. */
+    x: number;
+    /** mm. */
+    y: number;
+}
+/**
+ * One run of consecutive same-class pixels on a single row, encoded as
+ * `[xPixel, yPixel, length]` in pixel-space (multiply by `gridSize` and
+ * add `left`/`top` to project to mm world-frame).
+ */
+type MapRun = [number, number, number];
+interface MapLayer {
+    type: MapLayerType;
+    /** Set when `type === "segment"`. Range 1..63. */
+    segmentId?: number;
+    readonly runs: readonly MapRun[];
+}
+interface MapSegment {
+    /** Segment id from the pixel grid (1..63). */
+    id: number;
+    /**
+     * User-given room name. Already decoded from the wire format's
+     * base64 — use as-is, do NOT double-decode.
+     *
+     * `null` when `seg_inf.<id>.name` was missing entirely. Empty-string
+     * (`""`) when the user has not named the room — observed live on
+     * r2532a 2026-05-07 when no rooms were named in the Dreamehome app.
+     * Renderers that fall back via `s.name || \`Room ${s.id}\`` work
+     * correctly for both because both are falsy in JS, but a
+     * strict-null-only check (`s.name === null ? … : s.name`) would
+     * render visible empty labels.
+     */
+    name: string | null;
+    /** mm, world-frame, derived from the pixel scan. */
+    bbox: MapBoundingBox;
+    /** mm, world-frame — useful as a label-anchor point. */
+    centroid: MapPoint;
+    /** Adjacent segment ids from `seg_inf.<id>.nei_id`. */
+    readonly neighbours: readonly number[];
+    /** Floor material code from `seg_inf.<id>.material`. */
+    floorMaterial: number | null;
+    /** Floor direction code from `seg_inf.<id>.direction`. */
+    floorDirection: number | null;
+    /** Whether this segment is in the current cleaning set (`sa`). */
+    active: boolean;
+}
+interface MapPath {
+    type: MapPathType;
+    /** mm, world-frame. */
+    readonly points: readonly MapPoint[];
+}
+interface MapObstacle {
+    /** Per-obstacle id from `ai_obstacle`. */
+    id: number;
+    /** mm, world-frame. */
+    x: number;
+    /** mm, world-frame. */
+    y: number;
+    /**
+     * `ObstacleType` enum value — carried through unchanged. The browser
+     * decodes the integer to a label; node-dreame doesn't ship the lookup
+     * table because Dreame revises it per firmware.
+     */
+    type: number;
+    /** 0..100 — Dreame's own confidence percentage. */
+    confidence: number;
+    /** When the device captured a photo of the obstacle, the OSS file name. */
+    photoFileName: string | null;
+    /** AES key for photo decryption — separate from the map blob's key. */
+    photoKey: string | null;
+}
+/**
+ * One user-defined wall-shaped piece of geometry — a line segment in
+ * mm world-frame. Includes both classic virtual walls (`vw.line`) and
+ * the X50's threshold variants (`vws.vwsl` / `vws.npthrsd`); the
+ * `kind` and `passable` fields discriminate.
+ *
+ * `kind` defaults to `"wall"` when absent — older callers that
+ * pre-date the threshold split don't have to update.
+ *
+ * Threshold semantics (Tasshack `dev` `map.py:4678-4691`):
+ *   - `kind: "threshold", passable: true`   — passable threshold (X50 firmware
+ *     where the user has separately configured the impassable set)
+ *   - `kind: "threshold", passable: false`  — impassable threshold
+ *   - `kind: "threshold"` (no passable)     — "virtual" threshold from
+ *     older firmware that doesn't split passable/impassable
+ *   - `kind: "wall"` (or absent)            — classic virtual wall (`vw.line`)
+ */
+interface MapVirtualWall {
+    from: MapPoint;
+    to: MapPoint;
+    /** Defaults to `"wall"` when absent. */
+    kind?: 'wall' | 'threshold';
+    /** Only meaningful when `kind === "threshold"`. */
+    passable?: boolean;
+}
+/**
+ * One axis-aligned restricted area — either a no-go zone (`vw.rect`,
+ * `kind: "noGo"`) or a no-mop zone (`vw.mop`, `kind: "noMop"`).
+ *
+ * The wire format carries only two opposing corners; this struct
+ * normalises them into a `MapBoundingBox`. The optional `angle`
+ * mirrors a fifth element Dreame sometimes appends (rotation hint —
+ * the rectangle itself remains axis-aligned in the wire format).
+ */
+interface MapRestrictedArea {
+    kind: 'noGo' | 'noMop';
+    bbox: MapBoundingBox;
+    /** Optional rotation hint from the wire format — degrees, may be undefined. */
+    angle?: number;
+}
+/**
+ * One wall segment from the per-room wall geometry — present on
+ * saved maps as `walls_info.storeys[*].rooms[*].walls[*]`.
+ *
+ * `type` discriminates the wall variant; observed values on r2532a:
+ *   `0` — solid wall
+ *   `1` — opening / doorway
+ * Surfaced as-emitted; consumers can ignore or render selectively.
+ *
+ * `normal` is the unit-vector pointing into the room's interior on
+ * the wire (each component typically `-1`, `0`, or `1`).
+ */
+interface MapRoomWall {
+    type: number;
+    from: MapPoint;
+    to: MapPoint;
+    normal: MapPoint;
+}
+/**
+ * One room's wall list inside `walls_info.storeys[*].rooms[*]`.
+ * `roomId` matches a segment id from the pixel grid where present
+ * (some captures show roomIds outside the 1..63 segment range, so do
+ * NOT assume a 1:1 mapping at the consumer layer).
+ */
+interface MapRoom {
+    roomId: number;
+    walls: readonly MapRoomWall[];
+}
+/**
+ * One floor's worth of rooms inside `walls_info.storeys[*]`.
+ * Single-floor homes have exactly one storey; multi-floor would have
+ * one entry per floor. `VacuumMap.wallsInfo` carries only the storey
+ * matching the current `mapId`.
+ */
+interface MapStorey {
+    rooms: readonly MapRoom[];
+}
+/**
+ * Per-room wall geometry from the saved-map blob's `walls_info`
+ * field. Big and only present on saved maps (not live I-frames).
+ *
+ * `versionFlag` is the wire's `version_flag` int — surfaced
+ * unchanged in case the schema evolves.
+ */
+interface MapWallsInfo {
+    versionFlag: number;
+    storeys: readonly MapStorey[];
+}
+/**
+ * One user-defined low-clearance "sneak under furniture" zone — the
+ * X50 retracts its tower while passing through. Surfaced from the
+ * tail's `sneak_areas` / `sneak_areas_end` field (Tasshack `dev`
+ * `map.py:4776-4809`).
+ *
+ * The wire format is a polygon: `roi` is an even-length list of
+ * alternating `x0, y0, x1, y1, …` ints in mm world-frame. On
+ * r2532a 2026-05-07 every observed entry was a 4-corner rect (8
+ * ints) — but the Tasshack reference parses arbitrary even lengths,
+ * so we surface the points as-emitted rather than coercing to a
+ * bounding box.
+ */
+interface MapLowLyingArea {
+    /** Stable id from the wire format (for cross-frame correlation). */
+    id: number;
+    /** Polygon vertices in mm, world-frame. */
+    points: readonly MapPoint[];
+    /** Floor area in m² — present when the device emitted `sneak_areas_end`. */
+    area?: number;
+}
+/**
+ * Cleaned-area overlay decoded from the JSON tail's `decmap` field.
+ *
+ * `decmap` is a recursive blob — a full inner map envelope (header +
+ * zlib + JSON tail) embedded as a base64 string in the parent tail.
+ * Its pixel grid uses only the low 2 bits (`& 0x03`): `1 = cleaned`,
+ * `2 = dirty`. The inner grid has its own dimensions, independent of
+ * the parent map; the renderer reprojects onto the parent's pixel
+ * grid using the dimensions below.
+ *
+ * Both `cleaned` and `dirty` are run-length encoded the same way as
+ * `MapLayer.runs` — `[xPixel, yPixel, length]` in the inner grid's
+ * pixel-space.
+ *
+ * `cleanedSegments` carries the inner tail's `CleanArea` field when
+ * present (per-segment cleaned-area stats). Shape varies per firmware
+ * so it's surfaced as opaque.
+ */
+interface MapCleanedAreaOverlay {
+    /** Inner blob's own dimensions — independent of the parent map's. */
+    dimensions: MapDimensions;
+    /** Pixels marked `cleaned` (low-bits == 1) in the inner grid. */
+    readonly cleaned: readonly MapRun[];
+    /** Pixels marked `dirty` (low-bits == 2) in the inner grid. */
+    readonly dirty: readonly MapRun[];
+    /** Optional per-segment cleaned-area stats from the inner JSON tail. */
+    cleanedSegments?: unknown;
+}
+/**
+ * The decoded map. Coordinates throughout are mm in the device's world
+ * frame. The renderer transforms once when projecting onto its own
+ * canvas — see `dimensions` for the parent grid origin / scale.
+ */
+interface VacuumMap {
+    mapId: number;
+    frameId: number;
+    frameType: MapFrameType;
+    /** ms since epoch, from JSON tail's `timestamp_ms`. */
+    timestamp: number;
+    /** Degrees from JSON tail's `mra` — applied by the renderer if it rotates. */
+    rotation: number;
+    dimensions: MapDimensions;
+    robot: MapPose | null;
+    dock: MapPose | null;
+    docked: boolean;
+    readonly layers: readonly MapLayer[];
+    readonly segments: readonly MapSegment[];
+    readonly paths: readonly MapPath[];
+    readonly obstacles: readonly MapObstacle[];
+    /**
+     * Line-segment walls and threshold variants. Empty array when none
+     * configured. Each entry's `kind` (defaults to `"wall"` when absent)
+     * and `passable` discriminate classic virtual walls (`vw.line`)
+     * from passable / impassable / virtual thresholds (`vws.vwsl` /
+     * `vws.npthrsd`). See `MapVirtualWall`.
+     */
+    readonly virtualWalls: readonly MapVirtualWall[];
+    /**
+     * Axis-aligned restricted areas — both no-go (`vw.rect`, `vw.nocpt`)
+     * and no-mop (`vw.mop`).
+     */
+    readonly restrictedAreas: readonly MapRestrictedArea[];
+    /**
+     * Low-clearance "sneak under furniture" zones from `sneak_areas` /
+     * `sneak_areas_end`. Empty array when none configured.
+     */
+    readonly lowLyingAreas: readonly MapLowLyingArea[];
+    /**
+     * Per-room wall geometry from the saved-map blob's `walls_info`.
+     * `null` on live I-frames that don't carry the field — only
+     * populated when the parent frame has a saved-map blob to mine
+     * from (or is itself the saved-map blob).
+     */
+    readonly wallsInfo: MapWallsInfo | null;
+    /**
+     * Cleaning progress map embedded in the parent frame, decoded from
+     * the recursive `decmap` blob. `null` when the parent didn't carry
+     * one (typical for live-stream frames; the device emits `decmap`
+     * mainly on full-snapshot pushes).
+     */
+    cleanedArea: MapCleanedAreaOverlay | null;
+}
+
+/**
+ * Raster PNG renderer for a decoded `VacuumMap`.
+ *
+ * node-dreame ships only the structured model (no image); this is NEW. We paint
+ * one pixel per grid cell (× an optional integer upscale `scale`) from the
+ * run-length `layers`, later layers painting over earlier ones. The background
+ * is transparent. Per-segment colours come from a deterministic golden-angle
+ * palette so the same room id always renders the same hue.
+ *
+ * Pure: only `pngjs` + arithmetic. No casts.
+ */
+
+interface RenderVacuumPngOptions {
+    /** Integer upscale factor (nearest-neighbour). Default 1. */
+    scale?: number;
+}
+declare function renderVacuumPng(map: VacuumMap, opts?: RenderVacuumPngOptions): Buffer;
+
+/**
+ * Resolve a Dreame OSS object name (advertised via the PATH push,
+ * `siid 6 piid 3`) to a signed download URL and fetch the blob.
+ *
+ * Endpoint: `POST /dreame-user-iot/iotfile/getDownloadUrl`
+ * Body:     `{ did, model, filename, region }`
+ * Response: `{ code: 0, data: "<signed-url-string>" }` — `data` is the
+ *           URL string itself, not a nested `{ url }` object.
+ *
+ * The signed URL is good for ~1 hour (Aliyun signature). We cache it
+ * for 30 min by default and on cache hit append `current=<unix_ts>` to
+ * bust any intermediate caches (Tasshack convention).
+ *
+ * v1 only handles live blobs (the I-frame parked in OSS by the device).
+ * Permanent saved-map blobs use a different filename mangling — deferred.
+ *
+ * ADAPTED from node-dreame's `src/map/oss-fetch.ts`: the only changes are
+ * import-path rewrites onto our transport (`RequestContext`/`httpPostJson`
+ * from `transport/http`, `DreameApiError`/`DreameTransportError` from
+ * `transport/errors`, `DreameRegion` from `auth/config`) and typing the
+ * injected fetch seam as our `FetchImpl` (undici-backed) rather than the
+ * donor's global `typeof fetch` — so the mock type-checks with no cast.
+ */
+
+interface OssFetchInput {
+    /** Resolved API host (e.g. `eu.iot.dreame.tech:13267`). */
+    host: string;
+    /** Bearer token from the active `DreameSession`. */
+    accessToken: string;
+    /** Region — used for header construction and the body's `region` field. */
+    region: DreameRegion;
+    /** Optional `country` override for headers (defaults from region). */
+    country?: string;
+    /** Optional `lang` override for headers (defaults from region). */
+    lang?: string;
+    /** Device id. */
+    did: string;
+    /** Device model. */
+    model: string;
+    /** OSS object name (`ali_dreame/<uid>/<did>/<n>`). */
+    filename: string;
+    /** Caller-supplied AbortSignal — composed with the HTTP timeout. */
+    signal?: AbortSignal;
+    /** Per-request timeout override in ms. Pass `0` to disable. */
+    timeoutMs?: number;
+}
+/**
+ * Minimal fetcher seam consumed by `VacuumDevice.getMap`. Lets callers
+ * inject a custom signed-blob fetcher (e.g. a cache-backed or proxied one)
+ * without depending on the concrete {@link OssFetcher} class. The real
+ * {@link OssFetcher} implements this interface.
+ */
+interface OssFetcherLike {
+    fetchBlob(input: OssFetchInput): Promise<Buffer>;
+}
+
+/** Knobs for the segment/zone/spot helpers. Defaults pull from cached state. */
+interface CleanOpts {
+    repeats?: number;
+    fan?: number;
+    water?: number;
+}
+/**
+ * The vacuum widens the {@link BaseDeviceEvents} map with a `'map'` event,
+ * emitted by {@link VacuumDevice.getMap} once a fresh map has been decoded.
+ * Declaring it here lets `VacuumDevice extends BaseDevice<VacuumDeviceEvents>`
+ * type the emitter with no banned cast.
+ */
+type VacuumDeviceEvents = BaseDeviceEvents & {
+    map: [VacuumMap];
+};
+/** Input to {@link VacuumDevice.getMap}. */
+interface VacuumGetMapInput {
+    /** OSS object name advertised via the PATH push (siid 6 piid 3). */
+    filename: string;
+    /**
+     * Inject the signed-blob fetcher (tests pass a fake). Defaults to a fresh
+     * {@link OssFetcher}. Typed as {@link OssFetcherLike} so consumers can pass
+     * any object exposing a compatible `fetchBlob`.
+     */
+    fetcher?: OssFetcherLike;
+    /** Optional AES key for an encrypted blob (hex). */
+    key?: string;
+    /** Optional AES IV for an encrypted blob (hex). */
+    iv?: string;
+    /** Override the API host (defaults from the device region). */
+    host?: string;
+    /** Per-request timeout override in ms. */
+    timeoutMs?: number;
+    /** Caller-supplied AbortSignal. */
+    signal?: AbortSignal;
+}
+/** A typed Dreame-vacuum handle (state + capability-gated commands). */
+declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
+    #private;
+    constructor(input: BaseDeviceInput);
+    /** Rich, vacuum-specific capability record (booleans + supported enums). */
+    get vacuumCapabilities(): VacuumCapabilities;
+    get statusRaw(): number | null;
+    get status(): MiotState | null;
+    get battery(): number | null;
+    get chargingRaw(): number | null;
+    get charging(): ChargingStatus | null;
+    get isCharging(): boolean;
+    /** Docked => MiotState Charging or ChargingComplete (on the dock). */
+    get isDocked(): boolean;
+    get suctionRaw(): number | null;
+    get suction(): SuctionLevel | null;
+    get waterRaw(): number | null;
+    get water(): WaterVolume | null;
+    /** Reads the SAFE CLEAN_MODE_SETTING (siid 2 piid 6), plain 0-3. */
+    get cleaningModeRaw(): number | null;
+    get cleaningMode(): CleaningMode | null;
+    get taskStatusRaw(): number | null;
+    get taskStatus(): TaskStatus | null;
+    get errorCode(): number | null;
+    get faults(): readonly number[];
+    get taskProgressPct(): number | null;
+    get mainBrushLeftPct(): number | null;
+    get sideBrushLeftPct(): number | null;
+    get filterLeftPct(): number | null;
+    get volume(): number | null;
+    /**
+     * Start cleaning (MIoT action siid 2 aiid 1). Named `startCleaning` — NOT
+     * `start` — because `BaseDevice.start()` is the lifecycle method that opens
+     * the MQTT push, and the facade relies on that meaning. Donor `node-dreame`
+     * names this `start()` only because its standalone `Vacuum` class owns no
+     * lifecycle method to collide with.
+     */
+    startCleaning(): Promise<unknown>;
+    pause(): Promise<unknown>;
+    stop(): Promise<unknown>;
+    /** Return to the dock / charge (MIoT action CHARGE, siid 3 aiid 1). */
+    dock(): Promise<unknown>;
+    locate(): Promise<unknown>;
+    clearWarning(): Promise<unknown>;
+    startAutoEmpty(): Promise<unknown>;
+    /** Type-safe suction write. Validates against the model's supported levels. */
+    setSuction(level: SuctionLevel): Promise<unknown>;
+    /**
+     * Untyped suction write: validates an arbitrary number against the model's
+     * supported levels and rejects with `RangeError` on an invalid input. This
+     * is the raw-input entry point so callers (and tests) can exercise validation
+     * with no type assertions. `async` so the guard surfaces as a rejection.
+     */
+    setSuctionRaw(level: number): Promise<unknown>;
+    /** Type-safe water-volume write. Validates against supported volumes. */
+    setWater(volume: WaterVolume): Promise<unknown>;
+    /** Untyped water-volume write: validates an arbitrary number (zero casts). */
+    setWaterRaw(volume: number): Promise<unknown>;
+    /** SAFE clean-mode write — uses CLEAN_MODE_SETTING (siid 2 piid 6), never the 0x1400 bitfield. */
+    setCleaningMode(mode: CleaningMode): Promise<unknown>;
+    cleanSegments(ids: number[], opts?: CleanOpts): Promise<unknown>;
+    cleanZones(zones: Array<{
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    }>, opts?: CleanOpts): Promise<unknown>;
+    /**
+     * Send the robot to clean a single point (the SPOT custom-clean action,
+     * mode 20). ASSUMED: Tasshack's "go to point" is the same SPOT action — this
+     * is exposed as `cleanSpot` because it maps to the spot/custom-clean action,
+     * not a distinct go-to. No separate `goTo` is exposed.
+     */
+    cleanSpot(point: {
+        x: number;
+        y: number;
+    }, opts?: CleanOpts): Promise<unknown>;
+    /** The most-recently-decoded map, or `null` until {@link getMap} succeeds. */
+    get lastMap(): VacuumMap | 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
+     * segment is currently active. REPLACES the P3 "intentionally not exposed"
+     * placeholder — the value now comes from the decoded map layer (P5).
+     */
+    get currentSegmentId(): number | null;
+    /**
+     * Fetch the current saved/live-map blob (OSS), decode it, cache it as
+     * {@link lastMap}, emit a `'map'` event, and return the {@link VacuumMap}.
+     *
+     * Capability-gated on `canMap`. The `filename` is the OSS object name the
+     * caller resolves from a `mapInfo`/PATH push. The fetcher is injectable so
+     * tests drive it with a synthetic blob and no live network.
+     *
+     * NOTE: active live-frame P-frame STREAMING (continuous merge orchestration)
+     * is a documented follow-up; `getMap` resolves a single frame here. The
+     * `applyVacuumPFrame` merge primitive ships separately for that work.
+     */
+    getMap(input: VacuumGetMapInput): Promise<VacuumMap>;
+    /** Props worth seeding on start() / polling — exported for the facade. */
+    static readonly DEFAULT_PROPS: readonly [{
+        readonly siid: 2;
+        readonly piid: 1;
+    }, {
+        readonly siid: 2;
+        readonly piid: 2;
+    }, {
+        readonly siid: 4;
+        readonly piid: 18;
+    }, {
+        readonly siid: 4;
+        readonly piid: 1;
+    }, {
+        readonly siid: 4;
+        readonly piid: 4;
+    }, {
+        readonly siid: 4;
+        readonly piid: 5;
+    }, {
+        readonly siid: 2;
+        readonly piid: 6;
+    }, {
+        readonly siid: 4;
+        readonly piid: 63;
+    }, {
+        readonly siid: 3;
+        readonly piid: 1;
+    }, {
+        readonly siid: 3;
+        readonly piid: 2;
+    }, {
+        readonly siid: 9;
+        readonly piid: 2;
+    }, {
+        readonly siid: 10;
+        readonly piid: 2;
+    }, {
+        readonly siid: 11;
+        readonly piid: 1;
+    }, {
+        readonly siid: 7;
+        readonly piid: 1;
+    }];
+}
+
+/**
+ * Mower MIoT enum value spaces, reverse-engineered from antondaubert/dreame-mower
+ * (const.py DeviceStatus + STATUS_MAPPING + CHARGING_STATUS_MAPPING, and
+ * property/mower_control.py + service5.py). The donor is a working HA
+ * integration, so these are VERIFIED-by-donor; members annotated ASSUMED are
+ * not yet corroborated. The integer is always the source of truth.
+ */
+/** VERIFIED-by-donor — STATUS_PROPERTY (siid 2 piid 1), const.py DeviceStatus. */
+declare enum MowerStatus {
+    NoStatus = 0,
+    Mowing = 1,
+    Standby = 2,
+    Paused = 3,
+    PausedDueToErrors = 4,
+    ReturningToCharge = 5,
+    Charging = 6,
+    Mapping = 11,
+    ChargingComplete = 13,
+    Updating = 14
+}
+/** VERIFIED-by-donor — CHARGING_STATUS_PROPERTY (siid 3 piid 2), CHARGING_STATUS_MAPPING. */
+declare enum MowerChargingStatus {
+    NotDocked = 0,
+    Charging = 1,
+    NotCharging = 2,
+    ChargingCompleted = 3,
+    ReturnToCharge = 5,
+    /** Charging paused: battery temperature too low (donor issue #40). */
+    ChargingPausedLowTemperature = 16
+}
+/**
+ * VERIFIED-by-donor — per-zone control code in MOWER_CONTROL_STATUS (siid 2
+ * piid 56) `status` array entries `[zone_id, code]`. mower_control.py.
+ */
+declare enum MowerControlAction {
+    /** Zone waiting in a multi-zone session. */
+    Queued = -1,
+    /** Actively mowing. */
+    Continue = 0,
+    Completed = 2,
+    Pause = 4
+}
+/**
+ * Observed TASK_STATUS codes (siid 5 piid 104), service5.py TASK_STATUS_MAPPING.
+ * Only `SpotIncomplete` (7) has a confirmed meaning; the others in the donor are
+ * "Unknown task status: N" — ASSUMED / not exposed as named members here.
+ */
+declare enum MowerTaskStatus {
+    /** "Task incomplete - spot mowing". */
+    SpotIncomplete = 7
+}
+
+/**
+ * Cast-free mower decoders. Re-exports the shared numeric primitives, and adds
+ * the two structured-payload parsers the typed getters consume:
+ *   - parseTaskDescriptor : SCHEDULING_TASK (2:50) {t,d:{...}} -> typed task
+ *   - parseControlStatus  : MOWER_CONTROL_STATUS (2:56) {status:[[zone,code]]}
+ * Ported from antondaubert/dreame-mower property/{scheduling,mower_control}.py.
+ * The binary pose-track geometry (1:4) is OUT OF SCOPE here (P5).
+ */
+
+/** Typed scheduling task descriptor (subset of the donor TaskHandler fields). */
+interface MowerTaskDescriptor {
+    taskType: string;
+    executionActive: boolean;
+    /** `d.o` — coverage target % or mode sentinel. */
+    coverageTarget: number;
+    taskActive: boolean;
+    areaId: number[] | null;
+    regionId: number[] | null;
+    elapsedTime: number | null;
+}
+/** Typed mower control status (2:56). */
+interface MowerControlState {
+    action: MowerControlAction | null;
+    statusCode: number | null;
+    zones: number[][];
+}
+
+/**
+ * Per-model mower capability records + a resolver adapting the rich record into
+ * the generic CapabilityResolver the BaseDevice expects (mirrors the vacuum
+ * capability layer). The donor (antondaubert/dreame-mower) has no per-model
+ * capability matrix for mowers, so the targeted-mowing flags are ASSUMED working
+ * hypotheses from the donor command surface; verified:false until live-checked.
+ */
+
+/** Rich mower capability record. `canX` = behaviour the model accepts. */
+interface MowerCapabilities {
+    model: string;
+    /** true only for live-confirmed records (false = assumed / fallback). */
+    verified: boolean;
+    /** Zone-selective mowing (2:50 o:102). */
+    canMowZones: boolean;
+    /** Edge / contour mowing (2:50 o:101). */
+    canMowEdges: boolean;
+    /** Spot mowing (2:50 o:103). */
+    canMowSpots: boolean;
+    /** All-area, map-targeted start (2:50 o:100). */
+    canMowAllArea: boolean;
+    /** Resume after pause (2:50 o:5). Generic to the mower action surface. */
+    canResume: boolean;
+    /** Has a scheduling task descriptor (2:50). */
+    canSchedule: boolean;
+    /** Fetches/parses the batched vector map (MAP.* JSON → zones/paths/contours). */
+    canMap: boolean;
+}
+declare const MODEL_CAPABILITIES: Readonly<Record<string, MowerCapabilities>>;
+/** Resolve a model to its rich mower capability record (frozen / fallback). */
+declare function getMowerCapabilities(model: string): MowerCapabilities;
+/** Resolver the BaseDevice accepts via BaseDeviceInput.capabilities. */
+declare class MowerCapabilityResolver implements CapabilityResolver {
+    resolve(model: string): DeviceCapabilities;
+}
+
+/**
+ * Structured model for the mower vector map.
+ *
+ * PORT of the `@dataclass` definitions in antondaubert/dreame-mower's
+ * `map_data_parser.py` (`MowerZone`, `MowerPath`, `MowerContour`,
+ * `MowerSpotArea`, `MowerAvailableMap`, `MowerMapBoundary`, `MowerMowPath`,
+ * `MowerVectorMap`) re-typed as TypeScript interfaces with camelCase fields.
+ *
+ * Defaults are applied by the parser (Task 5.15), NOT by the type. Coordinate
+ * points are kept as `{ x, y }` objects (not tuples) to mirror the vacuum
+ * map's `MapPoint` and keep the public API ergonomic; the parser converts the
+ * wire `{ x, y }` shape directly.
+ */
+/** A single coordinate point in mower map units. */
+interface MowerPoint {
+    x: number;
+    y: number;
+}
+/** A mowing zone defined by a polygon boundary. */
+interface MowerZone {
+    zoneId: number;
+    path: readonly MowerPoint[];
+    name: string;
+    zoneType: number;
+    shapeType: number;
+    area: number;
+    time: number;
+    etime: number;
+}
+/** A spot-mowing area defined by a polygon boundary. */
+interface MowerSpotArea {
+    areaId: number;
+    path: readonly MowerPoint[];
+    name: string;
+    shapeType: number;
+    area: number;
+}
+/** A navigation path between zones. */
+interface MowerPathEntry {
+    pathId: number;
+    path: readonly MowerPoint[];
+    pathType: number;
+}
+/** A contour entry used for boundary or edge mowing. */
+interface MowerContour {
+    contourId: readonly [number, number];
+    path: readonly MowerPoint[];
+    contourType: number;
+    shapeType: number;
+}
+/** Bounding box for the entire map. */
+interface MowerMapBoundary {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Mowing-path trace — the actual trail the mower followed. */
+interface MowerMowPath {
+    zoneId: number;
+    segments: readonly (readonly MowerPoint[])[];
+}
+/** A discovered map that can be targeted by map-aware mowing tasks. */
+interface MowerAvailableMap {
+    mapId: number;
+    mapIndex: number;
+    name: string;
+    totalArea: number;
+}
+/** Complete vector map data for a mower, parsed from the batch API. */
+interface MowerMap {
+    zones: readonly MowerZone[];
+    spotAreas: readonly MowerSpotArea[];
+    forbiddenAreas: readonly MowerZone[];
+    paths: readonly MowerPathEntry[];
+    contours: readonly MowerContour[];
+    boundary: MowerMapBoundary | null;
+    totalArea: number;
+    name: string;
+    mapId: number;
+    mapIndex: number;
+    mowPaths: readonly MowerMowPath[];
+    availableMaps: readonly MowerAvailableMap[];
+    currentMapId: number | null;
+    lastUpdated: number | null;
+}
+
+/**
+ * Deterministic SVG renderer for a structured `MowerMap`.
+ *
+ * ADAPT of antondaubert/dreame-mower's `svg_map_generator.py` — only the
+ * geometry path is kept. We port `calculate_bounds`, `coord_to_pixel`
+ * (aspect-preserving, Y-flipped, centred), `svg_polygon` (≥3 points),
+ * `svg_path_from_segments` (M/L with consecutive-pixel dedupe), and the
+ * `create_svg_document`/`finish_svg_document` framing.
+ *
+ * The HA-coordinator-coupled chrome (legend, status overlay, timestamp, title,
+ * historical-file handling, rotation-from-coordinator, live-tracking overlay,
+ * mower-position circle) is DROPPED — it depends on a `coordinator`, a file
+ * path and live device state we don't carry. The renderer takes only a
+ * `MowerMap` + optional `{ width, height, padding }`.
+ *
+ * Zone `name`s are NOT rendered as text in v1 (keeps the output injection-safe
+ * and minimal — no untrusted strings reach the SVG). Pure string building, no
+ * deps, cast-free.
+ */
+
+interface RenderMowerSvgOptions {
+    /** Canvas width in pixels. Default 1200. */
+    width?: number;
+    /** Canvas height in pixels. Default 1200. */
+    height?: number;
+    /** Padding around the map content in pixels. Default 50. */
+    padding?: number;
+}
+/**
+ * Render a `MowerMap` into a deterministic SVG document string.
+ *
+ * Draw order (back to front): background, nav paths (dashed grey), zone fills
+ * (per-zone pastel), zone outlines, mow-path tracks (orange), forbidden-area
+ * polygons (red). An empty map renders a centred "No map data available"
+ * fallback inside a closed `<svg>`.
+ */
+declare function renderMowerSvg(map: MowerMap, opts?: RenderMowerSvgOptions): string;
+
+/**
+ * Injectable batch-fetch seam. Given a device id + the batch property groups
+ * (e.g. `['MAP','M_PATH']`), resolves the raw `{ 'MAP.0': …, 'MAP.info': … }`
+ * chunk dict the firmware returns. The default wires `getBatchDeviceDatas` from
+ * the cloud layer — but its live endpoint path is NOT yet recovered (see
+ * `cloud/commands.ts`), so production callers MUST inject a working fetcher.
+ * Tests inject a fake with no cast.
+ */
+type BatchDeviceDataFetcher = (did: string, props: string[]) => Promise<Record<string, unknown>>;
+/** Mower-specific construction input: adds the injectable batch-fetch seam. */
+interface MowerDeviceInput extends BaseDeviceInput {
+    /** Inject the batched device-data fetcher (maps). Tests pass a fake. */
+    getBatchDeviceDatas?: BatchDeviceDataFetcher;
+}
+/** A typed Dreame-mower handle (state + capability-gated commands). */
+declare class MowerDevice extends BaseDevice {
+    #private;
+    constructor(input: MowerDeviceInput);
+    /** Rich, mower-specific capability record. */
+    get mowerCapabilities(): MowerCapabilities;
+    get statusRaw(): number | null;
+    get status(): MowerStatus | null;
+    get battery(): number | null;
+    get chargingRaw(): number | null;
+    get charging(): MowerChargingStatus | null;
+    /** Docked => on the dock (Charging / ChargingComplete state). */
+    get isDocked(): boolean;
+    get isMowing(): boolean;
+    get taskStatusRaw(): number | null;
+    /** Parsed scheduling task descriptor (2:50), or null. */
+    get task(): MowerTaskDescriptor | null;
+    /**
+     * Mowing coverage target / progress signal from the task descriptor (`d.o`).
+     * This is the P4 progress surface; the byte-accurate pose-track % is P5.
+     */
+    get coverageTargetPct(): number | null;
+    /** Parsed per-zone control status (2:56), or null. */
+    get controlStatus(): MowerControlState | null;
+    get controlAction(): MowerControlAction | null;
+    /**
+     * Start the generic mowing action (siid 5 aiid 1). Named `startMowing` — NOT
+     * `start` — because `BaseDevice.start()` is the MQTT lifecycle method the
+     * facade relies on; overriding it would break handle startup.
+     */
+    startMowing(): Promise<unknown>;
+    pause(): Promise<unknown>;
+    stop(): Promise<unknown>;
+    /** Send the mower to its dock (siid 5 aiid 3). */
+    dock(): Promise<unknown>;
+    /**
+     * Resume mowing after a pause. Encoded as the continueControl opcode
+     * `{m:'a', p:0, o:5}` sent as the single in-param of the SCHEDULING_TASK
+     * (2:50) action — NOT a siid-5 action. Mirrors the donor TASK_PAYLOAD_RESUME.
+     */
+    resume(): Promise<unknown>;
+    /** All-area, map-targeted mowing (2:50 o:100). */
+    startMowingAllArea(mapId: number): Promise<unknown>;
+    /** Zone-selective mowing (2:50 o:102). */
+    startMowingZones(zoneIds: number[]): Promise<unknown>;
+    /** Edge / contour mowing (2:50 o:101). Contour ids are two-int pairs [[1,0]]. */
+    startMowingEdges(contourIds: number[][]): Promise<unknown>;
+    /** Spot mowing (2:50 o:103). */
+    startMowingSpots(spotAreaIds: number[]): Promise<unknown>;
+    /** The most-recently-parsed map, or `null` until {@link getMap} succeeds. */
+    get lastMap(): MowerMap | null;
+    /**
+     * Fetch the batched vector-map data, parse it into a {@link MowerMap}, cache
+     * it as {@link lastMap}, and return it. Capability-gated on `canMap`.
+     *
+     * The batch fetcher is injected at construction (the live cloud endpoint path
+     * is not yet recovered — see `cloud/commands.ts`). Rejects with
+     * {@link DreameError} if no fetcher was injected or the batch yields no
+     * parseable map (asleep mower / empty data).
+     */
+    getMap(props?: readonly string[]): Promise<MowerMap>;
+    /**
+     * Render the current map to a deterministic SVG string. Uses {@link lastMap}
+     * when present, otherwise fetches first via {@link getMap}.
+     */
+    mapSvg(opts?: RenderMowerSvgOptions): Promise<string>;
+    /** Props worth seeding on start() / polling — exported for the facade. */
+    static readonly DEFAULT_PROPS: readonly [{
+        readonly siid: 2;
+        readonly piid: 1;
+    }, {
+        readonly siid: 3;
+        readonly piid: 1;
+    }, {
+        readonly siid: 3;
+        readonly piid: 2;
+    }, {
+        readonly siid: 5;
+        readonly piid: 104;
+    }, {
+        readonly siid: 2;
+        readonly piid: 50;
+    }, {
+        readonly siid: 2;
+        readonly piid: 56;
+    }];
+}
+
+export { BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceEvent, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, 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, 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, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };