feat(map): add MowerMapTrace renderer for trace points

Mowers don't expose the regular map capability used by vacuums; their
trajectory only comes through MapTraceEvent. Move accumulation,
FIFO cap and SVG rendering into the library so consumers only forward
the event payload and read back an SVG.

Author: Beennnn

deebot_client/mower_trace.py

@@ -0,0 +1,98 @@
+"""Mower trajectory accumulator and SVG renderer.
+
+Mowers (e.g. Ecovacs GOAT family) do not expose the regular ``map``
+capability used by vacuums, but their firmware pushes trajectory points
+through :class:`~deebot_client.events.map.MapTraceEvent`. This module
+keeps the parsing, accumulation and rendering of those points in one
+place so consumers (e.g. the Home Assistant integration) only have to
+forward the event payload and read back an SVG.
+"""
+
+from __future__ import annotations
+
+
+class MowerMapTrace:
+    """Accumulator and SVG renderer for mower trajectory traces."""
+
+    MAX_POINTS = 5000
+
+    _STROKE_COLOR = "#1976d2"
+
+    def __init__(self) -> None:
+        self._points: list[tuple[int, int]] = []
+
+    @property
+    def has_points(self) -> bool:
+        """Return whether any trace points have been accumulated."""
+        return bool(self._points)
+
+    def clear(self) -> None:
+        """Drop all accumulated trace points."""
+        self._points.clear()
+
+    def add_data(self, raw: str) -> int:
+        """Parse a ``MapTraceEvent.data`` string and accumulate points.
+
+        Tokens are ``"x,y"`` separated by ``";"``. Malformed tokens are
+        skipped silently. The accumulator keeps at most :attr:`MAX_POINTS`
+        points (FIFO drop). Returns the number of points actually added.
+        """
+        new_points: list[tuple[int, int]] = []
+        for token in raw.split(";"):
+            token = token.strip()
+            if not token:
+                continue
+            try:
+                x_str, y_str = token.split(",")
+                new_points.append((int(x_str), int(y_str)))
+            except ValueError:
+                continue
+
+        if not new_points:
+            return 0
+
+        self._points.extend(new_points)
+        if len(self._points) > self.MAX_POINTS:
+            self._points = self._points[-self.MAX_POINTS :]
+        return len(new_points)
+
+    def to_svg(self) -> str | None:
+        """Render the accumulated trace as an SVG polyline.
+
+        Returns ``None`` when no points have been accumulated yet.
+        """
+        if not self._points:
+            return None
+
+        xs = [p[0] for p in self._points]
+        ys = [p[1] for p in self._points]
+        min_x, max_x = min(xs), max(xs)
+        min_y, max_y = min(ys), max(ys)
+
+        # 5% padding on the larger of the two dimensions, with a 50-unit floor
+        # so a near-zero-area trace still has visible margin.
+        padding = max(50, max(max_x - min_x, max_y - min_y) // 20)
+        min_x -= padding
+        max_x += padding
+        min_y -= padding
+        max_y += padding
+
+        width = max_x - min_x
+        height = max_y - min_y
+
+        # Mower coordinates use bottom-up Y; flip for SVG top-down rendering.
+        flipped = " ".join(f"{x},{max_y + min_y - y}" for x, y in self._points)
+
+        # Stroke scales with width so the line stays visible on tiny lawns
+        # and isn't a hairline on huge ones.
+        stroke_width = max(20, width // 200)
+
+        return (
+            f'<svg xmlns="http://www.w3.org/2000/svg" '
+            f'viewBox="{min_x} {min_y} {width} {height}" '
+            f'preserveAspectRatio="xMidYMid meet">'
+            f'<polyline points="{flipped}" fill="none" '
+            f'stroke="{self._STROKE_COLOR}" stroke-width="{stroke_width}" '
+            f'stroke-linejoin="round" stroke-linecap="round"/>'
+            f"</svg>"
+        )

tests/test_mower_trace.py

@@ -0,0 +1,101 @@
+"""Tests for the MowerMapTrace accumulator and SVG renderer."""
+
+from __future__ import annotations
+
+import pytest
+
+from deebot_client.mower_trace import MowerMapTrace
+
+
+def test_empty_trace_renders_to_none() -> None:
+    trace = MowerMapTrace()
+    assert not trace.has_points
+    assert trace.to_svg() is None
+
+
+def test_add_data_parses_tokens_and_returns_count() -> None:
+    trace = MowerMapTrace()
+    added = trace.add_data("0,0;100,200;300,400")
+    assert added == 3
+    assert trace.has_points
+
+
+def test_add_data_skips_malformed_tokens() -> None:
+    trace = MowerMapTrace()
+    added = trace.add_data("0,0;not-a-point;100,abc;200,300;;")
+    # Only "0,0" and "200,300" parse cleanly.
+    assert added == 2
+
+
+def test_add_data_returns_zero_on_all_invalid() -> None:
+    trace = MowerMapTrace()
+    assert trace.add_data(";;not-valid;") == 0
+    assert not trace.has_points
+
+
+def test_clear_drops_all_points() -> None:
+    trace = MowerMapTrace()
+    trace.add_data("1,2;3,4")
+    trace.clear()
+    assert not trace.has_points
+    assert trace.to_svg() is None
+
+
+def test_max_points_fifo_drop() -> None:
+    trace = MowerMapTrace()
+    over = MowerMapTrace.MAX_POINTS + 100
+    payload = ";".join(f"{i},{i}" for i in range(over))
+    added = trace.add_data(payload)
+    assert added == over
+
+    svg = trace.to_svg()
+    assert svg is not None
+
+    # Polyline holds exactly MAX_POINTS coordinate pairs after FIFO drop.
+    points_attr = svg.split('points="', 1)[1].split('"', 1)[0]
+    assert len(points_attr.split(" ")) == MowerMapTrace.MAX_POINTS
+
+    # The MAX_POINTS most recent points are kept; first kept point has
+    # x = (over - MAX_POINTS), here 100.
+    first_kept_x = over - MowerMapTrace.MAX_POINTS
+    assert points_attr.startswith(f"{first_kept_x},")
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected_substrings", "absent_substrings"),
+    [
+        # Single-point trace: padding gives a non-zero viewBox.
+        ("500,500", ["polyline", "viewBox=", "stroke="], []),
+        # Two-point trace: SVG contains the flipped polyline points.
+        ("0,0;100,100", ["polyline points=", "viewBox="], []),
+    ],
+)
+def test_to_svg_structure(
+    raw: str, expected_substrings: list[str], absent_substrings: list[str]
+) -> None:
+    trace = MowerMapTrace()
+    trace.add_data(raw)
+    svg = trace.to_svg()
+    assert svg is not None
+    assert svg.startswith("<svg")
+    assert svg.endswith("</svg>")
+    for needle in expected_substrings:
+        assert needle in svg
+    for needle in absent_substrings:
+        assert needle not in svg
+
+
+def test_to_svg_y_axis_is_flipped() -> None:
+    """SVG renders top-down; mower coords are bottom-up. Verify the flip."""
+    trace = MowerMapTrace()
+    trace.add_data("0,0;0,1000")
+    svg = trace.to_svg()
+    assert svg is not None
+    # Extract the polyline points attribute.
+    points = svg.split('points="', 1)[1].split('"', 1)[0].split(" ")
+    # Two points, both with x=0; y values must be swapped versus input
+    # (input 0 -> output max_y+min_y-0 = larger value;
+    #  input 1000 -> output max_y+min_y-1000 = smaller value).
+    y0 = int(points[0].split(",")[1])
+    y1 = int(points[1].split(",")[1])
+    assert y0 > y1