@apocaliss92/nodedreame 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -1591,6 +1591,22 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
      * `applyVacuumPFrame` merge primitive ships separately for that work.
      */
     getMap(input: VacuumGetMapInput): Promise<VacuumMap>;
+    /** Drop the P-frame merge base so the next I-frame re-seeds the stream. */
+    resetMapStream(): void;
+    /**
+     * Fetch the latest advertised map frame and fold it into a continuously
+     * updating map. An I-frame (re)seeds the merge base and renders standalone; a
+     * P-frame is merged onto the base via {@link applyVacuumPFrame} so the live
+     * grid stays COMPLETE (a P-frame decoded standalone is only byte-deltas). On an
+     * out-of-order P-frame or a map-id change the base is dropped and `null`
+     * returned — the next I-frame re-seeds. Returns `null` when no frame is
+     * advertised yet, or a P-frame arrives before any I-frame.
+     *
+     * Caches {@link lastMap} and emits `'map'` exactly like {@link getMap}, so a
+     * map-watching consumer (e.g. the camstack map child) gets a fresh complete
+     * frame on every push during a live clean.
+     */
+    fetchLatestMapStreaming(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
     /** Props worth seeding on start() / polling — exported for the facade. */
     static readonly DEFAULT_PROPS: readonly [{
         readonly siid: 2;

package/dist/index.d.ts

@@ -1591,6 +1591,22 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
      * `applyVacuumPFrame` merge primitive ships separately for that work.
      */
     getMap(input: VacuumGetMapInput): Promise<VacuumMap>;
+    /** Drop the P-frame merge base so the next I-frame re-seeds the stream. */
+    resetMapStream(): void;
+    /**
+     * Fetch the latest advertised map frame and fold it into a continuously
+     * updating map. An I-frame (re)seeds the merge base and renders standalone; a
+     * P-frame is merged onto the base via {@link applyVacuumPFrame} so the live
+     * grid stays COMPLETE (a P-frame decoded standalone is only byte-deltas). On an
+     * out-of-order P-frame or a map-id change the base is dropped and `null`
+     * returned — the next I-frame re-seeds. Returns `null` when no frame is
+     * advertised yet, or a P-frame arrives before any I-frame.
+     *
+     * Caches {@link lastMap} and emits `'map'` exactly like {@link getMap}, so a
+     * map-watching consumer (e.g. the camstack map child) gets a fresh complete
+     * frame on every push during a live clean.
+     */
+    fetchLatestMapStreaming(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
     /** Props worth seeding on start() / polling — exported for the facade. */
     static readonly DEFAULT_PROPS: readonly [{
         readonly siid: 2;

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
-var LIBRARY_VERSION = "1.9.0";
+var LIBRARY_VERSION = "1.10.0";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -2552,6 +2552,157 @@ function decodeCleanedAreaPixels(pixels, width, height) {
   return { cleaned, dirty };
 }
 
+// src/models/vacuum/map/merge.ts
+var OutOfOrderFrameError = class extends Error {
+  expectedFrameId;
+  actualFrameId;
+  constructor(expectedFrameId, actualFrameId) {
+    super(`map: out-of-order P-frame (expected frame_id=${expectedFrameId}, got ${actualFrameId})`);
+    this.name = "OutOfOrderFrameError";
+    this.expectedFrameId = expectedFrameId;
+    this.actualFrameId = actualFrameId;
+  }
+};
+function mergePFrame(prevInflated, pFrameInflated) {
+  const prevHeader = parseMapHeader(prevInflated);
+  const pHeader = parseMapHeader(pFrameInflated);
+  if (pHeader.frameType !== "P") {
+    throw new MapDecodeError(`mergePFrame: expected P-frame, got frame_type=${pHeader.frameType}`);
+  }
+  if (pHeader.mapId !== prevHeader.mapId) {
+    throw new MapDecodeError(
+      `mergePFrame: map_id mismatch (prev=${prevHeader.mapId}, P=${pHeader.mapId}) \u2014 request a fresh I-frame`
+    );
+  }
+  if (pHeader.frameId !== prevHeader.frameId + 1) {
+    throw new OutOfOrderFrameError(prevHeader.frameId + 1, pHeader.frameId);
+  }
+  if (prevHeader.gridSize !== pHeader.gridSize && pHeader.width > 0 && pHeader.height > 0) {
+    throw new MapDecodeError(
+      `mergePFrame: grid_size changed mid-stream (${prevHeader.gridSize} \u2192 ${pHeader.gridSize})`
+    );
+  }
+  const prevTail = parseMapJsonTail(sliceTailText(prevInflated, prevHeader));
+  const pTail = parseMapJsonTail(sliceTailText(pFrameInflated, pHeader));
+  const prevLeft = prevTail.origin?.[0] ?? prevHeader.left;
+  const prevTop = prevTail.origin?.[1] ?? prevHeader.top;
+  const grid = prevHeader.gridSize;
+  const prevRight = prevLeft + prevHeader.width * grid;
+  const prevBottom = prevTop + prevHeader.height * grid;
+  const hasPixelDelta = pHeader.width > 0 && pHeader.height > 0;
+  let unionLeft = prevLeft;
+  let unionTop = prevTop;
+  let unionWidth = prevHeader.width;
+  let unionHeight = prevHeader.height;
+  let pLeft = 0;
+  let pTop = 0;
+  if (hasPixelDelta) {
+    pLeft = pTail.origin?.[0] ?? pHeader.left;
+    pTop = pTail.origin?.[1] ?? pHeader.top;
+    const pRight = pLeft + pHeader.width * grid;
+    const pBottom = pTop + pHeader.height * grid;
+    if ((pLeft - prevLeft) % grid !== 0 || (pTop - prevTop) % grid !== 0) {
+      throw new MapDecodeError(
+        `mergePFrame: P-frame origin not aligned to prev grid (offset=${pLeft - prevLeft},${pTop - prevTop} vs grid=${grid})`
+      );
+    }
+    unionLeft = Math.min(prevLeft, pLeft);
+    unionTop = Math.min(prevTop, pTop);
+    const unionRight = Math.max(prevRight, pRight);
+    const unionBottom = Math.max(prevBottom, pBottom);
+    unionWidth = (unionRight - unionLeft) / grid;
+    unionHeight = (unionBottom - unionTop) / grid;
+  }
+  const newPixels = Buffer.alloc(unionWidth * unionHeight);
+  const prevPixelEnd = HEADER_SIZE + prevHeader.width * prevHeader.height;
+  if (prevInflated.length < prevPixelEnd) {
+    throw new MapDecodeError(
+      `mergePFrame: prev buffer truncated (need ${prevPixelEnd} bytes for header+pixels, got ${prevInflated.length})`
+    );
+  }
+  const prevPixels = prevInflated.subarray(HEADER_SIZE, prevPixelEnd);
+  const prevDxPx = (prevLeft - unionLeft) / grid;
+  const prevDyPx = (prevTop - unionTop) / grid;
+  for (let y = 0; y < prevHeader.height; y++) {
+    const srcOff = y * prevHeader.width;
+    const dstOff = (prevDyPx + y) * unionWidth + prevDxPx;
+    prevPixels.copy(newPixels, dstOff, srcOff, srcOff + prevHeader.width);
+  }
+  if (hasPixelDelta) {
+    const pPixelEnd = HEADER_SIZE + pHeader.width * pHeader.height;
+    if (pFrameInflated.length < pPixelEnd) {
+      throw new MapDecodeError(
+        `mergePFrame: P buffer truncated (need ${pPixelEnd} bytes for header+pixels, got ${pFrameInflated.length})`
+      );
+    }
+    const pPixels = pFrameInflated.subarray(HEADER_SIZE, pPixelEnd);
+    const pDxPx = (pLeft - unionLeft) / grid;
+    const pDyPx = (pTop - unionTop) / grid;
+    for (let y = 0; y < pHeader.height; y++) {
+      const dstRow = (pDyPx + y) * unionWidth + pDxPx;
+      const srcRow = y * pHeader.width;
+      for (let x = 0; x < pHeader.width; x++) {
+        newPixels[dstRow + x] = newPixels[dstRow + x] + pPixels[srcRow + x] & 255;
+      }
+    }
+  }
+  const newHeader = Buffer.alloc(HEADER_SIZE);
+  newHeader.writeInt16LE(prevHeader.mapId, 0);
+  newHeader.writeInt16LE(pHeader.frameId, 2);
+  newHeader[4] = FRAME_TYPE.I;
+  newHeader.writeInt16LE(pHeader.robotX, 5);
+  newHeader.writeInt16LE(pHeader.robotY, 7);
+  newHeader.writeInt16LE(pHeader.robotA, 9);
+  newHeader.writeInt16LE(pHeader.chargerX, 11);
+  newHeader.writeInt16LE(pHeader.chargerY, 13);
+  newHeader.writeInt16LE(pHeader.chargerA, 15);
+  newHeader.writeInt16LE(grid, 17);
+  newHeader.writeInt16LE(unionWidth, 19);
+  newHeader.writeInt16LE(unionHeight, 21);
+  newHeader.writeInt16LE(unionLeft, 23);
+  newHeader.writeInt16LE(unionTop, 25);
+  const mergedTail = mergeTails(prevTail, pTail, unionLeft, unionTop);
+  const tailBytes = Buffer.from(JSON.stringify(mergedTail), "utf8");
+  return Buffer.concat([newHeader, newPixels, tailBytes]);
+}
+function mergePFrameEnvelope(prev, pframe, prevOpts, pframeOpts) {
+  const prevBuf = typeof prev === "string" ? unwrapEnvelope(prev, prevOpts) : prev;
+  const pBuf = typeof pframe === "string" ? unwrapEnvelope(pframe, pframeOpts) : pframe;
+  return mergePFrame(prevBuf, pBuf);
+}
+function mergeTails(prev, p, unionLeft, unionTop) {
+  const merged = { ...p };
+  merged.origin = [unionLeft, unionTop];
+  const prevTr = typeof prev.tr === "string" ? prev.tr : "";
+  const pTr = typeof p.tr === "string" ? p.tr : "";
+  if (prevTr || pTr) {
+    merged.tr = prevTr + pTr;
+  } else {
+    delete merged.tr;
+  }
+  if (!("seg_inf" in p) && "seg_inf" in prev) {
+    merged.seg_inf = prev.seg_inf;
+  }
+  if (!("sa" in p) && "sa" in prev) {
+    merged.sa = prev.sa;
+  }
+  for (const key2 of PERSISTENT_TAIL_KEYS) {
+    if (!(key2 in p) && key2 in prev) {
+      merged[key2] = prev[key2];
+    }
+  }
+  return merged;
+}
+var PERSISTENT_TAIL_KEYS = [
+  "vw",
+  "vws",
+  "sneak_areas",
+  "sneak_areas_end",
+  "walls_info",
+  "rism",
+  "decmap"
+];
+
 // src/models/vacuum/map/decode.ts
 function decodeVacuumMap(input, opts = {}) {
   const inflated = typeof input === "string" ? unwrapEnvelope(input, opts) : looksLikeBase64Zlib(input) ? unwrapEnvelope(input.toString("latin1"), opts) : input;
@@ -2596,6 +2747,10 @@ function decodeVacuumMap(input, opts = {}) {
     cleanedArea
   };
 }
+function applyVacuumPFrame(prev, pframe, opts = {}) {
+  const merged = typeof prev === "string" || typeof pframe === "string" ? mergePFrameEnvelope(prev, pframe, opts.prev, opts.pframe) : mergePFrame(prev, pframe);
+  return { buffer: merged, data: decodeVacuumMap(merged) };
+}
 function mergeDimensions(header, tail) {
   const left = tail.origin?.[0] ?? header.left;
   const top = tail.origin?.[1] ?? header.top;
@@ -3533,6 +3688,14 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
    */
   async getMap(input) {
     this.#requireCap(this.#caps.canMap, "getMap", "map decoding");
+    const blob = await this.#fetchMapBlob(input);
+    const map = decodeVacuumMap(blob, this.#decodeOpts(input));
+    this.#lastMap = map;
+    this.emit("map", map);
+    return map;
+  }
+  /** Fetch the raw OSS blob (still the base64+zlib envelope) for a map frame. */
+  async #fetchMapBlob(input) {
     const session = this.currentSession();
     const region = this.region;
     const fetcher = input.fetcher ?? new OssFetcher();
@@ -3546,14 +3709,77 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
       ...input.timeoutMs !== void 0 ? { timeoutMs: input.timeoutMs } : {},
       ...input.signal !== void 0 ? { signal: input.signal } : {}
     };
-    const blob = await fetcher.fetchBlob(fetchInput);
-    const map = decodeVacuumMap(blob, {
+    return fetcher.fetchBlob(fetchInput);
+  }
+  /** The AES key/iv decode options, threaded from a {@link VacuumGetMapInput}. */
+  #decodeOpts(input) {
+    return {
       ...input.key !== void 0 ? { key: input.key } : {},
       ...input.iv !== void 0 ? { iv: input.iv } : {}
-    });
-    this.#lastMap = map;
-    this.emit("map", map);
-    return map;
+    };
+  }
+  /**
+   * The merge base for live P-frame streaming — always an INFLATED frame buffer.
+   * An I-frame (re)seeds it; each P-frame merge replaces it with the merged
+   * inflated buffer (so further P-frames stack). `null` until the first I-frame
+   * (or after an out-of-order / map-id reset).
+   */
+  #mapStreamBase = null;
+  /** Drop the P-frame merge base so the next I-frame re-seeds the stream. */
+  resetMapStream() {
+    this.#mapStreamBase = null;
+  }
+  /** Inflate an OSS blob to a raw frame buffer (live envelope → zlib; verbatim if already inflated). */
+  #inflateFrame(blob, opts) {
+    return looksLikeBase64Zlib(blob) ? unwrapEnvelope(blob.toString("latin1"), opts) : blob;
+  }
+  /**
+   * Fetch the latest advertised map frame and fold it into a continuously
+   * updating map. An I-frame (re)seeds the merge base and renders standalone; a
+   * P-frame is merged onto the base via {@link applyVacuumPFrame} so the live
+   * grid stays COMPLETE (a P-frame decoded standalone is only byte-deltas). On an
+   * out-of-order P-frame or a map-id change the base is dropped and `null`
+   * returned — the next I-frame re-seeds. Returns `null` when no frame is
+   * advertised yet, or a P-frame arrives before any I-frame.
+   *
+   * Caches {@link lastMap} and emits `'map'` exactly like {@link getMap}, so a
+   * map-watching consumer (e.g. the camstack map child) gets a fresh complete
+   * frame on every push during a live clean.
+   */
+  async fetchLatestMapStreaming(opts = {}) {
+    this.#requireCap(this.#caps.canMap, "fetchLatestMapStreaming", "map decoding");
+    const filename = this.mapFilename;
+    if (filename === null) return null;
+    const input = { filename, ...opts };
+    const decodeOpts = this.#decodeOpts(input);
+    const blob = await this.#fetchMapBlob(input);
+    const inflated = this.#inflateFrame(blob, decodeOpts);
+    const frame = decodeVacuumMap(inflated, decodeOpts);
+    if (frame.frameType === "I") {
+      this.#mapStreamBase = inflated;
+      this.#lastMap = frame;
+      this.emit("map", frame);
+      return frame;
+    }
+    if (frame.frameType === "P") {
+      if (this.#mapStreamBase === null) return null;
+      try {
+        const { buffer, data } = applyVacuumPFrame(this.#mapStreamBase, inflated);
+        this.#mapStreamBase = buffer;
+        this.#lastMap = data;
+        this.emit("map", data);
+        return data;
+      } catch (err) {
+        if (err instanceof OutOfOrderFrameError || err instanceof MapDecodeError) {
+          this.#mapStreamBase = null;
+          return null;
+        }
+        throw err;
+      }
+    }
+    this.#lastMap = frame;
+    this.emit("map", frame);
+    return frame;
   }
   /** Props worth seeding on start() / polling — exported for the facade. */
   static DEFAULT_PROPS = [