@apocaliss92/nodedreame 1.8.1 → 1.10.0

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
-var LIBRARY_VERSION = "1.8.1";
+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;
@@ -2616,10 +2771,79 @@ function pose(x, y, angle, absent) {
 
 // src/models/vacuum/map/render.ts
 import { PNG } from "pngjs";
-var RGBA = {
-  wall: [60, 60, 60, 255],
-  floor: [210, 222, 235, 255],
-  carpet: [180, 150, 120, 200]
+var SCHEMES = {
+  "dreame-light": {
+    floor: [210, 222, 235, 255],
+    wall: [60, 60, 60, 255],
+    carpet: [180, 150, 120, 200],
+    segSat: 0.45,
+    segVal: 0.95,
+    path: [60, 110, 180, 235],
+    robotBody: [40, 70, 110, 255],
+    robotHeading: [255, 255, 255, 255],
+    charger: [40, 160, 80, 255],
+    noGoFill: [220, 60, 60, 70],
+    noGoBorder: [200, 40, 40, 220],
+    noMopFill: [60, 120, 220, 60],
+    noMopBorder: [40, 90, 200, 200],
+    virtualWall: [200, 40, 40, 230],
+    obstacle: [230, 150, 30, 255],
+    label: [40, 40, 40, 255]
+  },
+  "dreame-dark": {
+    floor: [40, 46, 56, 255],
+    wall: [15, 15, 18, 255],
+    carpet: [80, 66, 52, 200],
+    segSat: 0.5,
+    segVal: 0.62,
+    path: [120, 170, 230, 235],
+    robotBody: [120, 170, 230, 255],
+    robotHeading: [20, 24, 30, 255],
+    charger: [60, 200, 110, 255],
+    noGoFill: [220, 70, 70, 80],
+    noGoBorder: [230, 70, 70, 220],
+    noMopFill: [70, 130, 230, 70],
+    noMopBorder: [80, 140, 235, 210],
+    virtualWall: [230, 70, 70, 235],
+    obstacle: [240, 180, 60, 255],
+    label: [225, 230, 240, 255]
+  },
+  "mijia-light": {
+    floor: [225, 232, 240, 255],
+    wall: [70, 78, 92, 255],
+    carpet: [188, 162, 132, 200],
+    segSat: 0.35,
+    segVal: 0.98,
+    path: [80, 130, 200, 230],
+    robotBody: [30, 100, 200, 255],
+    robotHeading: [255, 255, 255, 255],
+    charger: [40, 170, 90, 255],
+    noGoFill: [225, 70, 70, 70],
+    noGoBorder: [205, 45, 45, 220],
+    noMopFill: [70, 130, 225, 60],
+    noMopBorder: [50, 100, 205, 200],
+    virtualWall: [205, 45, 45, 230],
+    obstacle: [235, 160, 35, 255],
+    label: [45, 52, 64, 255]
+  },
+  tasshack: {
+    floor: [200, 210, 225, 255],
+    wall: [80, 80, 95, 255],
+    carpet: [176, 148, 118, 205],
+    segSat: 0.5,
+    segVal: 0.9,
+    path: [50, 100, 170, 235],
+    robotBody: [35, 60, 100, 255],
+    robotHeading: [255, 255, 255, 255],
+    charger: [35, 150, 75, 255],
+    noGoFill: [215, 55, 55, 75],
+    noGoBorder: [195, 35, 35, 220],
+    noMopFill: [55, 115, 215, 65],
+    noMopBorder: [35, 85, 195, 205],
+    virtualWall: [195, 35, 35, 230],
+    obstacle: [225, 145, 25, 255],
+    label: [35, 42, 54, 255]
+  }
 };
 function hsvToRgba(h, s, v) {
   const c = v * s;
@@ -2650,49 +2874,230 @@ function hsvToRgba(h, s, v) {
   const m = v - c;
   return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255), 255];
 }
-function segmentColor(id) {
+function segmentColor(id, pal) {
   const hue = id * 137.508 % 360;
-  return hsvToRgba(hue, 0.45, 0.95);
+  return hsvToRgba(hue, pal.segSat, pal.segVal);
 }
 function renderVacuumPng(map, opts = {}) {
   const scale = Math.max(1, Math.trunc(opts.scale ?? 1));
-  const w = map.dimensions.width * scale;
-  const h = map.dimensions.height * scale;
-  const png = new PNG({ width: Math.max(1, w), height: Math.max(1, h) });
+  const pal = SCHEMES[opts.colorScheme ?? "dreame-light"];
+  const w = Math.max(1, map.dimensions.width * scale);
+  const h = Math.max(1, map.dimensions.height * scale);
+  const png = new PNG({ width: w, height: h });
   png.data.fill(0);
   for (const layer of map.layers) {
-    paintLayer(png, layer, scale);
+    paintLayer(png, layer, scale, pal);
+  }
+  const dim = map.dimensions;
+  if (opts.showNoGo !== false) {
+    for (const area of map.restrictedAreas) {
+      const fill = area.kind === "noMop" ? pal.noMopFill : pal.noGoFill;
+      const border = area.kind === "noMop" ? pal.noMopBorder : pal.noGoBorder;
+      const a = worldToPx(area.bbox.xMin, area.bbox.yMin, dim, scale);
+      const b = worldToPx(area.bbox.xMax, area.bbox.yMax, dim, scale);
+      fillRect(png, a.x, a.y, b.x, b.y, fill);
+      strokeRect(png, a.x, a.y, b.x, b.y, border);
+    }
+  }
+  if (opts.showVirtualWalls !== false) {
+    for (const vw of map.virtualWalls) {
+      const a = worldToPx(vw.from.x, vw.from.y, dim, scale);
+      const b = worldToPx(vw.to.x, vw.to.y, dim, scale);
+      drawLine(png, a.x, a.y, b.x, b.y, pal.virtualWall, Math.max(1, scale));
+    }
+  }
+  if (opts.showPath !== false) {
+    for (const path of map.paths) {
+      drawPolyline(png, path.points, dim, scale, pal.path, Math.max(1, scale));
+    }
+  }
+  if (opts.showObstacles !== false) {
+    for (const ob of map.obstacles) {
+      const p = worldToPx(ob.x, ob.y, dim, scale);
+      drawDisk(png, p.x, p.y, Math.max(2, scale * 2), pal.obstacle);
+    }
+  }
+  if (opts.showCharger !== false && map.dock !== null) {
+    drawCharger(png, map.dock, dim, scale, pal);
+  }
+  if (opts.showRobot !== false && map.robot !== null) {
+    drawRobot(png, map.robot, dim, scale, pal);
+  }
+  if (opts.showSegmentLabels === true) {
+    for (const seg of map.segments) {
+      const p = worldToPx(seg.centroid.x, seg.centroid.y, dim, scale);
+      drawLabel(png, p.x, p.y, String(seg.id), pal.label, Math.max(1, scale));
+    }
   }
   return PNG.sync.write(png);
 }
-function paintLayer(png, layer, scale) {
-  const color = layer.type === "segment" ? segmentColor(layer.segmentId ?? 0) : RGBA[layer.type];
+function worldToPx(worldX, worldY, dim, scale) {
+  return {
+    x: Math.round((worldX - dim.left) / dim.gridSize * scale),
+    y: Math.round((worldY - dim.top) / dim.gridSize * scale)
+  };
+}
+function paintLayer(png, layer, scale, pal) {
+  const color = layer.type === "segment" ? segmentColor(layer.segmentId ?? 0, pal) : layer.type === "wall" ? pal.wall : layer.type === "carpet" ? pal.carpet : pal.floor;
   for (const run of layer.runs) {
-    paintRun(png, run, color, scale, png.width, png.height);
+    paintRun(png, run, color, scale);
   }
 }
-function paintRun(png, run, color, scale, width, height) {
+function paintRun(png, run, color, scale) {
   const [xPx, yPx, len] = run;
   for (let i = 0; i < len; i += 1) {
     const baseX = (xPx + i) * scale;
     const baseY = yPx * scale;
     for (let dy = 0; dy < scale; dy += 1) {
-      const py = baseY + dy;
-      if (py < 0 || py >= height) {
-        continue;
-      }
       for (let dx = 0; dx < scale; dx += 1) {
-        const px = baseX + dx;
-        if (px < 0 || px >= width) {
-          continue;
+        setPixel(png, baseX + dx, baseY + dy, color);
+      }
+    }
+  }
+}
+function setPixel(png, x, y, color) {
+  if (x < 0 || y < 0 || x >= png.width || y >= png.height) return;
+  const off = (y * png.width + x) * 4;
+  const a = color[3];
+  if (a >= 255) {
+    png.data[off] = color[0];
+    png.data[off + 1] = color[1];
+    png.data[off + 2] = color[2];
+    png.data[off + 3] = 255;
+    return;
+  }
+  const sa = a / 255;
+  const da = (png.data[off + 3] ?? 0) / 255;
+  const outA = sa + da * (1 - sa);
+  if (outA <= 0) return;
+  for (let k = 0; k < 3; k += 1) {
+    const src = color[k] ?? 0;
+    const dst = png.data[off + k] ?? 0;
+    png.data[off + k] = Math.round((src * sa + dst * da * (1 - sa)) / outA);
+  }
+  png.data[off + 3] = Math.round(outA * 255);
+}
+function fillRect(png, x0, y0, x1, y1, color) {
+  const xa = Math.min(x0, x1);
+  const xb = Math.max(x0, x1);
+  const ya = Math.min(y0, y1);
+  const yb = Math.max(y0, y1);
+  for (let y = ya; y <= yb; y += 1) {
+    for (let x = xa; x <= xb; x += 1) {
+      setPixel(png, x, y, color);
+    }
+  }
+}
+function strokeRect(png, x0, y0, x1, y1, color) {
+  const xa = Math.min(x0, x1);
+  const xb = Math.max(x0, x1);
+  const ya = Math.min(y0, y1);
+  const yb = Math.max(y0, y1);
+  for (let x = xa; x <= xb; x += 1) {
+    setPixel(png, x, ya, color);
+    setPixel(png, x, yb, color);
+  }
+  for (let y = ya; y <= yb; y += 1) {
+    setPixel(png, xa, y, color);
+    setPixel(png, xb, y, color);
+  }
+}
+function drawLine(png, x0, y0, x1, y1, color, thickness) {
+  let x = x0;
+  let y = y0;
+  const dx = Math.abs(x1 - x0);
+  const dy = -Math.abs(y1 - y0);
+  const sx = x0 < x1 ? 1 : -1;
+  const sy = y0 < y1 ? 1 : -1;
+  let err = dx + dy;
+  const r = Math.max(0, Math.trunc((thickness - 1) / 2));
+  for (; ; ) {
+    for (let oy = -r; oy <= r; oy += 1) {
+      for (let ox = -r; ox <= r; ox += 1) {
+        setPixel(png, x + ox, y + oy, color);
+      }
+    }
+    if (x === x1 && y === y1) break;
+    const e2 = 2 * err;
+    if (e2 >= dy) {
+      err += dy;
+      x += sx;
+    }
+    if (e2 <= dx) {
+      err += dx;
+      y += sy;
+    }
+  }
+}
+function drawPolyline(png, points, dim, scale, color, thickness) {
+  for (let i = 1; i < points.length; i += 1) {
+    const p0 = points[i - 1];
+    const p1 = points[i];
+    if (p0 === void 0 || p1 === void 0) continue;
+    const a = worldToPx(p0.x, p0.y, dim, scale);
+    const b = worldToPx(p1.x, p1.y, dim, scale);
+    drawLine(png, a.x, a.y, b.x, b.y, color, thickness);
+  }
+}
+function drawDisk(png, cx, cy, r, color) {
+  const rr = r * r;
+  for (let dy = -r; dy <= r; dy += 1) {
+    for (let dx = -r; dx <= r; dx += 1) {
+      if (dx * dx + dy * dy <= rr) setPixel(png, cx + dx, cy + dy, color);
+    }
+  }
+}
+function drawRobot(png, robot, dim, scale, pal) {
+  const p = worldToPx(robot.x, robot.y, dim, scale);
+  const r = Math.max(3, scale * 3);
+  drawDisk(png, p.x, p.y, r, pal.robotBody);
+  const rad = robot.angle * Math.PI / 180;
+  const hx = Math.round(p.x + Math.cos(rad) * r);
+  const hy = Math.round(p.y + Math.sin(rad) * r);
+  drawLine(png, p.x, p.y, hx, hy, pal.robotHeading, Math.max(1, Math.trunc(scale / 2) + 1));
+}
+function drawCharger(png, dock, dim, scale, pal) {
+  const p = worldToPx(dock.x, dock.y, dim, scale);
+  const r = Math.max(2, scale * 2);
+  fillRect(png, p.x - r, p.y - r, p.x + r, p.y + r, pal.charger);
+}
+var GLYPHS = {
+  "0": [7, 5, 5, 5, 7],
+  "1": [2, 6, 2, 2, 7],
+  "2": [7, 1, 7, 4, 7],
+  "3": [7, 1, 7, 1, 7],
+  "4": [5, 5, 7, 1, 1],
+  "5": [7, 4, 7, 1, 7],
+  "6": [7, 4, 7, 5, 7],
+  "7": [7, 1, 2, 2, 2],
+  "8": [7, 5, 7, 5, 7],
+  "9": [7, 5, 7, 1, 7],
+  "-": [0, 0, 7, 0, 0]
+};
+function drawLabel(png, cx, cy, text, color, px) {
+  const glyphW = 3 * px;
+  const glyphH = 5 * px;
+  const gap = px;
+  const totalW = text.length * glyphW + Math.max(0, text.length - 1) * gap;
+  let originX = Math.round(cx - totalW / 2);
+  const originY = Math.round(cy - glyphH / 2);
+  for (const ch of text) {
+    const glyph = GLYPHS[ch];
+    if (glyph !== void 0) {
+      for (let row = 0; row < 5; row += 1) {
+        const bits = glyph[row];
+        if (bits === void 0) continue;
+        for (let col = 0; col < 3; col += 1) {
+          if ((bits & 1 << 2 - col) === 0) continue;
+          for (let sy = 0; sy < px; sy += 1) {
+            for (let sx = 0; sx < px; sx += 1) {
+              setPixel(png, originX + col * px + sx, originY + row * px + sy, color);
+            }
+          }
         }
-        const off = (py * width + px) * 4;
-        png.data[off] = color[0];
-        png.data[off + 1] = color[1];
-        png.data[off + 2] = color[2];
-        png.data[off + 3] = color[3];
       }
     }
+    originX += glyphW + gap;
   }
 }
 
@@ -3283,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();
@@ -3296,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 = [