From a276f873723b33f2760b8d623aa85568191b5cac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Sat, 25 Apr 2026 22:22:15 +0300
Subject: [PATCH 01/44] Show recovery panel when history list response is
 unparseable

---
 docs/user-guide.md             | 48 ++++++++++++++++++-------
 frontend/mock/server.js        | 19 ++++++++++
 frontend/src/api.ts            | 16 ++++++++-
 frontend/src/style.css         | 45 +++++++++++++++++++++++
 frontend/src/views/history.tsx | 65 +++++++++++++++++++++++++++++++---
 5 files changed, 175 insertions(+), 18 deletions(-)

diff --git a/docs/user-guide.md b/docs/user-guide.md
index 8040331..bd95b3f 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -6,7 +6,6 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
 
 - [Hardware Setup](#hardware-setup)
     - [What You Need](#what-you-need)
-    - [Opening the Robot](#opening-the-robot)
     - [Debug Port Pinout](#debug-port-pinout)
     - [Wiring](#wiring)
 - [Flashing Firmware](#flashing-firmware)
@@ -24,6 +23,7 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
     - [Enabling Logging](#enabling-logging)
     - [Collecting Logs](#collecting-logs)
     - [Downloading Cleaning Maps](#downloading-cleaning-maps)
+    - [Recovering Corrupted Cleaning History](#recovering-corrupted-cleaning-history)
     - [Factory Reset](#factory-reset)
     - [Reporting an Issue](#reporting-an-issue)
 - [Multiple Robots](#multiple-robots)
@@ -37,12 +37,10 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
 ## Hardware Setup
 
 > [!NOTE]
-> Hardware assembly is not the primary focus of this project. There are already comprehensive
-> teardown and wiring guides available — in particular
-> [Philip2809/neato-brainslug](https://github.com/Philip2809/neato-brainslug) which covers
-> the D3-D7 debug port in detail. This section shares my personal experience with minimal
-> photos and a bill of materials. If there's community interest I'll expand it further —
-> I'll be opening my own Neato D7 soon to replace the LIDAR O-ring.
+> Hardware assembly is not the primary focus of this project. For a comprehensive teardown
+> guide covering how to open the robot and reach the debug port, see
+> [Philip2809/neato-brainslug](https://github.com/Philip2809/neato-brainslug). This section
+> covers the parts list, debug port pinout, and wiring.
 
 ### What You Need
 
@@ -75,11 +73,6 @@ solder the JST connector wires directly to the board pads for the cleanest resul
 The ESP32 is powered directly from the robot's 3.3V debug port — no separate USB power
 supply needed during normal operation.
 
-### Opening the Robot
-
-<!-- TODO: brief description of my experience, photos of the bottom screws and top shell removal -->
-<!-- Reference: https://github.com/Philip2809/neato-brainslug for a comprehensive teardown guide -->
-
 ### Debug Port Pinout
 
 The debug port connector on Botvac D3-D7 has four pins (left to right when looking at the
@@ -362,7 +355,36 @@ termination), download the cleaning history session from **History**. Each sessi
 the robot's recorded path rendered as a coverage map, along with stats like duration, distance,
 area covered, and battery usage.
 
-<!-- TODO: describe how to download/share the session data file for issue reports -->
+### Recovering Corrupted Cleaning History
+
+If the History page shows a "Cleaning history is corrupted" message, one of the stored sessions
+has malformed data and is preventing the list from loading. This can happen if a cleaning was
+interrupted by a power loss or unexpected reset. The following steps let you find and remove
+the bad session(s) without losing the rest. Replace `YOUR_ROBOT` with your bridge's hostname
+or IP address.
+
+1. **Fetch the session list** and inspect it visually:
+
+    ```sh
+    curl "http://YOUR_ROBOT/api/history"
+    ```
+
+   Paste the response into a JSON validator (for example
+   [jsonlint.com](https://jsonlint.com) or [jsonformatter.org](https://jsonformatter.org)).
+   The validator will flag the position of the malformed entry. Note the `name` field of the
+   bad session (e.g. `1776667071.jsonl.hs`).
+
+2. **Delete the bad session**:
+
+    ```sh
+    curl -X DELETE "http://YOUR_ROBOT/api/history/<filename>"
+    ```
+
+3. **Reload the History page**. If multiple sessions are corrupted, repeat steps 1-2 until the
+   list loads.
+
+If you'd rather not investigate, the History page also offers a **Delete all history** button
+that wipes every session in one go and restores the list view.
 
 ### Factory Reset
 
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index d757ddf..9243ccd 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -101,6 +101,7 @@ const _randf = (min, max, decimals = 2) => parseFloat((Math.random() * (max - mi
 //   fpe  — Polling fault: GET /api/error
 //   fp   — All polling faults (state + charger + error)
 //   fhc  — History corruption (inject corrupted pose lines in session data)
+//   fhl  — History list corruption (malformed JSON in /api/history response, triggers recovery panel)
 //   fal  — All faults combined
 const SCENARIO = "ok";
 
@@ -161,6 +162,7 @@ const SCENARIOS = {
     fpe: { faults: { pollError: true } },
     fp: { faults: { pollState: true, pollCharger: true, pollError: true } },
     fhc: { faults: { historyCorrupt: true } },
+    fhl: { faults: { historyListCorrupt: true } },
     fal: {
         faults: {
             actions: true,
@@ -171,6 +173,7 @@ const SCENARIOS = {
             pollCharger: true,
             pollError: true,
             historyCorrupt: true,
+            historyListCorrupt: true,
         },
     },
 };
@@ -898,6 +901,22 @@ const handleRequest = async (req, res) => {
                 summary,
             };
         });
+        // Mimic the firmware bug from issue #90: one session's summary field
+        // contains a truncated pose snapshot concatenated with the real
+        // summary, which makes the entire response unparseable. Triggers the
+        // recovery panel in the frontend.
+        if (faults.historyListCorrupt && list.length > 0) {
+            const target = list[Math.min(1, list.length - 1)];
+            const summaryJson = target.summary ? JSON.stringify(target.summary) : '{"type":"summary"}';
+            const corruptedSummary = `{"x":-0.218,"y":0.007,"t":35${summaryJson.slice(1)}`;
+            const body = JSON.stringify(list).replace(JSON.stringify(target.summary ?? null), corruptedSummary);
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(body),
+            });
+            res.end(body);
+            return;
+        }
         return jsonResponse(res, list);
     }
 
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index a74e0ea..25cd70a 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -24,10 +24,24 @@ async function parseError(res: Response): Promise<string> {
     return `${res.status} ${res.statusText}`;
 }
 
+// Thrown when an OK response body cannot be parsed as JSON. Distinct from
+// network/HTTP errors so callers can render a recovery flow instead of a
+// generic error banner.
+export class ResponseParseError extends Error {
+    constructor(public url: string) {
+        super(`Failed to parse response from ${url}`);
+        this.name = "ResponseParseError";
+    }
+}
+
 async function get<T>(url: string): Promise<T> {
     const res = await fetch(url);
     if (!res.ok) throw new Error(await parseError(res));
-    return res.json();
+    try {
+        return (await res.json()) as T;
+    } catch {
+        throw new ResponseParseError(url);
+    }
 }
 
 async function post(url: string): Promise<void> {
diff --git a/frontend/src/style.css b/frontend/src/style.css
index a285f24..39c39f8 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -1883,6 +1883,51 @@ body {
     padding: 48px 0;
 }
 
+.history-recovery {
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    background: var(--surface);
+    padding: 20px;
+    margin-top: 12px;
+}
+
+.history-recovery-title {
+    margin: 0 0 8px;
+    font-size: 16px;
+    font-weight: 600;
+    color: var(--red);
+}
+
+.history-recovery-msg {
+    margin: 0 0 16px;
+    font-size: 14px;
+    line-height: 1.5;
+    color: var(--text-muted);
+}
+
+.history-recovery-actions {
+    display: flex;
+    gap: 8px;
+    align-items: center;
+    flex-wrap: wrap;
+}
+
+.history-recovery-link {
+    padding: 6px 14px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: var(--surface-raised);
+    color: var(--text);
+    font-size: 12px;
+    font-weight: 600;
+    text-decoration: none;
+    -webkit-tap-highlight-color: transparent;
+}
+
+.history-recovery-link:active {
+    opacity: 0.7;
+}
+
 .history-session-row {
     display: flex;
     align-items: center;
diff --git a/frontend/src/views/history.tsx b/frontend/src/views/history.tsx
index 4a6e3f9..9294af9 100644
--- a/frontend/src/views/history.tsx
+++ b/frontend/src/views/history.tsx
@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "preact/hooks";
-import { api } from "../api";
+import { api, ResponseParseError } from "../api";
 import backSvg from "../assets/icons/back.svg?raw";
+import { ConfirmDialog } from "../components/confirm-dialog";
 import { ErrorBannerStack, useErrorStack } from "../components/error-banner";
 import { Icon } from "../components/icon";
 import { useNavigate, usePath } from "../components/router";
@@ -9,6 +10,9 @@ import { normalizeError } from "../utils";
 import { HistoryItemView } from "./history/item";
 import { HistoryListView } from "./history/list";
 
+const RECOVERY_GUIDE_URL =
+    "https://github.com/renjfk/OpenNeato/blob/main/docs/user-guide.md#recovering-corrupted-cleaning-history";
+
 export function HistoryView() {
     const navigate = useNavigate();
     const path = usePath();
@@ -18,6 +22,11 @@ export function HistoryView() {
     const [selectedMap, setSelectedMap] = useState<MapData | null>(null);
     const [mapEmpty, setMapEmpty] = useState(false);
     const [deleting, setDeleting] = useState(false);
+    // Set when the list response is unparseable (e.g. one session's metadata
+    // contains malformed JSON that breaks the surrounding response). Triggers
+    // the recovery panel instead of the normal list view.
+    const [listCorrupted, setListCorrupted] = useState(false);
+    const [confirmReset, setConfirmReset] = useState(false);
 
     // Derive selected filename from URL: /history = list, /history/<name> = detail
     const selectedName = path.startsWith("/history/") ? decodeURIComponent(path.slice(9)) : null;
@@ -35,10 +44,15 @@ export function HistoryView() {
     // Load file list only (no full session data)
     useEffect(() => {
         setLoading(true);
+        setListCorrupted(false);
         api.getHistoryList()
             .then((fileList) => setFiles(sortByDateDesc(fileList)))
             .catch((e: unknown) => {
-                errorStack.push(normalizeError(e, "Failed to load map data"));
+                if (e instanceof ResponseParseError) {
+                    setListCorrupted(true);
+                } else {
+                    errorStack.push(normalizeError(e, "Failed to load map data"));
+                }
             })
             .finally(() => setLoading(false));
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
@@ -131,6 +145,7 @@ export function HistoryView() {
         api.deleteAllHistory()
             .then(() => {
                 setFiles([]);
+                setListCorrupted(false);
                 if (selectedName) navigate("/history");
             })
             .catch((e: unknown) => {
@@ -164,7 +179,36 @@ export function HistoryView() {
             <div class="history-page">
                 {loading && <div class="history-empty">Loading...</div>}
 
-                {!loading && files.length === 0 && !showDetail && (
+                {!loading && listCorrupted && !showDetail && (
+                    <div class="history-recovery">
+                        <h2 class="history-recovery-title">Cleaning history is corrupted</h2>
+                        <p class="history-recovery-msg">
+                            One of the stored sessions contains malformed data and is preventing the list from loading.
+                            The recovery guide explains how to identify and remove the bad session(s) without losing the
+                            rest. If you'd rather not investigate, you can wipe everything in one go.
+                        </p>
+                        <div class="history-recovery-actions">
+                            <a
+                                class="history-recovery-link"
+                                href={RECOVERY_GUIDE_URL}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                            >
+                                Open recovery guide
+                            </a>
+                            <button
+                                type="button"
+                                class={`history-delete-all-btn${deleting ? " pending" : ""}`}
+                                onClick={() => setConfirmReset(true)}
+                                disabled={deleting}
+                            >
+                                Delete all history
+                            </button>
+                        </div>
+                    </div>
+                )}
+
+                {!loading && !listCorrupted && files.length === 0 && !showDetail && (
                     <HistoryListView
                         files={files}
                         hasRecording={false}
@@ -177,7 +221,7 @@ export function HistoryView() {
                     />
                 )}
 
-                {!loading && files.length > 0 && !showDetail && (
+                {!loading && !listCorrupted && files.length > 0 && !showDetail && (
                     <HistoryListView
                         files={files}
                         hasRecording={hasRecording}
@@ -198,6 +242,19 @@ export function HistoryView() {
                         recording={selectedRecording}
                     />
                 )}
+
+                {confirmReset && (
+                    <ConfirmDialog
+                        message="Delete all map data?"
+                        confirmLabel="Delete"
+                        disabled={deleting}
+                        onConfirm={() => {
+                            setConfirmReset(false);
+                            handleDeleteAll();
+                        }}
+                        onCancel={() => setConfirmReset(false)}
+                    />
+                )}
             </div>
         </>
     );

From fbdf5ad19092079e0186af9664c67453cecb0f1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Sun, 26 Apr 2026 19:42:14 +0300
Subject: [PATCH 02/44] Animate loading wave that reveals the cleaning history
 map

---
 frontend/src/views/history/helpers.ts        |  99 ++--
 frontend/src/views/history/item.tsx          |  80 ++-
 frontend/src/views/history/loading-wave.ts   | 490 +++++++++++++++++++
 frontend/src/views/history/motion-player.tsx |  15 +-
 4 files changed, 631 insertions(+), 53 deletions(-)
 create mode 100644 frontend/src/views/history/loading-wave.ts

diff --git a/frontend/src/views/history/helpers.ts b/frontend/src/views/history/helpers.ts
index 1cd1ef6..a4278f8 100644
--- a/frontend/src/views/history/helpers.ts
+++ b/frontend/src/views/history/helpers.ts
@@ -4,10 +4,67 @@ import clockSvg from "../../assets/icons/clock.svg?raw";
 import houseSvg from "../../assets/icons/house.svg?raw";
 import manualSvg from "../../assets/icons/manual.svg?raw";
 import spotSvg from "../../assets/icons/spot.svg?raw";
-import type { MapData, MapPathPoint, MapTransform } from "../../types";
+import type { MapBounds, MapData, MapPathPoint, MapTransform } from "../../types";
 import { pad2 } from "../../utils";
 
 const DEFAULT_TRANSFORM: MapTransform = { panX: 0, panY: 0, zoom: 1 };
+const MAP_PAD = 20;
+const GRID_STEP = 0.5;
+
+export interface MapProjection {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    scale: number;
+    toX: (wx: number) => number;
+    toY: (wy: number) => number;
+}
+
+// World-to-canvas projection used by the static renderer and the loading wave.
+// `pad` is in display pixels; the world is centered within the available area.
+export function computeMapProjection(displayW: number, displayH: number, bounds: MapBounds): MapProjection {
+    const { minX, maxX, minY, maxY } = bounds;
+    const worldW = maxX - minX;
+    const worldH = maxY - minY;
+    const availW = displayW - MAP_PAD * 2;
+    const availH = displayH - MAP_PAD * 2;
+    const scale = Math.min(availW / worldW, availH / worldH);
+    const offX = MAP_PAD + (availW - worldW * scale) / 2;
+    const offY = MAP_PAD + (availH - worldH * scale) / 2;
+    return {
+        minX,
+        maxX,
+        minY,
+        maxY,
+        scale,
+        toX: (wx) => offX + (wx - minX) * scale,
+        toY: (wy) => offY + (maxY - wy) * scale,
+    };
+}
+
+// 0.5m background grid. Same look in both the static map and the wave reveal.
+export function drawMapGrid(ctx: CanvasRenderingContext2D, proj: MapProjection, isDark: boolean): void {
+    ctx.strokeStyle = isDark ? "rgba(255, 255, 255, 0.04)" : "rgba(0, 0, 0, 0.06)";
+    ctx.lineWidth = 1;
+    const { minX, maxX, minY, maxY, toX, toY } = proj;
+    for (let gx = Math.floor(minX / GRID_STEP) * GRID_STEP; gx <= maxX; gx += GRID_STEP) {
+        ctx.beginPath();
+        ctx.moveTo(toX(gx), toY(minY));
+        ctx.lineTo(toX(gx), toY(maxY));
+        ctx.stroke();
+    }
+    for (let gy = Math.floor(minY / GRID_STEP) * GRID_STEP; gy <= maxY; gy += GRID_STEP) {
+        ctx.beginPath();
+        ctx.moveTo(toX(minX), toY(gy));
+        ctx.lineTo(toX(maxX), toY(gy));
+        ctx.stroke();
+    }
+}
+
+export function isDarkSurface(canvas: HTMLCanvasElement): boolean {
+    return getComputedStyle(canvas).getPropertyValue("--surface").trim().startsWith("#1");
+}
 
 export function formatDuration(secs: number): string {
     if (secs < 60) return `${secs}s`;
@@ -114,48 +171,16 @@ export function renderMap(
     ctx.translate(panX, panY);
     ctx.scale(zoom, zoom);
 
-    const { minX, maxX, minY, maxY } = map.bounds;
-    const worldW = maxX - minX;
-    const worldH = maxY - minY;
-
-    const pad = 20;
-    const availW = displayW - pad * 2;
-    const availH = displayH - pad * 2;
-    const scale = Math.min(availW / worldW, availH / worldH);
-
-    // Center the map within the canvas
-    const renderedW = worldW * scale;
-    const renderedH = worldH * scale;
-    const offX = pad + (availW - renderedW) / 2;
-    const offY = pad + (availH - renderedH) / 2;
-
-    const toX = (x: number) => offX + (x - minX) * scale;
-    const toY = (y: number) => offY + (maxY - y) * scale;
-
-    const isDark = getComputedStyle(canvas).getPropertyValue("--surface").trim().startsWith("#1");
+    const proj = computeMapProjection(displayW, displayH, map.bounds);
+    const { scale, toX, toY } = proj;
+    const isDark = isDarkSurface(canvas);
 
     // Background
     ctx.fillStyle = getComputedStyle(canvas).getPropertyValue("--surface").trim() || "#1a1a1c";
     ctx.fillRect(0, 0, displayW, displayH);
 
     // Grid lines - draw first so coverage/path render on top
-    ctx.strokeStyle = isDark ? "rgba(255, 255, 255, 0.04)" : "rgba(0, 0, 0, 0.06)";
-    ctx.lineWidth = 1;
-    const gridStep = 0.5;
-    const gridMinX = Math.floor(minX / gridStep) * gridStep;
-    const gridMinY = Math.floor(minY / gridStep) * gridStep;
-    for (let gx = gridMinX; gx <= maxX; gx += gridStep) {
-        ctx.beginPath();
-        ctx.moveTo(toX(gx), toY(minY));
-        ctx.lineTo(toX(gx), toY(maxY));
-        ctx.stroke();
-    }
-    for (let gy = gridMinY; gy <= maxY; gy += gridStep) {
-        ctx.beginPath();
-        ctx.moveTo(toX(minX), toY(gy));
-        ctx.lineTo(toX(maxX), toY(gy));
-        ctx.stroke();
-    }
+    drawMapGrid(ctx, proj, isDark);
 
     // Coverage cells — filtered by timestamp during playback
     const cellPx = map.cellSize * scale;
diff --git a/frontend/src/views/history/item.tsx b/frontend/src/views/history/item.tsx
index a9122fb..95f2c08 100644
--- a/frontend/src/views/history/item.tsx
+++ b/frontend/src/views/history/item.tsx
@@ -4,6 +4,7 @@ import { Icon } from "../../components/icon";
 import { useMapGestures } from "../../hooks/use-map-gestures";
 import type { HistoryFileInfo, MapData } from "../../types";
 import { formatDuration, renderMap } from "./helpers";
+import { Wave } from "./loading-wave";
 import { MotionPlayer } from "./motion-player";
 
 interface HistoryItemViewProps {
@@ -24,30 +25,77 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
         setCanvasEl(canvasRef.current);
     }, [map]);
 
-    // Motion playback is only available for finished sessions. While
-    // recording we fall back to the live static render (with its pulsing
-    // end marker) so the existing behaviour is unchanged.
+    // True while the wave is on screen — covers both the loading phase
+    // and the brief carrier-driven reveal phase. Flips to false when the
+    // carrier wave's trailing edge clears the canvas, at which point the
+    // wave hands the canvas back to the motion player / static render.
+    const [revealing, setRevealing] = useState<boolean>(true);
+
+    // Single Wave instance lives across the loading -> revealing
+    // transition so in-flight idle pulses carry over into the reveal
+    // phase rather than being torn down and replaced. We create it once
+    // on mount; a separate effect calls startReveal() when map arrives.
+    const waveRef = useRef<Wave | null>(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas) return;
+        const wave = new Wave({ canvas });
+        waveRef.current = wave;
+        let canceled = false;
+        wave.done.then(() => {
+            if (!canceled) setRevealing(false);
+        });
+        return () => {
+            canceled = true;
+            wave.cancel();
+            waveRef.current = null;
+        };
+    }, []);
+
+    // Kick the reveal phase the first time map data arrives. The wave
+    // keeps its existing in-flight idle pulses; the carrier joins them
+    // as one extra pulse instead of replacing the rhythm. Subsequent
+    // map updates (e.g. recording-session polling) are ignored — the
+    // reveal animation runs once.
+    const revealStartedRef = useRef(false);
+    useEffect(() => {
+        if (revealStartedRef.current) return;
+        if (!map || map.path.length === 0) return;
+        const wave = waveRef.current;
+        if (!wave) return;
+        wave.startReveal(map, transform);
+        revealStartedRef.current = true;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [map]);
+
+    // Motion playback mounts as soon as a finished session's data is
+    // present. While `revealing` is true its canvas effects are
+    // suspended via the `canvasSuspended` prop — controls render and
+    // are interactive, but it doesn't fight the wave for the canvas.
     const showPlayer = !recording && map !== null && map.path.length > 0;
 
-    // When the player is visible it owns all canvas draws. Otherwise we
-    // render the static map here so recording sessions and loading states
-    // keep working exactly as before.
+    // Static render fallback — only when the player is not present
+    // (recording sessions). The player handles its own canvas draws when
+    // it owns them. We also skip while `revealing` so the wave keeps the
+    // canvas to itself.
     useEffect(() => {
         if (showPlayer) return;
+        if (revealing) return;
         if (map && canvasRef.current) {
             renderMap(canvasRef.current, map, recording, transform);
         }
-    }, [map, recording, transform, showPlayer]);
+    }, [map, recording, transform, showPlayer, revealing]);
 
     useEffect(() => {
         if (showPlayer) return;
+        if (revealing) return;
         if (!map) return;
         const handleResize = () => {
             if (map && canvasRef.current) renderMap(canvasRef.current, map, recording, transform);
         };
         window.addEventListener("resize", handleResize);
         return () => window.removeEventListener("resize", handleResize);
-    }, [map, recording, transform, showPlayer]);
+    }, [map, recording, transform, showPlayer, revealing]);
 
     // Prefer list metadata summary (available immediately), fall back to
     // the summary parsed from the full JSONL data (available after fetch)
@@ -86,15 +134,21 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
                 </div>
             )}
 
-            {/* Map canvas */}
+            {/* Map canvas. The wave owns this canvas while `revealing`;
+                afterwards the motion player or the static-render effect
+                takes over. The empty-data message replaces it only when
+                we know the session has no usable map. */}
             <div class="history-canvas-wrap">
-                {!map && !mapEmpty && <div class="history-empty">Loading map...</div>}
                 {mapEmpty && <div class="history-empty">Not enough data to display map</div>}
-                <canvas ref={canvasRef} class="history-canvas" style={map ? undefined : { display: "none" }} />
+                <canvas ref={canvasRef} class="history-canvas" style={mapEmpty ? { display: "none" } : undefined} />
             </div>
 
-            {/* Motion player (finished sessions only) */}
-            {showPlayer && map && <MotionPlayer canvas={canvasEl} map={map} transform={transform} />}
+            {/* Motion player mounts immediately when data arrives so its
+                controls render right away. Its canvas effects are
+                suspended via `canvasSuspended` until the wave resolves. */}
+            {showPlayer && map && (
+                <MotionPlayer canvas={canvasEl} map={map} transform={transform} canvasSuspended={revealing} />
+            )}
 
             {/* Legend */}
             {map && (
diff --git a/frontend/src/views/history/loading-wave.ts b/frontend/src/views/history/loading-wave.ts
new file mode 100644
index 0000000..ecbf392
--- /dev/null
+++ b/frontend/src/views/history/loading-wave.ts
@@ -0,0 +1,490 @@
+// Loading + reveal wave animation for the cleaning history map.
+//
+// Two phases share one rAF loop and one pulse pool so the loading ->
+// revealing transition has no visual cut:
+//   1. LOADING: small noisy pulses ripple outward from near canvas center
+//      and fade out. Repeats until startReveal() or cancel().
+//   2. REVEAL: startReveal() spawns a "carrier" pulse at center. It looks
+//      like a loading pulse at birth but lives long enough to traverse
+//      the whole canvas and gradually fattens as it travels. Coverage
+//      cells, the path, and start/end markers paint in its wake.
+//
+// The wave owns the canvas while running. The host UI keeps its own
+// canvas effects suspended until `done` resolves, then takes over to
+// show the final state.
+
+import type { MapData, MapTransform } from "../../types";
+import { computeMapProjection, drawMapGrid, isDarkSurface, type MapProjection, renderMap } from "./helpers";
+
+const CELL_SIZE_M = 0.05; // matches CELL_SIZE_M in history-data.ts
+
+// Tuning — chosen empirically in /tmp/openneato-loading-demo.html.
+const PULSE_PERIOD_S = 2.2;
+const PULSE_SPAWN_S = 0.9;
+const PULSE_DRIFT = 0.4; // 0..1, how far loading pulses spawn from center
+const REVEAL_RING_MULT = 3; // carrier's final ringW = ringWidthPx * this
+const REVEAL_DUR_MS = 1600;
+const NOISE_AMP = 0.55; // 0..1, fraction of ringW used for wobble
+const REVEAL_FADE_RING_MULT = 1.5; // wake-fade and carrier overshoot in units of ringW
+const SUPPRESS_FADE_RING_MULT = 3; // gentle ramp-out for idle pulses behind the carrier
+
+// Visual sizes scale with canvas dimension so phones get a less chunky
+// wave. Desktop (>= ~600px square) lands on the original 40 / 12 values
+// because of the upper clamps; very small canvases get clamped from
+// below to keep the wave readable.
+const RING_W_RATIO = 0.067; // ~6.7% of min(W, H), targets 40px on a 600px canvas
+const RING_W_MIN = 22;
+const RING_W_MAX = 40;
+const ANIM_CELL_RATIO = 0.02; // ~2% of min(W, H), targets 12px on a 600px canvas
+const ANIM_CELL_MIN = 7;
+const ANIM_CELL_MAX = 12;
+
+function ringWidthPx(W: number, H: number): number {
+    return Math.max(RING_W_MIN, Math.min(RING_W_MAX, Math.min(W, H) * RING_W_RATIO));
+}
+
+function animCellPx(W: number, H: number): number {
+    return Math.max(ANIM_CELL_MIN, Math.min(ANIM_CELL_MAX, Math.min(W, H) * ANIM_CELL_RATIO));
+}
+
+type PulseRole = "loading" | "carrier";
+
+interface Pulse {
+    bornAt: number; // seconds since wave start
+    ox: number; // origin in canvas pixels
+    oy: number;
+    salt: number; // unique seed for noise
+    duration: number; // total lifetime in seconds
+    role: PulseRole;
+    ringWStart: number;
+    ringWEnd: number;
+    maxR: number; // target front radius at end of life, pixels
+}
+
+// Stable per-cell hash noise in [-1, 1]. No allocations, deterministic.
+function hashNoise(cx: number, cy: number, salt: number): number {
+    let h = (cx | 0) * 374761393 + (cy | 0) * 668265263 + (salt | 0) * 2147483647;
+    h = (h ^ (h >>> 13)) * 1274126177;
+    h = h ^ (h >>> 16);
+    return ((h >>> 0) / 4294967295) * 2 - 1;
+}
+
+// Smooth 2D value noise — bilinear interp of 4 corners with smoothstep.
+function valueNoise2D(x: number, y: number, salt: number): number {
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const xf = x - xi;
+    const yf = y - yi;
+    const a = hashNoise(xi, yi, salt);
+    const b = hashNoise(xi + 1, yi, salt);
+    const c = hashNoise(xi, yi + 1, salt);
+    const d = hashNoise(xi + 1, yi + 1, salt);
+    const sx = xf * xf * (3 - 2 * xf);
+    const sy = yf * yf * (3 - 2 * yf);
+    const ab = a + (b - a) * sx;
+    const cd = c + (d - c) * sx;
+    return ab + (cd - ab) * sy;
+}
+
+function pulseFront(pl: Pulse, t: number): number {
+    const age = t - pl.bornAt;
+    if (age < 0) return -Infinity;
+    const localT = age / pl.duration;
+    if (pl.role === "carrier") {
+        return localT * (pl.maxR + pl.ringWEnd * REVEAL_FADE_RING_MULT);
+    }
+    return localT * pl.maxR;
+}
+
+// Carrier ringW grows linearly across its lifetime so the wave looks
+// like a loading pulse at birth and fattens as it travels.
+function pulseRingW(pl: Pulse, t: number): number {
+    if (pl.role !== "carrier") return pl.ringWStart;
+    const localT = Math.max(0, Math.min(1, (t - pl.bornAt) / pl.duration));
+    return pl.ringWStart + (pl.ringWEnd - pl.ringWStart) * localT;
+}
+
+function pulseAlpha(pl: Pulse, t: number): number {
+    const localT = (t - pl.bornAt) / pl.duration;
+    if (pl.role === "carrier") {
+        return Math.min(1, 0.85 + 0.15 * Math.min(1, localT * 4));
+    }
+    return Math.max(0, 1 - localT);
+}
+
+function pulseDistancePx(pl: Pulse, px: number, py: number, ringW: number): number {
+    const dx = px - pl.ox;
+    const dy = py - pl.oy;
+    const dRaw = Math.sqrt(dx * dx + dy * dy);
+    const n = valueNoise2D(px * 0.06, py * 0.06, pl.salt);
+    return dRaw + n * NOISE_AMP * ringW * 0.6;
+}
+
+// Largest distance from (ox, oy) to any canvas corner.
+function farthestCorner(ox: number, oy: number, W: number, H: number): number {
+    return Math.max(Math.hypot(ox, oy), Math.hypot(W - ox, oy), Math.hypot(ox, H - oy), Math.hypot(W - ox, H - oy));
+}
+
+interface WaveOptions {
+    canvas: HTMLCanvasElement;
+}
+
+export class Wave {
+    private canvas: HTMLCanvasElement;
+    private map: MapData | null = null;
+    private transform: MapTransform | null = null;
+    private carrier: Pulse | null = null;
+    private pulses: Pulse[] = [];
+    private nextSpawnAt = 0;
+    private saltCounter = 1;
+    private startTs: number;
+    private raf: number | null = null;
+    private finished = false;
+    private resolveDone: (() => void) | null = null;
+    public readonly done: Promise<void>;
+
+    private cachedSurface: string | null = null;
+    private cachedIsDark = true;
+    private cachedDpr = 0;
+    private cachedW = 0;
+    private cachedH = 0;
+
+    constructor(opts: WaveOptions) {
+        this.canvas = opts.canvas;
+        this.startTs = performance.now();
+        this.done = new Promise<void>((resolve) => {
+            this.resolveDone = resolve;
+        });
+        this.tick = this.tick.bind(this);
+        this.raf = requestAnimationFrame(this.tick);
+    }
+
+    // Begin the reveal phase. Spawns a fresh "carrier" pulse at center
+    // and re-anchors any in-flight loading pulses onto the carrier's
+    // velocity so they expand at the same rate and expire together
+    // instead of trailing as ghosts on their own slower cadence.
+    startReveal(map: MapData, transform: MapTransform): void {
+        if (this.carrier !== null || this.finished) return;
+        this.map = map;
+        this.transform = transform;
+
+        const W = this.canvas.clientWidth;
+        const H = this.canvas.clientHeight;
+        const ox = W / 2;
+        const oy = H / 2;
+        const ringWStart = ringWidthPx(W, H);
+        const ringWEnd = ringWStart * REVEAL_RING_MULT;
+        const t = (performance.now() - this.startTs) / 1000;
+        const carrier: Pulse = {
+            bornAt: t,
+            ox,
+            oy,
+            salt: this.saltCounter++,
+            duration: REVEAL_DUR_MS / 1000,
+            role: "carrier",
+            ringWStart,
+            ringWEnd,
+            maxR: farthestCorner(ox, oy, W, H) + ringWEnd * REVEAL_FADE_RING_MULT + 20,
+        };
+
+        // Match each loading pulse's front-velocity to the carrier's
+        // *rendered* velocity. The carrier's pulseFront includes an
+        // overshoot of `ringWEnd * REVEAL_FADE_RING_MULT` past maxR so
+        // its trailing edge clears the canvas; loading pulses don't get
+        // that bonus, so we compensate via their duration. bornAt is
+        // shifted to keep the current front position continuous on the
+        // reveal frame (no jump).
+        const carrierRenderedMaxR = carrier.maxR + carrier.ringWEnd * REVEAL_FADE_RING_MULT;
+        const carrierVelocity = carrierRenderedMaxR / carrier.duration;
+        for (const pl of this.pulses) {
+            if (pl.role !== "loading") continue;
+            const oldFront = pulseFront(pl, t);
+            const newDuration = pl.maxR / carrierVelocity;
+            pl.duration = newDuration;
+            pl.bornAt = t - (oldFront / pl.maxR) * newDuration;
+        }
+
+        this.pulses.push(carrier);
+        this.carrier = carrier;
+    }
+
+    cancel(): void {
+        this.finish();
+    }
+
+    // Stop the rAF loop and resolve `done`. Idempotent.
+    private finish(): void {
+        if (this.finished) return;
+        this.finished = true;
+        if (this.raf !== null) cancelAnimationFrame(this.raf);
+        this.raf = null;
+        this.resolveDone?.();
+    }
+
+    private spawnLoadingPulse(t: number): void {
+        const W = this.canvas.clientWidth;
+        const H = this.canvas.clientHeight;
+        const ox = W / 2 + (Math.random() - 0.5) * W * 0.5 * PULSE_DRIFT;
+        const oy = H / 2 + (Math.random() - 0.5) * H * 0.5 * PULSE_DRIFT;
+        const ringW = ringWidthPx(W, H);
+        this.pulses.push({
+            bornAt: t,
+            ox,
+            oy,
+            salt: this.saltCounter++,
+            duration: PULSE_PERIOD_S * (0.85 + Math.random() * 0.3),
+            role: "loading",
+            ringWStart: ringW,
+            ringWEnd: ringW,
+            maxR: farthestCorner(ox, oy, W, H) + 20,
+        });
+    }
+
+    private tick(now: number): void {
+        if (this.finished) return;
+        const t = (now - this.startTs) / 1000;
+
+        if (this.carrier === null) {
+            if (t >= this.nextSpawnAt) {
+                this.spawnLoadingPulse(t);
+                this.nextSpawnAt = t + PULSE_SPAWN_S * (0.7 + Math.random() * 0.6);
+            }
+            if (this.pulses.length === 0) this.spawnLoadingPulse(t);
+        }
+
+        // Drop expired pulses
+        this.pulses = this.pulses.filter((pl) => t - pl.bornAt < pl.duration * 1.2);
+
+        this.render(t);
+
+        // Reveal completion: the carrier's trailing edge has cleared the
+        // farthest visible canvas pixel. Hand off to the host UI.
+        if (this.carrier !== null && this.map !== null && this.transform !== null) {
+            const front = pulseFront(this.carrier, t);
+            const ringW = pulseRingW(this.carrier, t);
+            if (front - ringW >= this.carrier.maxR) {
+                renderMap(this.canvas, this.map, false, this.transform);
+                this.finish();
+                return;
+            }
+        }
+
+        this.raf = requestAnimationFrame(this.tick);
+    }
+
+    private ensureCanvasSized(): { ctx: CanvasRenderingContext2D; W: number; H: number } | null {
+        const ctx = this.canvas.getContext("2d");
+        if (!ctx) return null;
+        const dpr = window.devicePixelRatio || 1;
+        const W = this.canvas.clientWidth;
+        const H = this.canvas.clientHeight;
+        if (W !== this.cachedW || H !== this.cachedH || dpr !== this.cachedDpr) {
+            this.canvas.width = W * dpr;
+            this.canvas.height = H * dpr;
+            this.cachedDpr = dpr;
+            this.cachedW = W;
+            this.cachedH = H;
+            this.cachedSurface = null;
+        }
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        if (this.cachedSurface === null) {
+            this.cachedSurface = getComputedStyle(this.canvas).getPropertyValue("--surface").trim();
+            this.cachedIsDark = isDarkSurface(this.canvas);
+        }
+        return { ctx, W, H };
+    }
+
+    private render(t: number): void {
+        const sized = this.ensureCanvasSized();
+        if (!sized) return;
+        const { ctx, W: displayW, H: displayH } = sized;
+        const isDark = this.cachedIsDark;
+
+        ctx.fillStyle = this.cachedSurface || "#1a1a1c";
+        ctx.fillRect(0, 0, displayW, displayH);
+
+        // Reveal phase paints the map beneath the wave foreground.
+        // Loading phase has no map data, so the wave runs on the bare
+        // background.
+        const proj =
+            this.carrier && this.map?.bounds ? computeMapProjection(displayW, displayH, this.map.bounds) : null;
+
+        if (proj) {
+            const tf = this.transform ?? { panX: 0, panY: 0, zoom: 1 };
+            ctx.translate(tf.panX, tf.panY);
+            ctx.scale(tf.zoom, tf.zoom);
+            drawMapGrid(ctx, proj, isDark);
+            this.drawRevealCoverage(ctx, t, proj, isDark);
+            this.drawRevealPath(ctx, t, proj, isDark);
+        }
+
+        this.drawWaveCells(ctx, t, displayW, displayH, isDark);
+
+        if (proj) this.drawRevealMarkers(ctx, t, proj);
+    }
+
+    // Paint real coverage cells at native 5cm resolution behind the
+    // carrier wave front. Opacity ramps from 0 at the front edge to full
+    // settled coverage opacity within ~1.5 ringW behind the front.
+    private drawRevealCoverage(ctx: CanvasRenderingContext2D, t: number, proj: MapProjection, isDark: boolean): void {
+        const carrier = this.carrier;
+        const map = this.map;
+        if (!carrier || !map) return;
+        const ringW = pulseRingW(carrier, t);
+        const front = pulseFront(carrier, t);
+        const cellPx = CELL_SIZE_M * proj.scale;
+        const settledA = isDark ? 0.15 : 0.22;
+        const baseRgb = isDark ? "52, 199, 89" : "22, 130, 50";
+        const fadeWidth = ringW * REVEAL_FADE_RING_MULT;
+
+        const buckets: number[][] = Array.from({ length: 10 }, () => []);
+
+        for (const cell of map.coverage) {
+            const [cx, cy] = cell;
+            const px = proj.toX(cx * CELL_SIZE_M);
+            const py = proj.toY(cy * CELL_SIZE_M);
+            const edge = front - pulseDistancePx(carrier, px, py, ringW);
+            if (edge <= 0) continue;
+            const settle = Math.min(1, edge / fadeWidth);
+            const bIdx = Math.min(9, (settle * 10) | 0);
+            buckets[bIdx].push(px - cellPx / 2, py - cellPx / 2);
+        }
+
+        for (let i = 0; i < 10; i++) {
+            const arr = buckets[i];
+            if (arr.length === 0) continue;
+            ctx.fillStyle = `rgba(${baseRgb}, ${(settledA * (i + 1)) / 10})`;
+            for (let j = 0; j < arr.length; j += 2) {
+                ctx.fillRect(arr[j], arr[j + 1], cellPx, cellPx);
+            }
+        }
+    }
+
+    private drawRevealPath(ctx: CanvasRenderingContext2D, t: number, proj: MapProjection, isDark: boolean): void {
+        const carrier = this.carrier;
+        const map = this.map;
+        if (!carrier || !map || map.path.length < 2) return;
+        const ringW = pulseRingW(carrier, t);
+        const front = pulseFront(carrier, t);
+
+        ctx.strokeStyle = isDark ? "rgba(249, 235, 178, 0.6)" : "rgba(180, 140, 40, 0.5)";
+        ctx.lineWidth = 2;
+        ctx.lineJoin = "round";
+        ctx.lineCap = "round";
+        ctx.beginPath();
+        let drawing = false;
+        for (const pt of map.path) {
+            const ppx = proj.toX(pt.x);
+            const ppy = proj.toY(pt.y);
+            const reached = front - pulseDistancePx(carrier, ppx, ppy, ringW) > 0;
+            if (reached) {
+                if (drawing) ctx.lineTo(ppx, ppy);
+                else {
+                    ctx.moveTo(ppx, ppy);
+                    drawing = true;
+                }
+            } else {
+                drawing = false;
+            }
+        }
+        ctx.stroke();
+    }
+
+    private drawRevealMarkers(ctx: CanvasRenderingContext2D, t: number, proj: MapProjection): void {
+        const carrier = this.carrier;
+        const map = this.map;
+        if (!carrier || !map || map.path.length === 0) return;
+        const ringW = pulseRingW(carrier, t);
+        const front = pulseFront(carrier, t);
+        const fadeWidth = ringW * REVEAL_FADE_RING_MULT;
+
+        const drawDot = (worldX: number, worldY: number, r: number, g: number, b: number) => {
+            const px = proj.toX(worldX);
+            const py = proj.toY(worldY);
+            const edge = front - pulseDistancePx(carrier, px, py, ringW);
+            if (edge < 0) return;
+            const a = Math.min(1, edge / fadeWidth);
+            ctx.beginPath();
+            ctx.arc(px, py, 5, 0, Math.PI * 2);
+            ctx.fillStyle = `rgba(${r}, ${g}, ${b}, ${0.9 * a})`;
+            ctx.fill();
+        };
+
+        const start = map.path[0];
+        drawDot(start.x, start.y, 52, 199, 89);
+        if (map.path.length > 1) {
+            const end = map.path[map.path.length - 1];
+            drawDot(end.x, end.y, 255, 69, 58);
+        }
+    }
+
+    // Foreground wave cells on a fixed-pixel grid (independent of map
+    // scale). Loading and carrier pulses share the same brightness
+    // formula so the carrier reads as a continuation of the rhythm.
+    // Behind the carrier front, contributions are suppressed with a soft
+    // ramp so idle pulses don't snap-cut to invisible.
+    private drawWaveCells(
+        ctx: CanvasRenderingContext2D,
+        t: number,
+        displayW: number,
+        displayH: number,
+        isDark: boolean,
+    ): void {
+        const baseRgb = isDark ? "52, 199, 89" : "22, 130, 50";
+        const cellPx = animCellPx(displayW, displayH);
+        const cols = Math.ceil(displayW / cellPx) + 2;
+        const rows = Math.ceil(displayH / cellPx) + 2;
+
+        const carrier = this.carrier;
+        const carrierRingW = carrier ? pulseRingW(carrier, t) : 0;
+        const carrierFront = carrier ? pulseFront(carrier, t) : 0;
+        const suppressFadeWidth = carrierRingW * SUPPRESS_FADE_RING_MULT;
+        const tickSeed = (t * 4) | 0;
+
+        const buckets: number[][] = Array.from({ length: 10 }, () => []);
+
+        for (let cy = 0; cy < rows; cy++) {
+            for (let cx = 0; cx < cols; cx++) {
+                const px = cx * cellPx;
+                const py = cy * cellPx;
+
+                let suppress = 1;
+                if (carrier) {
+                    const edge = carrierFront - pulseDistancePx(carrier, px, py, carrierRingW);
+                    if (edge > carrierRingW) {
+                        suppress = Math.max(0, 1 - (edge - carrierRingW) / suppressFadeWidth);
+                    }
+                }
+                if (suppress <= 0.01) continue;
+
+                let bright = 0;
+                for (const pl of this.pulses) {
+                    const ringW = pulseRingW(pl, t);
+                    const front = pulseFront(pl, t);
+                    if (front <= -ringW) continue;
+                    const delta = front - pulseDistancePx(pl, px, py, ringW);
+                    const absDelta = delta < 0 ? -delta : delta;
+                    if (absDelta < ringW) {
+                        const f = 1 - absDelta / ringW;
+                        const flicker = 0.9 + 0.1 * hashNoise(cx, cy, pl.salt + tickSeed);
+                        const b = f * pulseAlpha(pl, t) * flicker;
+                        if (b > bright) bright = b;
+                    }
+                }
+                bright *= suppress;
+                if (bright <= 0.02) continue;
+
+                buckets[Math.min(9, (bright * 10) | 0)].push(px, py);
+            }
+        }
+
+        for (let i = 0; i < 10; i++) {
+            const arr = buckets[i];
+            if (arr.length === 0) continue;
+            ctx.fillStyle = `rgba(${baseRgb}, ${(0.85 * (i + 1)) / 10})`;
+            for (let j = 0; j < arr.length; j += 2) {
+                ctx.fillRect(arr[j], arr[j + 1], cellPx, cellPx);
+            }
+        }
+    }
+}
diff --git a/frontend/src/views/history/motion-player.tsx b/frontend/src/views/history/motion-player.tsx
index d9b2bcf..ccc7e30 100644
--- a/frontend/src/views/history/motion-player.tsx
+++ b/frontend/src/views/history/motion-player.tsx
@@ -18,9 +18,13 @@ interface MotionPlayerProps {
     // Seconds of session time played per real second. 1x replays in real time,
     // higher values speed the playback up proportionally.
     speed?: number;
+    // When true, the player's controls render as normal but it does NOT
+    // touch the canvas. Used by the host UI to keep play/restart/scrubber
+    // visible while the loading wave still owns the canvas drawing surface.
+    canvasSuspended?: boolean;
 }
 
-export function MotionPlayer({ canvas, map, transform, speed = 8 }: MotionPlayerProps) {
+export function MotionPlayer({ canvas, map, transform, speed = 8, canvasSuspended }: MotionPlayerProps) {
     const duration = sessionDuration(map);
     const [playing, setPlaying] = useState(false);
     // Start at the end of the timeline so a freshly opened session shows the
@@ -40,20 +44,25 @@ export function MotionPlayer({ canvas, map, transform, speed = 8 }: MotionPlayer
 
     // Re-render canvas whenever the time, transform, or map changes. This
     // runs on every animation frame tick via the setCurrentTime update.
+    // While `canvasSuspended` is true the wave owns the canvas, so we
+    // skip painting; once the host clears the suspension this effect
+    // re-runs and lays down the current playhead state.
     useEffect(() => {
+        if (canvasSuspended) return;
         if (!canvas || !map) return;
         renderMap(canvas, map, false, transform, currentTime);
-    }, [canvas, map, transform, currentTime]);
+    }, [canvas, map, transform, currentTime, canvasSuspended]);
 
     // Re-render on resize — canvas backing store gets invalidated.
     useEffect(() => {
+        if (canvasSuspended) return;
         if (!canvas) return;
         const onResize = () => {
             renderMap(canvas, map, false, transform, timeRef.current);
         };
         window.addEventListener("resize", onResize);
         return () => window.removeEventListener("resize", onResize);
-    }, [canvas, map, transform]);
+    }, [canvas, map, transform, canvasSuspended]);
 
     // Reset to the completed map whenever the session switches. The scrubber
     // anchors at `duration` so the user sees the full session at rest.

From 942b52323e8da92eeaa97751796a192c85b9f8a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Sun, 26 Apr 2026 23:33:11 +0300
Subject: [PATCH 03/44] Update all dependencies to latest versions

---
 firmware/src/data_logger.cpp       |   21 +-
 flash/go.mod                       |    8 +-
 flash/go.sum                       |   12 +-
 frontend/biome.json                |    2 +-
 frontend/mock/server.js            |   15 +-
 frontend/package-lock.json         | 1437 ++++++++++++----------------
 frontend/package.json              |   11 +-
 frontend/scripts/embed_frontend.js |    8 +-
 frontend/src/svg.d.ts              |    3 +
 frontend/vite.config.ts            |    5 +-
 platformio.ini                     |    2 +-
 11 files changed, 653 insertions(+), 871 deletions(-)

diff --git a/firmware/src/data_logger.cpp b/firmware/src/data_logger.cpp
index b768ce8..f8e53f4 100644
--- a/firmware/src/data_logger.cpp
+++ b/firmware/src/data_logger.cpp
@@ -452,18 +452,15 @@ void DataLogger::logEvent(const String& type, const std::vector<Field>& fields)
 }
 
 static const char *httpMethodStr(WebRequestMethodComposite method) {
-    switch (method) {
-        case HTTP_GET:
-            return "GET";
-        case HTTP_POST:
-            return "POST";
-        case HTTP_DELETE:
-            return "DELETE";
-        case HTTP_PUT:
-            return "PUT";
-        default:
-            return "UNKNOWN";
-    }
+    if (method == HTTP_GET)
+        return "GET";
+    if (method == HTTP_POST)
+        return "POST";
+    if (method == HTTP_DELETE)
+        return "DELETE";
+    if (method == HTTP_PUT)
+        return "PUT";
+    return "UNKNOWN";
 }
 
 void DataLogger::logRequest(WebRequestMethodComposite method, const String& path, int status, unsigned long ms) {
diff --git a/flash/go.mod b/flash/go.mod
index fbb3bc3..d807f71 100644
--- a/flash/go.mod
+++ b/flash/go.mod
@@ -1,13 +1,13 @@
 module github.com/renjfk/OpenNeato/flash
 
-go 1.26.1
+go 1.26.2
 
 require (
 	go.bug.st/serial v1.6.4
-	golang.org/x/term v0.41.0
+	golang.org/x/term v0.42.0
 )
 
 require (
-	github.com/creack/goselect v0.1.2 // indirect
-	golang.org/x/sys v0.42.0 // indirect
+	github.com/creack/goselect v0.1.3 // indirect
+	golang.org/x/sys v0.43.0 // indirect
 )
diff --git a/flash/go.sum b/flash/go.sum
index 5acd17d..d483e31 100644
--- a/flash/go.sum
+++ b/flash/go.sum
@@ -1,5 +1,5 @@
-github.com/creack/goselect v0.1.2 h1:2DNy14+JPjRBgPzAd1thbQp4BSIihxcBf0IXhQXDRa0=
-github.com/creack/goselect v0.1.2/go.mod h1:a/NhLweNvqIYMuxcMOuWY516Cimucms3DglDzQP3hKY=
+github.com/creack/goselect v0.1.3 h1:MaGNMclRo7P2Jl21hBpR1Cn33ITSbKP6E49RtfblLKc=
+github.com/creack/goselect v0.1.3/go.mod h1:a/NhLweNvqIYMuxcMOuWY516Cimucms3DglDzQP3hKY=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -8,9 +8,9 @@ github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcU
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 go.bug.st/serial v1.6.4 h1:7FmqNPgVp3pu2Jz5PoPtbZ9jJO5gnEnZIvnI1lzve8A=
 go.bug.st/serial v1.6.4/go.mod h1:nofMJxTeNVny/m6+KaafC6vJGj3miwQZ6vW4BZUGJPI=
-golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
+golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/frontend/biome.json b/frontend/biome.json
index 928bf20..67e4982 100644
--- a/frontend/biome.json
+++ b/frontend/biome.json
@@ -1,5 +1,5 @@
 {
-    "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
 
     "files": {
         "includes": [
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index 9243ccd..f2c57d0 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -3,10 +3,13 @@
 // Runs as a Vite plugin — hooks into Vite's dev server middleware
 // To test different scenarios, edit the `state` object directly and reload
 
-const { createHash } = require("node:crypto");
-const { execSync } = require("node:child_process");
-const { readFileSync, readdirSync } = require("node:fs");
-const { join } = require("node:path");
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // --- Helpers ---
 
@@ -936,7 +939,7 @@ const handleRequest = async (req, res) => {
         const bodyStr = body.toString("binary");
         // Extract filename from Content-Disposition header in multipart body
         const nameMatch = bodyStr.match(/filename="([^"]+)"/);
-        if (!nameMatch || !nameMatch[1].endsWith(".jsonl")) {
+        if (!nameMatch?.[1].endsWith(".jsonl")) {
             return sendError(res, "Invalid file: expected a .jsonl session file", 400);
         }
         const filename = nameMatch[1];
@@ -1201,4 +1204,4 @@ function mockApiPlugin() {
     };
 }
 
-module.exports = { mockApiPlugin };
+export { mockApiPlugin };
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index c65caf3..ce0a779 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,13 +8,13 @@
             "name": "neato-web",
             "version": "0.0.1",
             "dependencies": {
-                "preact": "10.29.0"
+                "preact": "10.29.1"
             },
             "devDependencies": {
-                "@biomejs/biome": "2.4.7",
-                "@preact/preset-vite": "2.10.3",
-                "typescript": "5.9.3",
-                "vite": "7.3.1"
+                "@biomejs/biome": "2.4.13",
+                "@preact/preset-vite": "2.10.5",
+                "typescript": "6.0.3",
+                "vite": "8.0.10"
             }
         },
         "node_modules/@babel/code-frame": {
@@ -333,9 +333,9 @@
             }
         },
         "node_modules/@biomejs/biome": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.7.tgz",
-            "integrity": "sha512-vXrgcmNGZ4lpdwZSpMf1hWw1aWS6B+SyeSYKTLrNsiUsAdSRN0J4d/7mF3ogJFbIwFFSOL3wT92Zzxia/d5/ng==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.13.tgz",
+            "integrity": "sha512-gLXOwkOBBg0tr7bDsqlkIh4uFeKuMjxvqsrb1Tukww1iDmHcfr4Uu8MoQxp0Rcte+69+osRNWXwHsu/zxT6XqA==",
             "dev": true,
             "license": "MIT OR Apache-2.0",
             "bin": {
@@ -349,20 +349,20 @@
                 "url": "https://opencollective.com/biome"
             },
             "optionalDependencies": {
-                "@biomejs/cli-darwin-arm64": "2.4.7",
-                "@biomejs/cli-darwin-x64": "2.4.7",
-                "@biomejs/cli-linux-arm64": "2.4.7",
-                "@biomejs/cli-linux-arm64-musl": "2.4.7",
-                "@biomejs/cli-linux-x64": "2.4.7",
-                "@biomejs/cli-linux-x64-musl": "2.4.7",
-                "@biomejs/cli-win32-arm64": "2.4.7",
-                "@biomejs/cli-win32-x64": "2.4.7"
+                "@biomejs/cli-darwin-arm64": "2.4.13",
+                "@biomejs/cli-darwin-x64": "2.4.13",
+                "@biomejs/cli-linux-arm64": "2.4.13",
+                "@biomejs/cli-linux-arm64-musl": "2.4.13",
+                "@biomejs/cli-linux-x64": "2.4.13",
+                "@biomejs/cli-linux-x64-musl": "2.4.13",
+                "@biomejs/cli-win32-arm64": "2.4.13",
+                "@biomejs/cli-win32-x64": "2.4.13"
             }
         },
         "node_modules/@biomejs/cli-darwin-arm64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.7.tgz",
-            "integrity": "sha512-Oo0cF5mHzmvDmTXw8XSjhCia8K6YrZnk7aCS54+/HxyMdZMruMO3nfpDsrlar/EQWe41r1qrwKiCa2QDYHDzWA==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.13.tgz",
+            "integrity": "sha512-2KImO1jhNFBa2oWConyr0x6flxbQpGKv6902uGXpYM62Xyem8U80j441SyUJ8KyngsmKbQjeIv1q2CQfDkNnYg==",
             "cpu": [
                 "arm64"
             ],
@@ -377,9 +377,9 @@
             }
         },
         "node_modules/@biomejs/cli-darwin-x64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.7.tgz",
-            "integrity": "sha512-I+cOG3sd/7HdFtvDSnF9QQPrWguUH7zrkIMMykM3PtfWU9soTcS2yRb9Myq6MHmzbeCT08D1UmY+BaiMl5CcoQ==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.13.tgz",
+            "integrity": "sha512-BKrJklbaFN4p1Ts4kPBczo+PkbsHQg57kmJ+vON9u2t6uN5okYHaSr7h/MutPCWQgg2lglaWoSmm+zhYW+oOkg==",
             "cpu": [
                 "x64"
             ],
@@ -394,9 +394,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.7.tgz",
-            "integrity": "sha512-om6FugwmibzfP/6ALj5WRDVSND4H2G9X0nkI1HZpp2ySf9lW2j0X68oQSaHEnls6666oy4KDsc5RFjT4m0kV0w==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.13.tgz",
+            "integrity": "sha512-NzkUDSqfvMBrPplKgVr3aXLHZ2NEELvvF4vZxXulEylKWIGqlvNEcwUcj9OLrn75TD3lJ/GIqCVlBwd1MZCuYQ==",
             "cpu": [
                 "arm64"
             ],
@@ -414,9 +414,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64-musl": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.7.tgz",
-            "integrity": "sha512-I2NvM9KPb09jWml93O2/5WMfNR7Lee5Latag1JThDRMURVhPX74p9UDnyTw3Ae6cE1DgXfw7sqQgX7rkvpc0vw==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.13.tgz",
+            "integrity": "sha512-U5MsuBQW25dXaYtqWWSPM3P96H6Y+fHuja3TQpMNnylocHW0tEbtFTDlUj6oM+YJLntvEkQy4grBvQNUD4+RCg==",
             "cpu": [
                 "arm64"
             ],
@@ -434,9 +434,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.7.tgz",
-            "integrity": "sha512-bV8/uo2Tj+gumnk4sUdkerWyCPRabaZdv88IpbmDWARQQoA/Q0YaqPz1a+LSEDIL7OfrnPi9Hq1Llz4ZIGyIQQ==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.13.tgz",
+            "integrity": "sha512-Az3ZZedYRBo9EQzNnD9SxFcR1G5QsGo6VEc2hIyVPZ1rdKwee/7E9oeBBZFpE8Z44ekxsDQBqbiWGW5ShOhUSQ==",
             "cpu": [
                 "x64"
             ],
@@ -454,9 +454,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64-musl": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.7.tgz",
-            "integrity": "sha512-00kx4YrBMU8374zd2wHuRV5wseh0rom5HqRND+vDldJPrWwQw+mzd/d8byI9hPx926CG+vWzq6AeiT7Yi5y59g==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.13.tgz",
+            "integrity": "sha512-Z601MienRgTBDza/+u2CH3RSrWoXo9rtr8NK6A4KJzqGgfxx+H3VlyLgTJ4sRo40T3pIsqpTmiOQEvYzQvBRvQ==",
             "cpu": [
                 "x64"
             ],
@@ -474,9 +474,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-arm64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.7.tgz",
-            "integrity": "sha512-hOUHBMlFCvDhu3WCq6vaBoG0dp0LkWxSEnEEsxxXvOa9TfT6ZBnbh72A/xBM7CBYB7WgwqboetzFEVDnMxelyw==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.13.tgz",
+            "integrity": "sha512-Px9PS2B5/Q183bUwy/5VHqp3J2lzdOCeVGzMpphYfl8oSa7VDCqenBdqWpy6DCy/en4Rbf/Y1RieZF6dJPcc9A==",
             "cpu": [
                 "arm64"
             ],
@@ -491,9 +491,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-x64": {
-            "version": "2.4.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.7.tgz",
-            "integrity": "sha512-qEpGjSkPC3qX4ycbMUthXvi9CkRq7kZpkqMY1OyhmYlYLnANnooDQ7hDerM8+0NJ+DZKVnsIc07h30XOpt7LtQ==",
+            "version": "2.4.13",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.13.tgz",
+            "integrity": "sha512-tTcMkXyBrmHi9BfrD2VNHs/5rYIUKETqsBlYOvSAABwBkJhSDVb5e7wPukftsQbO3WzQkXe6kaztC6WtUOXSoQ==",
             "cpu": [
                 "x64"
             ],
@@ -507,446 +507,38 @@
                 "node": ">=14.21.3"
             }
         },
-        "node_modules/@esbuild/aix-ppc64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz",
-            "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==",
-            "cpu": [
-                "ppc64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "aix"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/android-arm": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz",
-            "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==",
-            "cpu": [
-                "arm"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "android"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/android-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz",
-            "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "android"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/android-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz",
-            "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "android"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/darwin-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz",
-            "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/darwin-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz",
-            "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/freebsd-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz",
-            "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "freebsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/freebsd-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz",
-            "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "freebsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-arm": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz",
-            "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==",
-            "cpu": [
-                "arm"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz",
-            "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-ia32": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz",
-            "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==",
-            "cpu": [
-                "ia32"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-loong64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz",
-            "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==",
-            "cpu": [
-                "loong64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-mips64el": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz",
-            "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==",
-            "cpu": [
-                "mips64el"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-ppc64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz",
-            "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==",
-            "cpu": [
-                "ppc64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-riscv64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz",
-            "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==",
-            "cpu": [
-                "riscv64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-s390x": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz",
-            "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==",
-            "cpu": [
-                "s390x"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/linux-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz",
-            "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/netbsd-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz",
-            "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "netbsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/netbsd-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz",
-            "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "netbsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/openbsd-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz",
-            "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "openbsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/openbsd-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz",
-            "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "openbsd"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/openharmony-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz",
-            "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "openharmony"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/sunos-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz",
-            "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "sunos"
-            ],
-            "engines": {
-                "node": ">=18"
-            }
-        },
-        "node_modules/@esbuild/win32-arm64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz",
-            "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==",
-            "cpu": [
-                "arm64"
-            ],
+        "node_modules/@emnapi/core": {
+            "version": "1.10.0",
+            "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
+            "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
             "dev": true,
             "license": "MIT",
             "optional": true,
-            "os": [
-                "win32"
-            ],
-            "engines": {
-                "node": ">=18"
+            "dependencies": {
+                "@emnapi/wasi-threads": "1.2.1",
+                "tslib": "^2.4.0"
             }
         },
-        "node_modules/@esbuild/win32-ia32": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz",
-            "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==",
-            "cpu": [
-                "ia32"
-            ],
+        "node_modules/@emnapi/runtime": {
+            "version": "1.10.0",
+            "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+            "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
             "dev": true,
             "license": "MIT",
             "optional": true,
-            "os": [
-                "win32"
-            ],
-            "engines": {
-                "node": ">=18"
+            "dependencies": {
+                "tslib": "^2.4.0"
             }
         },
-        "node_modules/@esbuild/win32-x64": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz",
-            "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==",
-            "cpu": [
-                "x64"
-            ],
+        "node_modules/@emnapi/wasi-threads": {
+            "version": "1.2.1",
+            "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+            "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
             "dev": true,
             "license": "MIT",
             "optional": true,
-            "os": [
-                "win32"
-            ],
-            "engines": {
-                "node": ">=18"
+            "dependencies": {
+                "tslib": "^2.4.0"
             }
         },
         "node_modules/@jridgewell/gen-mapping": {
@@ -999,10 +591,39 @@
                 "@jridgewell/sourcemap-codec": "^1.4.14"
             }
         },
+        "node_modules/@napi-rs/wasm-runtime": {
+            "version": "1.1.4",
+            "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
+            "integrity": "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==",
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "dependencies": {
+                "@tybys/wasm-util": "^0.10.1"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            },
+            "peerDependencies": {
+                "@emnapi/core": "^1.7.1",
+                "@emnapi/runtime": "^1.7.1"
+            }
+        },
+        "node_modules/@oxc-project/types": {
+            "version": "0.127.0",
+            "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz",
+            "integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://github.com/sponsors/Boshen"
+            }
+        },
         "node_modules/@preact/preset-vite": {
-            "version": "2.10.3",
-            "resolved": "https://registry.npmjs.org/@preact/preset-vite/-/preset-vite-2.10.3.tgz",
-            "integrity": "sha512-1SiS+vFItpkNdBs7q585PSAIln0wBeBdcpJYbzPs1qipsb/FssnkUioNXuRsb8ZnU8YEQHr+3v8+/mzWSnTQmg==",
+            "version": "2.10.5",
+            "resolved": "https://registry.npmjs.org/@preact/preset-vite/-/preset-vite-2.10.5.tgz",
+            "integrity": "sha512-p0vJpxiVO7KWWazWny3LUZ+saXyZKWv6Ju0bYMWNJRp2YveufRPgSUB1C4MTqGJfz07EehMgfN+AJNwQy+w6Iw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -1012,12 +633,14 @@
                 "@rollup/pluginutils": "^5.0.0",
                 "babel-plugin-transform-hook-names": "^1.0.2",
                 "debug": "^4.4.3",
+                "magic-string": "^0.30.21",
                 "picocolors": "^1.1.1",
-                "vite-prerender-plugin": "^0.5.8"
+                "vite-prerender-plugin": "^0.5.8",
+                "zimmerframe": "^1.1.4"
             },
             "peerDependencies": {
                 "@babel/core": "7.x",
-                "vite": "2.x || 3.x || 4.x || 5.x || 6.x || 7.x"
+                "vite": "2.x || 3.x || 4.x || 5.x || 6.x || 7.x || 8.x"
             }
         },
         "node_modules/@prefresh/babel-plugin": {
@@ -1089,47 +712,10 @@
                 "url": "https://github.com/sponsors/jonschlinkert"
             }
         },
-        "node_modules/@rollup/pluginutils": {
-            "version": "5.3.0",
-            "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
-            "integrity": "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==",
-            "dev": true,
-            "license": "MIT",
-            "dependencies": {
-                "@types/estree": "^1.0.0",
-                "estree-walker": "^2.0.2",
-                "picomatch": "^4.0.2"
-            },
-            "engines": {
-                "node": ">=14.0.0"
-            },
-            "peerDependencies": {
-                "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
-            },
-            "peerDependenciesMeta": {
-                "rollup": {
-                    "optional": true
-                }
-            }
-        },
-        "node_modules/@rollup/rollup-android-arm-eabi": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.59.0.tgz",
-            "integrity": "sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==",
-            "cpu": [
-                "arm"
-            ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "android"
-            ]
-        },
-        "node_modules/@rollup/rollup-android-arm64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.59.0.tgz",
-            "integrity": "sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q==",
+        "node_modules/@rolldown/binding-android-arm64": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
+            "integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==",
             "cpu": [
                 "arm64"
             ],
@@ -1138,12 +724,15 @@
             "optional": true,
             "os": [
                 "android"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-darwin-arm64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.59.0.tgz",
-            "integrity": "sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg==",
+        "node_modules/@rolldown/binding-darwin-arm64": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
+            "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
             "cpu": [
                 "arm64"
             ],
@@ -1152,12 +741,15 @@
             "optional": true,
             "os": [
                 "darwin"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-darwin-x64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.59.0.tgz",
-            "integrity": "sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w==",
+        "node_modules/@rolldown/binding-darwin-x64": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
+            "integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==",
             "cpu": [
                 "x64"
             ],
@@ -1166,26 +758,15 @@
             "optional": true,
             "os": [
                 "darwin"
-            ]
-        },
-        "node_modules/@rollup/rollup-freebsd-arm64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.59.0.tgz",
-            "integrity": "sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA==",
-            "cpu": [
-                "arm64"
             ],
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "freebsd"
-            ]
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-freebsd-x64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.59.0.tgz",
-            "integrity": "sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg==",
+        "node_modules/@rolldown/binding-freebsd-x64": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz",
+            "integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==",
             "cpu": [
                 "x64"
             ],
@@ -1194,46 +775,32 @@
             "optional": true,
             "os": [
                 "freebsd"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.59.0.tgz",
-            "integrity": "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==",
-            "cpu": [
-                "arm"
             ],
-            "dev": true,
-            "libc": [
-                "glibc"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.59.0.tgz",
-            "integrity": "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==",
+        "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz",
+            "integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==",
             "cpu": [
                 "arm"
             ],
             "dev": true,
-            "libc": [
-                "musl"
-            ],
             "license": "MIT",
             "optional": true,
             "os": [
                 "linux"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-arm64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.59.0.tgz",
-            "integrity": "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==",
+        "node_modules/@rolldown/binding-linux-arm64-gnu": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz",
+            "integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==",
             "cpu": [
                 "arm64"
             ],
@@ -1245,12 +812,15 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-arm64-musl": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.59.0.tgz",
-            "integrity": "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==",
+        "node_modules/@rolldown/binding-linux-arm64-musl": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz",
+            "integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==",
             "cpu": [
                 "arm64"
             ],
@@ -1262,84 +832,19 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-loong64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.59.0.tgz",
-            "integrity": "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==",
-            "cpu": [
-                "loong64"
             ],
-            "dev": true,
-            "libc": [
-                "glibc"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-loong64-musl": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.59.0.tgz",
-            "integrity": "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==",
-            "cpu": [
-                "loong64"
-            ],
-            "dev": true,
-            "libc": [
-                "musl"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.59.0.tgz",
-            "integrity": "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==",
-            "cpu": [
-                "ppc64"
-            ],
-            "dev": true,
-            "libc": [
-                "glibc"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-ppc64-musl": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.59.0.tgz",
-            "integrity": "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==",
+        "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz",
+            "integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==",
             "cpu": [
                 "ppc64"
             ],
             "dev": true,
-            "libc": [
-                "musl"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.59.0.tgz",
-            "integrity": "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==",
-            "cpu": [
-                "riscv64"
-            ],
-            "dev": true,
             "libc": [
                 "glibc"
             ],
@@ -1347,29 +852,15 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
-        },
-        "node_modules/@rollup/rollup-linux-riscv64-musl": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.59.0.tgz",
-            "integrity": "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==",
-            "cpu": [
-                "riscv64"
             ],
-            "dev": true,
-            "libc": [
-                "musl"
-            ],
-            "license": "MIT",
-            "optional": true,
-            "os": [
-                "linux"
-            ]
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-s390x-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.59.0.tgz",
-            "integrity": "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==",
+        "node_modules/@rolldown/binding-linux-s390x-gnu": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz",
+            "integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==",
             "cpu": [
                 "s390x"
             ],
@@ -1381,12 +872,15 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-x64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.59.0.tgz",
-            "integrity": "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==",
+        "node_modules/@rolldown/binding-linux-x64-gnu": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz",
+            "integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==",
             "cpu": [
                 "x64"
             ],
@@ -1398,12 +892,15 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-linux-x64-musl": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.59.0.tgz",
-            "integrity": "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==",
+        "node_modules/@rolldown/binding-linux-x64-musl": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz",
+            "integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==",
             "cpu": [
                 "x64"
             ],
@@ -1415,40 +912,51 @@
             "optional": true,
             "os": [
                 "linux"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-openbsd-x64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.59.0.tgz",
-            "integrity": "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==",
+        "node_modules/@rolldown/binding-openharmony-arm64": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz",
+            "integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==",
             "cpu": [
-                "x64"
+                "arm64"
             ],
             "dev": true,
             "license": "MIT",
             "optional": true,
             "os": [
-                "openbsd"
-            ]
+                "openharmony"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-openharmony-arm64": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.59.0.tgz",
-            "integrity": "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==",
+        "node_modules/@rolldown/binding-wasm32-wasi": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz",
+            "integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==",
             "cpu": [
-                "arm64"
+                "wasm32"
             ],
             "dev": true,
             "license": "MIT",
             "optional": true,
-            "os": [
-                "openharmony"
-            ]
+            "dependencies": {
+                "@emnapi/core": "1.10.0",
+                "@emnapi/runtime": "1.10.0",
+                "@napi-rs/wasm-runtime": "^1.1.4"
+            },
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-win32-arm64-msvc": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.59.0.tgz",
-            "integrity": "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==",
+        "node_modules/@rolldown/binding-win32-arm64-msvc": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz",
+            "integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==",
             "cpu": [
                 "arm64"
             ],
@@ -1457,49 +965,68 @@
             "optional": true,
             "os": [
                 "win32"
-            ]
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
         },
-        "node_modules/@rollup/rollup-win32-ia32-msvc": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.59.0.tgz",
-            "integrity": "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==",
+        "node_modules/@rolldown/binding-win32-x64-msvc": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz",
+            "integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==",
             "cpu": [
-                "ia32"
+                "x64"
             ],
             "dev": true,
             "license": "MIT",
             "optional": true,
             "os": [
                 "win32"
-            ]
-        },
-        "node_modules/@rollup/rollup-win32-x64-gnu": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.59.0.tgz",
-            "integrity": "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==",
-            "cpu": [
-                "x64"
             ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/pluginutils": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
+            "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@rollup/pluginutils": {
+            "version": "5.3.0",
+            "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
+            "integrity": "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==",
             "dev": true,
             "license": "MIT",
-            "optional": true,
-            "os": [
-                "win32"
-            ]
+            "dependencies": {
+                "@types/estree": "^1.0.0",
+                "estree-walker": "^2.0.2",
+                "picomatch": "^4.0.2"
+            },
+            "engines": {
+                "node": ">=14.0.0"
+            },
+            "peerDependencies": {
+                "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+            },
+            "peerDependenciesMeta": {
+                "rollup": {
+                    "optional": true
+                }
+            }
         },
-        "node_modules/@rollup/rollup-win32-x64-msvc": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.59.0.tgz",
-            "integrity": "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==",
-            "cpu": [
-                "x64"
-            ],
+        "node_modules/@tybys/wasm-util": {
+            "version": "0.10.1",
+            "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+            "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
             "dev": true,
             "license": "MIT",
             "optional": true,
-            "os": [
-                "win32"
-            ]
+            "dependencies": {
+                "tslib": "^2.4.0"
+            }
         },
         "node_modules/@types/estree": {
             "version": "1.0.8",
@@ -1648,6 +1175,16 @@
                 }
             }
         },
+        "node_modules/detect-libc": {
+            "version": "2.1.2",
+            "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+            "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=8"
+            }
+        },
         "node_modules/dom-serializer": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
@@ -1727,48 +1264,6 @@
                 "url": "https://github.com/fb55/entities?sponsor=1"
             }
         },
-        "node_modules/esbuild": {
-            "version": "0.27.4",
-            "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",
-            "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==",
-            "dev": true,
-            "hasInstallScript": true,
-            "license": "MIT",
-            "bin": {
-                "esbuild": "bin/esbuild"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "optionalDependencies": {
-                "@esbuild/aix-ppc64": "0.27.4",
-                "@esbuild/android-arm": "0.27.4",
-                "@esbuild/android-arm64": "0.27.4",
-                "@esbuild/android-x64": "0.27.4",
-                "@esbuild/darwin-arm64": "0.27.4",
-                "@esbuild/darwin-x64": "0.27.4",
-                "@esbuild/freebsd-arm64": "0.27.4",
-                "@esbuild/freebsd-x64": "0.27.4",
-                "@esbuild/linux-arm": "0.27.4",
-                "@esbuild/linux-arm64": "0.27.4",
-                "@esbuild/linux-ia32": "0.27.4",
-                "@esbuild/linux-loong64": "0.27.4",
-                "@esbuild/linux-mips64el": "0.27.4",
-                "@esbuild/linux-ppc64": "0.27.4",
-                "@esbuild/linux-riscv64": "0.27.4",
-                "@esbuild/linux-s390x": "0.27.4",
-                "@esbuild/linux-x64": "0.27.4",
-                "@esbuild/netbsd-arm64": "0.27.4",
-                "@esbuild/netbsd-x64": "0.27.4",
-                "@esbuild/openbsd-arm64": "0.27.4",
-                "@esbuild/openbsd-x64": "0.27.4",
-                "@esbuild/openharmony-arm64": "0.27.4",
-                "@esbuild/sunos-x64": "0.27.4",
-                "@esbuild/win32-arm64": "0.27.4",
-                "@esbuild/win32-ia32": "0.27.4",
-                "@esbuild/win32-x64": "0.27.4"
-            }
-        },
         "node_modules/escalade": {
             "version": "3.2.0",
             "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -1879,6 +1374,279 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/lightningcss": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
+            "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+            "dev": true,
+            "license": "MPL-2.0",
+            "dependencies": {
+                "detect-libc": "^2.0.3"
+            },
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            },
+            "optionalDependencies": {
+                "lightningcss-android-arm64": "1.32.0",
+                "lightningcss-darwin-arm64": "1.32.0",
+                "lightningcss-darwin-x64": "1.32.0",
+                "lightningcss-freebsd-x64": "1.32.0",
+                "lightningcss-linux-arm-gnueabihf": "1.32.0",
+                "lightningcss-linux-arm64-gnu": "1.32.0",
+                "lightningcss-linux-arm64-musl": "1.32.0",
+                "lightningcss-linux-x64-gnu": "1.32.0",
+                "lightningcss-linux-x64-musl": "1.32.0",
+                "lightningcss-win32-arm64-msvc": "1.32.0",
+                "lightningcss-win32-x64-msvc": "1.32.0"
+            }
+        },
+        "node_modules/lightningcss-android-arm64": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+            "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-arm64": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
+            "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-x64": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+            "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-freebsd-x64": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+            "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm-gnueabihf": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+            "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-gnu": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+            "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-musl": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+            "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-gnu": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+            "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-musl": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+            "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-arm64-msvc": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+            "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-x64-msvc": {
+            "version": "1.32.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+            "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
         "node_modules/lru-cache": {
             "version": "5.1.1",
             "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
@@ -1964,9 +1732,9 @@
             "license": "ISC"
         },
         "node_modules/picomatch": {
-            "version": "4.0.3",
-            "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
-            "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+            "version": "4.0.4",
+            "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+            "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
             "dev": true,
             "license": "MIT",
             "engines": {
@@ -1977,9 +1745,9 @@
             }
         },
         "node_modules/postcss": {
-            "version": "8.5.8",
-            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
-            "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
+            "version": "8.5.12",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
+            "integrity": "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==",
             "dev": true,
             "funding": [
                 {
@@ -2006,58 +1774,47 @@
             }
         },
         "node_modules/preact": {
-            "version": "10.29.0",
-            "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.0.tgz",
-            "integrity": "sha512-wSAGyk2bYR1c7t3SZ3jHcM6xy0lcBcDel6lODcs9ME6Th++Dx2KU+6D3HD8wMMKGA8Wpw7OMd3/4RGzYRpzwRg==",
+            "version": "10.29.1",
+            "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.1.tgz",
+            "integrity": "sha512-gQCLc/vWroE8lIpleXtdJhTFDogTdZG9AjMUpVkDf2iTCNwYNWA+u16dL41TqUDJO4gm2IgrcMv3uTpjd4Pwmg==",
             "license": "MIT",
             "funding": {
                 "type": "opencollective",
                 "url": "https://opencollective.com/preact"
             }
         },
-        "node_modules/rollup": {
-            "version": "4.59.0",
-            "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.59.0.tgz",
-            "integrity": "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==",
+        "node_modules/rolldown": {
+            "version": "1.0.0-rc.17",
+            "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
+            "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@types/estree": "1.0.8"
+                "@oxc-project/types": "=0.127.0",
+                "@rolldown/pluginutils": "1.0.0-rc.17"
             },
             "bin": {
-                "rollup": "dist/bin/rollup"
+                "rolldown": "bin/cli.mjs"
             },
             "engines": {
-                "node": ">=18.0.0",
-                "npm": ">=8.0.0"
+                "node": "^20.19.0 || >=22.12.0"
             },
             "optionalDependencies": {
-                "@rollup/rollup-android-arm-eabi": "4.59.0",
-                "@rollup/rollup-android-arm64": "4.59.0",
-                "@rollup/rollup-darwin-arm64": "4.59.0",
-                "@rollup/rollup-darwin-x64": "4.59.0",
-                "@rollup/rollup-freebsd-arm64": "4.59.0",
-                "@rollup/rollup-freebsd-x64": "4.59.0",
-                "@rollup/rollup-linux-arm-gnueabihf": "4.59.0",
-                "@rollup/rollup-linux-arm-musleabihf": "4.59.0",
-                "@rollup/rollup-linux-arm64-gnu": "4.59.0",
-                "@rollup/rollup-linux-arm64-musl": "4.59.0",
-                "@rollup/rollup-linux-loong64-gnu": "4.59.0",
-                "@rollup/rollup-linux-loong64-musl": "4.59.0",
-                "@rollup/rollup-linux-ppc64-gnu": "4.59.0",
-                "@rollup/rollup-linux-ppc64-musl": "4.59.0",
-                "@rollup/rollup-linux-riscv64-gnu": "4.59.0",
-                "@rollup/rollup-linux-riscv64-musl": "4.59.0",
-                "@rollup/rollup-linux-s390x-gnu": "4.59.0",
-                "@rollup/rollup-linux-x64-gnu": "4.59.0",
-                "@rollup/rollup-linux-x64-musl": "4.59.0",
-                "@rollup/rollup-openbsd-x64": "4.59.0",
-                "@rollup/rollup-openharmony-arm64": "4.59.0",
-                "@rollup/rollup-win32-arm64-msvc": "4.59.0",
-                "@rollup/rollup-win32-ia32-msvc": "4.59.0",
-                "@rollup/rollup-win32-x64-gnu": "4.59.0",
-                "@rollup/rollup-win32-x64-msvc": "4.59.0",
-                "fsevents": "~2.3.2"
+                "@rolldown/binding-android-arm64": "1.0.0-rc.17",
+                "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
+                "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
+                "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
+                "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
+                "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
+                "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
+                "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
+                "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
+                "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
+                "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
+                "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
+                "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
+                "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
+                "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
             }
         },
         "node_modules/semver": {
@@ -2111,14 +1868,14 @@
             }
         },
         "node_modules/tinyglobby": {
-            "version": "0.2.15",
-            "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
-            "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==",
+            "version": "0.2.16",
+            "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+            "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
                 "fdir": "^6.5.0",
-                "picomatch": "^4.0.3"
+                "picomatch": "^4.0.4"
             },
             "engines": {
                 "node": ">=12.0.0"
@@ -2127,10 +1884,18 @@
                 "url": "https://github.com/sponsors/SuperchupuDev"
             }
         },
+        "node_modules/tslib": {
+            "version": "2.8.1",
+            "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+            "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+            "dev": true,
+            "license": "0BSD",
+            "optional": true
+        },
         "node_modules/typescript": {
-            "version": "5.9.3",
-            "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
-            "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+            "version": "6.0.3",
+            "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+            "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
             "dev": true,
             "license": "Apache-2.0",
             "bin": {
@@ -2173,18 +1938,17 @@
             }
         },
         "node_modules/vite": {
-            "version": "7.3.1",
-            "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",
-            "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
+            "version": "8.0.10",
+            "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
+            "integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "esbuild": "^0.27.0",
-                "fdir": "^6.5.0",
-                "picomatch": "^4.0.3",
-                "postcss": "^8.5.6",
-                "rollup": "^4.43.0",
-                "tinyglobby": "^0.2.15"
+                "lightningcss": "^1.32.0",
+                "picomatch": "^4.0.4",
+                "postcss": "^8.5.10",
+                "rolldown": "1.0.0-rc.17",
+                "tinyglobby": "^0.2.16"
             },
             "bin": {
                 "vite": "bin/vite.js"
@@ -2200,9 +1964,10 @@
             },
             "peerDependencies": {
                 "@types/node": "^20.19.0 || >=22.12.0",
+                "@vitejs/devtools": "^0.1.0",
+                "esbuild": "^0.27.0 || ^0.28.0",
                 "jiti": ">=1.21.0",
                 "less": "^4.0.0",
-                "lightningcss": "^1.21.0",
                 "sass": "^1.70.0",
                 "sass-embedded": "^1.70.0",
                 "stylus": ">=0.54.8",
@@ -2215,13 +1980,16 @@
                 "@types/node": {
                     "optional": true
                 },
-                "jiti": {
+                "@vitejs/devtools": {
                     "optional": true
                 },
-                "less": {
+                "esbuild": {
+                    "optional": true
+                },
+                "jiti": {
                     "optional": true
                 },
-                "lightningcss": {
+                "less": {
                     "optional": true
                 },
                 "sass": {
@@ -2271,6 +2039,13 @@
             "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
             "dev": true,
             "license": "ISC"
+        },
+        "node_modules/zimmerframe": {
+            "version": "1.1.4",
+            "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
+            "integrity": "sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==",
+            "dev": true,
+            "license": "MIT"
         }
     }
 }
diff --git a/frontend/package.json b/frontend/package.json
index f910777..f58f4ae 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -2,6 +2,7 @@
     "name": "neato-web",
     "private": true,
     "version": "0.0.1",
+    "type": "module",
     "scripts": {
         "dev": "vite",
         "build": "biome check && tsc --noEmit && vite build && node scripts/embed_frontend.js",
@@ -11,12 +12,12 @@
         "fix:unsafe": "biome check --write --unsafe"
     },
     "dependencies": {
-        "preact": "10.29.0"
+        "preact": "10.29.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.4.7",
-        "@preact/preset-vite": "2.10.3",
-        "typescript": "5.9.3",
-        "vite": "7.3.1"
+        "@biomejs/biome": "2.4.13",
+        "@preact/preset-vite": "2.10.5",
+        "typescript": "6.0.3",
+        "vite": "8.0.10"
     }
 }
diff --git a/frontend/scripts/embed_frontend.js b/frontend/scripts/embed_frontend.js
index 5f15898..be728c0 100644
--- a/frontend/scripts/embed_frontend.js
+++ b/frontend/scripts/embed_frontend.js
@@ -6,10 +6,12 @@
 //
 // Usage: node frontend/scripts/embed_frontend.js
 
-const fs = require("node:fs");
-const path = require("node:path");
-const zlib = require("node:zlib");
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const distDir = path.join(__dirname, "..", "dist");
 const outHeader = path.join(__dirname, "..", "..", "firmware", "src", "web_assets.h");
 
diff --git a/frontend/src/svg.d.ts b/frontend/src/svg.d.ts
index c096cc5..4e008b5 100644
--- a/frontend/src/svg.d.ts
+++ b/frontend/src/svg.d.ts
@@ -3,3 +3,6 @@ declare module "*.svg?raw" {
     const content: string;
     export default content;
 }
+
+// Type declaration for side-effect CSS imports
+declare module "*.css";
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 75fee80..3cef2f6 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,12 +1,13 @@
 import preact from "@preact/preset-vite";
 import { defineConfig } from "vite";
 
-export default defineConfig(({ command }) => {
+export default defineConfig(async ({ command }) => {
     const isDev = command === "serve";
     const serverHost = "0.0.0.0";
     const serverPort = 5173;
+    const mockApiPlugin = isDev ? (await import("./mock/server.js")).mockApiPlugin : null;
     return {
-        plugins: [preact(), ...(isDev ? [require("./mock/server.js").mockApiPlugin()] : [])],
+        plugins: [preact(), ...(mockApiPlugin ? [mockApiPlugin()] : [])],
         define: isDev ? { __GITHUB_API_BASE__: JSON.stringify(`http://${serverHost}:${serverPort}`) } : {},
         server: {
             host: serverHost,
diff --git a/platformio.ini b/platformio.ini
index 2ac8289..335371f 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -38,7 +38,7 @@ lib_compat_mode = strict
 lib_ldf_mode = chain
 lib_deps =
     ESP32Async/AsyncTCP @ 3.4.10
-    ESP32Async/ESPAsyncWebServer @ 3.10.1
+    ESP32Async/ESPAsyncWebServer @ 3.10.3
 
 ; --- Build modes --------------------------------------------------------------
 

From b5309499a2d2d8903ebf0b68f131cabf9e2e678b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Mon, 27 Apr 2026 13:21:32 +0300
Subject: [PATCH 04/44] ci: pin flash tool macOS deployment target to 11.0

---
 .goreleaser.yml    | 10 ++++++++++
 docs/user-guide.md |  5 +++++
 2 files changed, 15 insertions(+)

diff --git a/.goreleaser.yml b/.goreleaser.yml
index a4230a4..b48670d 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -16,6 +16,16 @@ builds:
     env:
       - >-
         {{- if eq .Os "darwin" }}CGO_ENABLED=1{{- else }}CGO_ENABLED=0{{- end }}
+      # Pin macOS minimum to 11.0 (Big Sur), which is also Go's own floor as of
+      # Go 1.25+. Without this, the linker uses the build host's SDK as the
+      # deployment target, producing binaries that fail to load on anything
+      # older than the runner's macOS version.
+      - >-
+        {{- if eq .Os "darwin" }}MACOSX_DEPLOYMENT_TARGET=11.0{{- end }}
+      - >-
+        {{- if eq .Os "darwin" }}CGO_CFLAGS=-mmacosx-version-min=11.0{{- end }}
+      - >-
+        {{- if eq .Os "darwin" }}CGO_LDFLAGS=-mmacosx-version-min=11.0{{- end }}
     goos:
       - linux
       - darwin
diff --git a/docs/user-guide.md b/docs/user-guide.md
index bd95b3f..c221939 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -148,6 +148,11 @@ These are standalone binaries — no extraction needed. On macOS/Linux you may n
 > xattr -d com.apple.quarantine ~/Downloads/openneato-flash_Darwin_arm64
 > ```
 
+> [!IMPORTANT]
+> macOS 11 (Big Sur) is the minimum supported version. This is the floor for the Go toolchain
+> the binary is built with — older macOS versions (Catalina, Mojave, and earlier) will fail to
+> load the binary or crash on first network request.
+
 > [!WARNING]
 > The flash tool has been primarily tested on macOS. Linux and Windows builds are provided but
 > not battle-tested — if you run into issues on those platforms, please

From 7f341cc80ceceebff669bdddea6a53de2a28af9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <soner.koksal@relexsolutions.com>
Date: Sat, 25 Apr 2026 23:34:31 +0300
Subject: [PATCH 05/44] Fix OTA rejecting valid images on original ESP32 due to
 chip ID enum mismatch

---
 firmware/src/firmware_manager.cpp | 38 +++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 7 deletions(-)

diff --git a/firmware/src/firmware_manager.cpp b/firmware/src/firmware_manager.cpp
index f32c134..b0cd460 100644
--- a/firmware/src/firmware_manager.cpp
+++ b/firmware/src/firmware_manager.cpp
@@ -4,23 +4,47 @@
 
 FirmwareManager::FirmwareManager(DataLogger& logger) : LoopTask(250), dataLogger(logger) {}
 
-// ESP32 image extended header byte 12 contains the chip ID.
-// The esp_chip_info model enum uses the same values (CHIP_ESP32=1, CHIP_ESP32S2=2,
-// CHIP_ESP32C3=5, CHIP_ESP32S3=9, etc.), so we compare directly.
+// ESP32 image extended header byte 12 contains the chip ID (ESP_CHIP_ID_*),
+// which is a different enum from esp_chip_info_t::model (esp_chip_model_t).
+// They happen to match for C3 (5) and S3 (9), but not for the original ESP32
+// (header=0, model=1) or H2. Translate explicitly before comparing.
 bool FirmwareManager::validateChip(uint8_t *data, size_t len) {
     if (len < 16) {
         return true; // Not enough data yet, defer validation
     }
+    struct ChipMap {
+        uint8_t headerId; // ESP_CHIP_ID_* from image header byte 12
+        uint8_t model; // esp_chip_model_t value
+    };
+    static const ChipMap kChipMap[] = {
+            {0x00, CHIP_ESP32},
+            {0x02, CHIP_ESP32S2},
+            {0x05, CHIP_ESP32C3},
+            {0x09, CHIP_ESP32S3},
+    };
+    auto binChipId = static_cast<uint8_t>(data[12]);
+    const ChipMap *match = nullptr;
+    for (const auto& entry: kChipMap) {
+        if (entry.headerId == binChipId) {
+            match = &entry;
+            break;
+        }
+    }
+    if (!match) {
+        updateError = "Firmware chip mismatch: unknown chip ID in image";
+        LOG("FW", "Unknown binary chip ID: 0x%02X", binChipId);
+        return false;
+    }
     esp_chip_info_t info;
     esp_chip_info(&info);
-    auto binChipId = static_cast<uint8_t>(data[12]);
     auto expected = static_cast<uint8_t>(info.model);
-    if (binChipId != expected) {
+    if (match->model != expected) {
         updateError = "Firmware chip mismatch: file targets a different ESP32 variant";
-        LOG("FW", "Chip mismatch: binary has chip ID %u, expected %u", binChipId, expected);
+        LOG("FW", "Chip mismatch: binary chip ID 0x%02X (model %u), expected model %u", binChipId, match->model,
+            expected);
         return false;
     }
-    LOG("FW", "Chip ID validated: %u", binChipId);
+    LOG("FW", "Chip ID validated: 0x%02X (model %u)", binChipId, match->model);
     return true;
 }
 

From 790e4cbb139ad44f434e0ccf6fd81164e532ef61 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Sat, 25 Apr 2026 23:12:26 +0300
Subject: [PATCH 06/44] feat: rotate cleaning map in history view

---
 frontend/src/assets/icons/rotate-left.svg    |  1 +
 frontend/src/assets/icons/rotate-right.svg   |  1 +
 frontend/src/hooks/use-map-gestures.ts       | 45 +++++++++++----
 frontend/src/style.css                       | 56 ++++++++++++++++++
 frontend/src/views/history/helpers.ts        | 20 +++++--
 frontend/src/views/history/item.tsx          | 60 +++++++++++++++++---
 frontend/src/views/history/loading-wave.ts   | 27 ++++++++-
 frontend/src/views/history/motion-player.tsx | 11 ++--
 8 files changed, 191 insertions(+), 30 deletions(-)
 create mode 100644 frontend/src/assets/icons/rotate-left.svg
 create mode 100644 frontend/src/assets/icons/rotate-right.svg

diff --git a/frontend/src/assets/icons/rotate-left.svg b/frontend/src/assets/icons/rotate-left.svg
new file mode 100644
index 0000000..4b4e327
--- /dev/null
+++ b/frontend/src/assets/icons/rotate-left.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><g transform="translate(24 0) scale(-1 1)"><path d="M17.5689 10.205C17.6829 10.6032 18.0981 10.8336 18.4964 10.7196C18.8946 10.6056 19.125 10.1904 19.011 9.7922L17.5689 10.205ZM16.59 7.0486L17.1301 6.52824L17.1295 6.52764L16.59 7.0486ZM13.111 5.1336L13.2625 4.39907L13.2611 4.39878L13.111 5.1336ZM9.18996 5.5336L8.89453 4.84424L8.89379 4.84456L9.18996 5.5336ZM6.14396 8.1096L5.51365 7.70314L5.51364 7.70315L6.14396 8.1096ZM6.98796 16.9486L7.53029 16.4306L7.52996 16.4302L6.98796 16.9486ZM15.557 17.8196L15.984 18.4362L15.9841 18.4361L15.557 17.8196ZM18.7536 14.9554C18.907 14.5706 18.7195 14.1343 18.3347 13.9809C17.95 13.8275 17.5137 14.0151 17.3603 14.3998L18.7536 14.9554ZM17.5641 9.80996C17.4599 10.2109 17.7004 10.6203 18.1013 10.7245C18.5022 10.8287 18.9117 10.5881 19.0158 10.1872L17.5641 9.80996ZM19.7258 7.45525C19.83 7.05435 19.5895 6.6449 19.1886 6.54072C18.7877 6.43653 18.3783 6.67706 18.2741 7.07796L19.7258 7.45525ZM18.0902 10.7215C18.4894 10.8318 18.9025 10.5976 19.0129 10.1984C19.1232 9.79911 18.889 9.38602 18.4897 9.2757L18.0902 10.7215ZM15.8407 8.5437C15.4415 8.43337 15.0284 8.66759 14.918 9.06684C14.8077 9.46609 15.0419 9.87919 15.4412 9.98951L15.8407 8.5437ZM19.011 9.7922C18.6602 8.56683 18.0144 7.44613 17.1301 6.52824L16.0498 7.56897C16.764 8.31028 17.2856 9.21537 17.5689 10.205L19.011 9.7922ZM17.1295 6.52764C16.0842 5.44503 14.7364 4.70315 13.2625 4.39907L12.9594 5.86813C14.1375 6.11119 15.2148 6.7042 16.0504 7.56956L17.1295 6.52764ZM13.2611 4.39878C11.7942 4.09906 10.2707 4.25448 8.89453 4.84424L9.48538 6.22297C10.5807 5.75356 11.7933 5.62986 12.9608 5.86842L13.2611 4.39878ZM8.89379 4.84456C7.50796 5.44022 6.33115 6.43545 5.51365 7.70314L6.77426 8.51607C7.43013 7.49901 8.37429 6.70054 9.48612 6.22265L8.89379 4.84456ZM5.51364 7.70315C3.52854 10.7816 3.91413 14.8198 6.44595 17.467L7.52996 16.4302C5.47778 14.2845 5.16523 11.0113 6.77427 8.51605L5.51364 7.70315ZM6.44562 17.4666C8.95364 20.0923 12.9989 20.5035 15.984 18.4362L15.13 17.203C12.7516 18.8501 9.52855 18.5225 7.53029 16.4306L6.44562 17.4666ZM15.9841 18.4361C17.2293 17.5732 18.1926 16.3625 18.7536 14.9554L17.3603 14.3998C16.9084 15.5332 16.1326 16.5082 15.1298 17.2032L15.9841 18.4361ZM19.0158 10.1872L19.7258 7.45525L18.2741 7.07796L17.5641 9.80996L19.0158 10.1872ZM18.4897 9.2757L15.8407 8.5437L15.4412 9.98951L18.0902 10.7215L18.4897 9.2757Z"/></g></svg>
diff --git a/frontend/src/assets/icons/rotate-right.svg b/frontend/src/assets/icons/rotate-right.svg
new file mode 100644
index 0000000..9e318e1
--- /dev/null
+++ b/frontend/src/assets/icons/rotate-right.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M17.5689 10.205C17.6829 10.6032 18.0981 10.8336 18.4964 10.7196C18.8946 10.6056 19.125 10.1904 19.011 9.7922L17.5689 10.205ZM16.59 7.0486L17.1301 6.52824L17.1295 6.52764L16.59 7.0486ZM13.111 5.1336L13.2625 4.39907L13.2611 4.39878L13.111 5.1336ZM9.18996 5.5336L8.89453 4.84424L8.89379 4.84456L9.18996 5.5336ZM6.14396 8.1096L5.51365 7.70314L5.51364 7.70315L6.14396 8.1096ZM6.98796 16.9486L7.53029 16.4306L7.52996 16.4302L6.98796 16.9486ZM15.557 17.8196L15.984 18.4362L15.9841 18.4361L15.557 17.8196ZM18.7536 14.9554C18.907 14.5706 18.7195 14.1343 18.3347 13.9809C17.95 13.8275 17.5137 14.0151 17.3603 14.3998L18.7536 14.9554ZM17.5641 9.80996C17.4599 10.2109 17.7004 10.6203 18.1013 10.7245C18.5022 10.8287 18.9117 10.5881 19.0158 10.1872L17.5641 9.80996ZM19.7258 7.45525C19.83 7.05435 19.5895 6.6449 19.1886 6.54072C18.7877 6.43653 18.3783 6.67706 18.2741 7.07796L19.7258 7.45525ZM18.0902 10.7215C18.4894 10.8318 18.9025 10.5976 19.0129 10.1984C19.1232 9.79911 18.889 9.38602 18.4897 9.2757L18.0902 10.7215ZM15.8407 8.5437C15.4415 8.43337 15.0284 8.66759 14.918 9.06684C14.8077 9.46609 15.0419 9.87919 15.4412 9.98951L15.8407 8.5437ZM19.011 9.7922C18.6602 8.56683 18.0144 7.44613 17.1301 6.52824L16.0498 7.56897C16.764 8.31028 17.2856 9.21537 17.5689 10.205L19.011 9.7922ZM17.1295 6.52764C16.0842 5.44503 14.7364 4.70315 13.2625 4.39907L12.9594 5.86813C14.1375 6.11119 15.2148 6.7042 16.0504 7.56956L17.1295 6.52764ZM13.2611 4.39878C11.7942 4.09906 10.2707 4.25448 8.89453 4.84424L9.48538 6.22297C10.5807 5.75356 11.7933 5.62986 12.9608 5.86842L13.2611 4.39878ZM8.89379 4.84456C7.50796 5.44022 6.33115 6.43545 5.51365 7.70314L6.77426 8.51607C7.43013 7.49901 8.37429 6.70054 9.48612 6.22265L8.89379 4.84456ZM5.51364 7.70315C3.52854 10.7816 3.91413 14.8198 6.44595 17.467L7.52996 16.4302C5.47778 14.2845 5.16523 11.0113 6.77427 8.51605L5.51364 7.70315ZM6.44562 17.4666C8.95364 20.0923 12.9989 20.5035 15.984 18.4362L15.13 17.203C12.7516 18.8501 9.52855 18.5225 7.53029 16.4306L6.44562 17.4666ZM15.9841 18.4361C17.2293 17.5732 18.1926 16.3625 18.7536 14.9554L17.3603 14.3998C16.9084 15.5332 16.1326 16.5082 15.1298 17.2032L15.9841 18.4361ZM19.0158 10.1872L19.7258 7.45525L18.2741 7.07796L17.5641 9.80996L19.0158 10.1872ZM18.4897 9.2757L15.8407 8.5437L15.4412 9.98951L18.0902 10.7215L18.4897 9.2757Z"/></svg>
diff --git a/frontend/src/hooks/use-map-gestures.ts b/frontend/src/hooks/use-map-gestures.ts
index d630bc0..9b898e5 100644
--- a/frontend/src/hooks/use-map-gestures.ts
+++ b/frontend/src/hooks/use-map-gestures.ts
@@ -10,8 +10,13 @@ const DOUBLE_TAP_ZOOM = 2.5;
 
 // Manages pan, zoom, and reset gestures for a canvas element.
 // Returns the current transform and a reset function.
-export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null }): MapTransform {
+// `rotation` (degrees, 0/90/180/270) keeps gesture math aligned with the
+// rotated drawing transform applied in renderMap so dragging right always
+// pans the visible content right regardless of orientation.
+export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null }, rotation = 0): MapTransform {
     const [transform, setTransform] = useState<MapTransform>(DEFAULT_TRANSFORM);
+    const rotationRef = useRef(rotation);
+    rotationRef.current = rotation;
 
     // Mutable refs for gesture state to avoid re-attaching listeners
     const tRef = useRef<MapTransform>(DEFAULT_TRANSFORM);
@@ -67,17 +72,36 @@ export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null })
         [clampPan, commit],
     );
 
-    // Convert client coordinates to canvas-local coordinates
+    // Convert client coordinates to canvas-local coordinates, in the
+    // map's pre-rotation space. Pan/zoom transforms are applied after the
+    // rotation in renderMap, so gestures must operate in that same space.
     const toLocal = useCallback(
         (clientX: number, clientY: number): { x: number; y: number } => {
             const canvas = canvasRef.current;
             if (!canvas) return { x: clientX, y: clientY };
             const rect = canvas.getBoundingClientRect();
-            return { x: clientX - rect.left, y: clientY - rect.top };
+            const sx = clientX - rect.left;
+            const sy = clientY - rect.top;
+            const theta = (-rotationRef.current * Math.PI) / 180;
+            const cos = Math.cos(theta);
+            const sin = Math.sin(theta);
+            const w = canvas.clientWidth;
+            const h = canvas.clientHeight;
+            const dx = sx - w / 2;
+            const dy = sy - h / 2;
+            return { x: w / 2 + cos * dx - sin * dy, y: h / 2 + sin * dx + cos * dy };
         },
         [canvasRef],
     );
 
+    // Rotate a screen-space delta into the map's pre-rotation space.
+    const rotateDelta = useCallback((dx: number, dy: number): { dx: number; dy: number } => {
+        const theta = (-rotationRef.current * Math.PI) / 180;
+        const cos = Math.cos(theta);
+        const sin = Math.sin(theta);
+        return { dx: cos * dx - sin * dy, dy: sin * dx + cos * dy };
+    }, []);
+
     useEffect(() => {
         const canvas = canvasRef.current;
         if (!canvas) return;
@@ -102,9 +126,8 @@ export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null })
 
         const onPointerMove = (e: PointerEvent) => {
             if (!dragging.current) return;
-            const dx = e.clientX - dragStart.current.x;
-            const dy = e.clientY - dragStart.current.y;
-            const pan = clampPan(panStart.current.x + dx, panStart.current.y + dy, tRef.current.zoom);
+            const d = rotateDelta(e.clientX - dragStart.current.x, e.clientY - dragStart.current.y);
+            const pan = clampPan(panStart.current.x + d.dx, panStart.current.y + d.dy, tRef.current.zoom);
             commit({ ...tRef.current, panX: pan.panX, panY: pan.panY });
         };
 
@@ -191,9 +214,11 @@ export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null })
                 const pan = clampPan(nextPanX + panDx, nextPanY + panDy, newZoom);
                 commit({ panX: pan.panX, panY: pan.panY, zoom: newZoom });
             } else if (e.touches.length === 1 && dragging.current) {
-                const dx = e.touches[0].clientX - dragStart.current.x;
-                const dy = e.touches[0].clientY - dragStart.current.y;
-                const pan = clampPan(panStart.current.x + dx, panStart.current.y + dy, tRef.current.zoom);
+                const d = rotateDelta(
+                    e.touches[0].clientX - dragStart.current.x,
+                    e.touches[0].clientY - dragStart.current.y,
+                );
+                const pan = clampPan(panStart.current.x + d.dx, panStart.current.y + d.dy, tRef.current.zoom);
                 commit({ ...tRef.current, panX: pan.panX, panY: pan.panY });
             }
         };
@@ -236,7 +261,7 @@ export function useMapGestures(canvasRef: { current: HTMLCanvasElement | null })
             canvas.removeEventListener("touchmove", onTouchMove);
             canvas.removeEventListener("touchend", onTouchEnd);
         };
-    }, [canvasRef, clampPan, commit, reset, toLocal, zoomAt]);
+    }, [canvasRef, clampPan, commit, reset, toLocal, zoomAt, rotateDelta]);
 
     // Reset transform when canvas ref changes (new map loaded)
     useEffect(() => {
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 39c39f8..357a8f4 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -2245,6 +2245,7 @@ body {
 }
 
 .history-canvas-wrap {
+    position: relative;
     border: 1px solid var(--border);
     border-radius: 12px;
     overflow: hidden;
@@ -2252,6 +2253,61 @@ body {
     touch-action: manipulation;
 }
 
+.history-rotate-btn {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 36px;
+    height: 36px;
+    border-radius: 50%;
+    border: none;
+    background: rgba(0, 0, 0, 0.45);
+    color: var(--text-dim);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    opacity: 0.55;
+    transition:
+        opacity 0.15s,
+        transform 0.1s;
+    -webkit-tap-highlight-color: transparent;
+    z-index: 1;
+}
+
+.history-rotate-btn.left {
+    left: 8px;
+}
+
+.history-rotate-btn.right {
+    right: 8px;
+}
+
+.history-rotate-btn svg {
+    width: 26px;
+    height: 26px;
+}
+
+.history-rotate-btn:hover,
+.history-rotate-btn:focus-visible {
+    opacity: 1;
+    color: var(--text);
+}
+
+.history-rotate-btn:active {
+    transform: translateY(-50%) scale(0.9);
+}
+
+.light .history-rotate-btn {
+    background: rgba(255, 255, 255, 0.7);
+}
+
+@media (prefers-color-scheme: light) {
+    .system-theme .history-rotate-btn {
+        background: rgba(255, 255, 255, 0.7);
+    }
+}
+
 .history-canvas {
     display: block;
     width: 100%;
diff --git a/frontend/src/views/history/helpers.ts b/frontend/src/views/history/helpers.ts
index a4278f8..9d9aaca 100644
--- a/frontend/src/views/history/helpers.ts
+++ b/frontend/src/views/history/helpers.ts
@@ -145,12 +145,14 @@ export function interpolatePose(
 // renderer draws only the portion of the session up to that timestamp and
 // shows the interpolated robot pose as a directional sprite — used by the
 // motion player. Without `currentTime` the full static map is drawn.
+// `rotation` rotates the map content around the canvas center (degrees, 0/90/180/270).
 export function renderMap(
     canvas: HTMLCanvasElement,
     map: MapData,
     recording = false,
     tf?: MapTransform,
     currentTime?: number,
+    rotation = 0,
 ) {
     const ctx = canvas.getContext("2d");
     if (!ctx || !map.bounds) return;
@@ -166,6 +168,20 @@ export function renderMap(
     canvas.height = displayH * dpr;
     ctx.scale(dpr, dpr);
 
+    // Fill the unrotated background first so rotation doesn't expose the
+    // underlying transparent canvas at the corners.
+    ctx.fillStyle = getComputedStyle(canvas).getPropertyValue("--surface").trim() || "#1a1a1c";
+    ctx.fillRect(0, 0, displayW, displayH);
+
+    // Rotate the map content around the canvas center. Pan/zoom are applied
+    // in the rotated coordinate space so gestures stay aligned with the
+    // visible orientation (handled in useMapGestures).
+    if (rotation) {
+        ctx.translate(displayW / 2, displayH / 2);
+        ctx.rotate((rotation * Math.PI) / 180);
+        ctx.translate(-displayW / 2, -displayH / 2);
+    }
+
     // Apply zoom + pan: zoom from top-left origin, panX/panY computed by
     // useMapGestures already account for the cursor-relative zoom anchor.
     ctx.translate(panX, panY);
@@ -175,10 +191,6 @@ export function renderMap(
     const { scale, toX, toY } = proj;
     const isDark = isDarkSurface(canvas);
 
-    // Background
-    ctx.fillStyle = getComputedStyle(canvas).getPropertyValue("--surface").trim() || "#1a1a1c";
-    ctx.fillRect(0, 0, displayW, displayH);
-
     // Grid lines - draw first so coverage/path render on top
     drawMapGrid(ctx, proj, isDark);
 
diff --git a/frontend/src/views/history/item.tsx b/frontend/src/views/history/item.tsx
index 95f2c08..b6d434b 100644
--- a/frontend/src/views/history/item.tsx
+++ b/frontend/src/views/history/item.tsx
@@ -1,5 +1,7 @@
-import { useEffect, useRef, useState } from "preact/hooks";
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import boltSvg from "../../assets/icons/bolt.svg?raw";
+import rotateLeftSvg from "../../assets/icons/rotate-left.svg?raw";
+import rotateRightSvg from "../../assets/icons/rotate-right.svg?raw";
 import { Icon } from "../../components/icon";
 import { useMapGestures } from "../../hooks/use-map-gestures";
 import type { HistoryFileInfo, MapData } from "../../types";
@@ -14,9 +16,25 @@ interface HistoryItemViewProps {
     recording: boolean;
 }
 
+// Persisted map rotation, in degrees. Always normalized to one of 0/90/180/270.
+function loadRotation(): number {
+    const raw = Number(localStorage.getItem("mapRotation"));
+    if (!Number.isFinite(raw)) return 0;
+    return (((Math.round(raw / 90) * 90) % 360) + 360) % 360;
+}
+
 export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemViewProps) {
     const canvasRef = useRef<HTMLCanvasElement>(null);
-    const transform = useMapGestures(canvasRef);
+    const [rotation, setRotation] = useState<number>(loadRotation);
+    const transform = useMapGestures(canvasRef, rotation);
+
+    useEffect(() => {
+        localStorage.setItem("mapRotation", String(rotation));
+    }, [rotation]);
+
+    const rotateBy = useCallback((delta: number) => {
+        setRotation((r) => (((r + delta) % 360) + 360) % 360);
+    }, []);
 
     // Expose the live canvas element so MotionPlayer can drive the renderer
     // without duplicating gesture handling or the ref plumbing.
@@ -63,7 +81,7 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
         if (!map || map.path.length === 0) return;
         const wave = waveRef.current;
         if (!wave) return;
-        wave.startReveal(map, transform);
+        wave.startReveal(map, transform, rotation);
         revealStartedRef.current = true;
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [map]);
@@ -82,20 +100,20 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
         if (showPlayer) return;
         if (revealing) return;
         if (map && canvasRef.current) {
-            renderMap(canvasRef.current, map, recording, transform);
+            renderMap(canvasRef.current, map, recording, transform, undefined, rotation);
         }
-    }, [map, recording, transform, showPlayer, revealing]);
+    }, [map, recording, transform, showPlayer, revealing, rotation]);
 
     useEffect(() => {
         if (showPlayer) return;
         if (revealing) return;
         if (!map) return;
         const handleResize = () => {
-            if (map && canvasRef.current) renderMap(canvasRef.current, map, recording, transform);
+            if (map && canvasRef.current) renderMap(canvasRef.current, map, recording, transform, undefined, rotation);
         };
         window.addEventListener("resize", handleResize);
         return () => window.removeEventListener("resize", handleResize);
-    }, [map, recording, transform, showPlayer, revealing]);
+    }, [map, recording, transform, showPlayer, revealing, rotation]);
 
     // Prefer list metadata summary (available immediately), fall back to
     // the summary parsed from the full JSONL data (available after fetch)
@@ -141,13 +159,39 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
             <div class="history-canvas-wrap">
                 {mapEmpty && <div class="history-empty">Not enough data to display map</div>}
                 <canvas ref={canvasRef} class="history-canvas" style={mapEmpty ? { display: "none" } : undefined} />
+                {map && !mapEmpty && (
+                    <>
+                        <button
+                            type="button"
+                            class="history-rotate-btn left"
+                            onClick={() => rotateBy(-90)}
+                            aria-label="Rotate map counter-clockwise"
+                        >
+                            <Icon svg={rotateLeftSvg} />
+                        </button>
+                        <button
+                            type="button"
+                            class="history-rotate-btn right"
+                            onClick={() => rotateBy(90)}
+                            aria-label="Rotate map clockwise"
+                        >
+                            <Icon svg={rotateRightSvg} />
+                        </button>
+                    </>
+                )}
             </div>
 
             {/* Motion player mounts immediately when data arrives so its
                 controls render right away. Its canvas effects are
                 suspended via `canvasSuspended` until the wave resolves. */}
             {showPlayer && map && (
-                <MotionPlayer canvas={canvasEl} map={map} transform={transform} canvasSuspended={revealing} />
+                <MotionPlayer
+                    canvas={canvasEl}
+                    map={map}
+                    transform={transform}
+                    rotation={rotation}
+                    canvasSuspended={revealing}
+                />
             )}
 
             {/* Legend */}
diff --git a/frontend/src/views/history/loading-wave.ts b/frontend/src/views/history/loading-wave.ts
index ecbf392..37a16fa 100644
--- a/frontend/src/views/history/loading-wave.ts
+++ b/frontend/src/views/history/loading-wave.ts
@@ -133,6 +133,7 @@ export class Wave {
     private canvas: HTMLCanvasElement;
     private map: MapData | null = null;
     private transform: MapTransform | null = null;
+    private rotation = 0;
     private carrier: Pulse | null = null;
     private pulses: Pulse[] = [];
     private nextSpawnAt = 0;
@@ -163,10 +164,11 @@ export class Wave {
     // and re-anchors any in-flight loading pulses onto the carrier's
     // velocity so they expand at the same rate and expire together
     // instead of trailing as ghosts on their own slower cadence.
-    startReveal(map: MapData, transform: MapTransform): void {
+    startReveal(map: MapData, transform: MapTransform, rotation: number = 0): void {
         if (this.carrier !== null || this.finished) return;
         this.map = map;
         this.transform = transform;
+        this.rotation = rotation;
 
         const W = this.canvas.clientWidth;
         const H = this.canvas.clientHeight;
@@ -263,7 +265,7 @@ export class Wave {
             const front = pulseFront(this.carrier, t);
             const ringW = pulseRingW(this.carrier, t);
             if (front - ringW >= this.carrier.maxR) {
-                renderMap(this.canvas, this.map, false, this.transform);
+                renderMap(this.canvas, this.map, false, this.transform, undefined, this.rotation);
                 this.finish();
                 return;
             }
@@ -311,16 +313,35 @@ export class Wave {
 
         if (proj) {
             const tf = this.transform ?? { panX: 0, panY: 0, zoom: 1 };
+            ctx.save();
+            if (this.rotation) {
+                ctx.translate(displayW / 2, displayH / 2);
+                ctx.rotate((this.rotation * Math.PI) / 180);
+                ctx.translate(-displayW / 2, -displayH / 2);
+            }
             ctx.translate(tf.panX, tf.panY);
             ctx.scale(tf.zoom, tf.zoom);
             drawMapGrid(ctx, proj, isDark);
             this.drawRevealCoverage(ctx, t, proj, isDark);
             this.drawRevealPath(ctx, t, proj, isDark);
+            ctx.restore();
         }
 
         this.drawWaveCells(ctx, t, displayW, displayH, isDark);
 
-        if (proj) this.drawRevealMarkers(ctx, t, proj);
+        if (proj) {
+            ctx.save();
+            if (this.rotation) {
+                ctx.translate(displayW / 2, displayH / 2);
+                ctx.rotate((this.rotation * Math.PI) / 180);
+                ctx.translate(-displayW / 2, -displayH / 2);
+            }
+            const tf = this.transform ?? { panX: 0, panY: 0, zoom: 1 };
+            ctx.translate(tf.panX, tf.panY);
+            ctx.scale(tf.zoom, tf.zoom);
+            this.drawRevealMarkers(ctx, t, proj);
+            ctx.restore();
+        }
     }
 
     // Paint real coverage cells at native 5cm resolution behind the
diff --git a/frontend/src/views/history/motion-player.tsx b/frontend/src/views/history/motion-player.tsx
index ccc7e30..129faef 100644
--- a/frontend/src/views/history/motion-player.tsx
+++ b/frontend/src/views/history/motion-player.tsx
@@ -15,6 +15,7 @@ interface MotionPlayerProps {
     canvas: HTMLCanvasElement | null;
     map: MapData;
     transform: MapTransform;
+    rotation: number;
     // Seconds of session time played per real second. 1x replays in real time,
     // higher values speed the playback up proportionally.
     speed?: number;
@@ -24,7 +25,7 @@ interface MotionPlayerProps {
     canvasSuspended?: boolean;
 }
 
-export function MotionPlayer({ canvas, map, transform, speed = 8, canvasSuspended }: MotionPlayerProps) {
+export function MotionPlayer({ canvas, map, transform, rotation, speed = 8, canvasSuspended }: MotionPlayerProps) {
     const duration = sessionDuration(map);
     const [playing, setPlaying] = useState(false);
     // Start at the end of the timeline so a freshly opened session shows the
@@ -50,19 +51,19 @@ export function MotionPlayer({ canvas, map, transform, speed = 8, canvasSuspende
     useEffect(() => {
         if (canvasSuspended) return;
         if (!canvas || !map) return;
-        renderMap(canvas, map, false, transform, currentTime);
-    }, [canvas, map, transform, currentTime, canvasSuspended]);
+        renderMap(canvas, map, false, transform, currentTime, rotation);
+    }, [canvas, map, transform, currentTime, rotation, canvasSuspended]);
 
     // Re-render on resize — canvas backing store gets invalidated.
     useEffect(() => {
         if (canvasSuspended) return;
         if (!canvas) return;
         const onResize = () => {
-            renderMap(canvas, map, false, transform, timeRef.current);
+            renderMap(canvas, map, false, transform, timeRef.current, rotation);
         };
         window.addEventListener("resize", onResize);
         return () => window.removeEventListener("resize", onResize);
-    }, [canvas, map, transform, canvasSuspended]);
+    }, [canvas, map, transform, rotation, canvasSuspended]);
 
     // Reset to the completed map whenever the session switches. The scrubber
     // anchors at `duration` so the user sees the full session at rest.

From fe4caddf44570b3f7ba90a83ba817472445c3caa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Sun, 26 Apr 2026 23:12:52 +0300
Subject: [PATCH 07/44] feat: generate OpenAPI spec and Markdown API reference
 per release

---
 .github/workflows/release.yml       |    4 +-
 .gitignore                          |    1 +
 .goreleaser.yml                     |    4 +
 AGENTS.md                           |   10 +-
 firmware/src/web_server.cpp         |  167 +++++
 frontend/package.json               |    2 +-
 frontend/scripts/gen_api_docs.js    | 1013 +++++++++++++++++++++++++++
 frontend/src/types.ts               |  205 +++++-
 frontend/src/views/history/item.tsx |    2 +-
 9 files changed, 1382 insertions(+), 26 deletions(-)
 create mode 100644 frontend/scripts/gen_api_docs.js

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e4cd4c0..d7c4cf1 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -98,7 +98,9 @@ jobs:
         run: npm ci
         working-directory: frontend
 
-      - name: Build frontend (lint + typecheck + vite + embed)
+      - name: Build frontend (lint + typecheck + vite + embed + api docs)
+        env:
+          OPENNEATO_VERSION: ${{ needs.prepare.outputs.version }}
         run: npm run build
         working-directory: frontend
 
diff --git a/.gitignore b/.gitignore
index ddd21ec..d95fef0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@ firmware/compile_commands.json
 firmware/src/web_assets.h
 frontend/node_modules
 frontend/dist
+frontend/dist-docs
 flash/openneato-flash
 release/
 dist/
diff --git a/.goreleaser.yml b/.goreleaser.yml
index b48670d..43dc56c 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -53,12 +53,16 @@ release:
   extra_files:
     - glob: .pio/build/*-release/*-firmware.bin
     - glob: .pio/build/*-release/*-full.tar.gz
+    - glob: frontend/dist-docs/openapi.json
+    - glob: frontend/dist-docs/api-reference.md
 
 checksum:
   name_template: checksums.txt
   extra_files:
     - glob: .pio/build/*-release/*-firmware.bin
     - glob: .pio/build/*-release/*-full.tar.gz
+    - glob: frontend/dist-docs/openapi.json
+    - glob: frontend/dist-docs/api-reference.md
 
 changelog:
   sort: asc
diff --git a/AGENTS.md b/AGENTS.md
index d55b2be..0c7a218 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,8 @@ Three top-level components: `firmware/` (ESP32 C/C++), `frontend/` (Preact SPA),
 - Flash tool: Go CLI, cross-compiled via GoReleaser, uses esptool subprocess
 - Mock server: `frontend/mock/server.js` Vite plugin, `SCENARIO` constant for state switching. Reset to `"ok"` before
   committing.
-- Build pipeline: `npm run build` -> lint -> tsc -> vite -> `embed_frontend.js` generates `web_assets.h`
+- Build pipeline: `npm run build` -> lint -> tsc -> vite -> `embed_frontend.js` generates `web_assets.h` ->
+  `gen_api_docs.js` generates `frontend/dist-docs/{openapi.json, api-reference.md}` (shipped as release assets)
 
 ### Data Logging
 
@@ -43,6 +44,13 @@ needs logging, add a new typed helper following the existing pattern. Log both
 success and failure outcomes. At info level, only failures and state transitions
 are logged; at debug level, all serial commands including raw responses are included.
 
+### API Documentation
+
+When adding/changing an HTTP route, annotate it with `// @doc` directives in
+`web_server.cpp` and keep TSDoc (`/** ... */`) on every field of the matching
+response/body interface in `frontend/src/types.ts`. The generator (`npm run build`)
+fails on drift between firmware JSON keys and TS interfaces.
+
 ### Filesystem and Flash Wear
 
 SPIFFS (not LittleFS). Buffer writes in RAM, never write to flash in a loop.
diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index a710c8e..e6535d4 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -77,32 +77,78 @@ void WebServer::begin() {
 
 void WebServer::registerApiRoutes() {
     // -- Sensor query endpoints ----------------------------------------------
+    // @tag Sensors: Read-only telemetry from the robot
 
+    // @doc summary: Get robot identity (model, serial, firmware versions)
+    // @doc response: VersionData
     registerGetRoute("/api/version", neato, &NeatoSerial::getVersion, {});
+    // @doc summary: Get battery and charger status
+    // @doc response: ChargerData
     registerGetRoute("/api/charger", neato, &NeatoSerial::getCharger, {});
+    // @doc summary: Get motor telemetry (brush, vacuum, wheels, side brush, laser)
+    // @doc response: MotorData
     registerGetRoute(
             "/api/motors", neato,
             static_cast<void (NeatoSerial::*)(std::function<void(bool, const MotorData&)>)>(&NeatoSerial::getMotors),
             {});
+    // @doc summary: Get current UI and robot state machine values
+    // @doc response: StateData
     registerGetRoute("/api/state", neato, &NeatoSerial::getState, {});
+    // @doc summary: Get current error or warning state
+    // @doc response: ErrorData
     registerGetRoute("/api/error", neato, &NeatoSerial::getErr, {});
+    // @doc summary: Get latest 360-point LIDAR scan
+    // @doc response: LidarScan
     registerGetRoute("/api/lidar", neato, &NeatoSerial::getLdsScan, {});
+    // @doc summary: Get robot on-board user settings (sounds, eco, wall follow, maintenance)
+    // @doc response: UserSettingsData
     registerGetRoute("/api/user-settings", neato, &NeatoSerial::getUserSettings, {});
 
     // -- Action endpoints ----------------------------------------------------
     // All parameterized actions use query strings: resource URL identifies the
     // command, query params carry arguments (mirrors Neato serial protocol).
+    // @tag Actions: Control commands sent to the robot
 
+    // @doc summary: Start, pause, resume, stop, or dock cleaning
+    // @doc query: action enum=house,spot,pause,stop,dock required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/clean", neato, &NeatoSerial::clean, {"action"});
+    // @doc summary: Play a robot sound effect
+    // @doc query: id integer 0..20 required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/sound", neato, &NeatoSerial::playSound, {"id"});
+    // @doc summary: Enter or exit test mode (required for manual control)
+    // @doc query: enable boolean 0..1 required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/testmode", neato, &NeatoSerial::testMode, {"enable"});
+    // @doc summary: Restart or shutdown the robot
+    // @doc query: action enum=restart,shutdown required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/power", neato, &NeatoSerial::powerControl, {"action"});
+    // @doc summary: Start or stop LIDAR turret rotation
+    // @doc query: enable boolean 0..1 required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/lidar/rotate", neato, &NeatoSerial::setLdsRotation, {"enable"});
+    // @doc summary: Set a single robot on-board user setting
+    // @doc query: key string required
+    // @doc query: value string required
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/user-settings", neato, &NeatoSerial::setUserSetting, {"key", "value"});
+    // @doc summary: Clear all UI errors and warnings on the robot
+    // @doc response: Ok
+    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/clear-errors", neato, &NeatoSerial::clearErrors, {});
 
     // Serial endpoint — send arbitrary serial command, returns raw response.
     // Always available (no debug gate — useful for diagnostics without enabling verbose logging).
+    // Excluded from public API docs (diagnostics-only passthrough).
+    // @doc skip
     server.on("/api/serial", HTTP_POST, [this](AsyncWebServerRequest *request) {
         lastApiActivity = millis();
         unsigned long startMs = lastApiActivity;
@@ -141,13 +187,35 @@ void WebServer::registerApiRoutes() {
 void WebServer::registerManualRoutes() {
     // Register longer paths first — ESPAsyncWebServer matches routes by prefix,
     // so /api/manual would swallow /api/manual/move and /api/manual/motors.
+    // @tag Manual: Manual cleaning mode (joystick, motors)
+
+    // @doc path: /api/manual/status
+    // @doc method: GET
+    // @doc summary: Get manual mode state (active flag, motors, bumpers, stalls)
+    // @doc response: ManualStatus
     loggedRoute("/api/manual/status", HTTP_GET, [this](AsyncWebServerRequest *request) {
         request->send(200, "application/json", manualMgr.getStatusJson());
         return 200;
     });
+    // @doc summary: Drive the wheels for a specific distance at a given speed
+    // @doc query: left integer required (mm, negative=backward)
+    // @doc query: right integer required (mm, negative=backward)
+    // @doc query: speed integer required (mm/s)
+    // @doc response: Ok
+    // @doc errors: 503=manual mode inactive or unsafe state, 504=robot timeout
     registerPostRoute("/api/manual/move", manualMgr, &ManualCleanManager::move, {"left", "right", "speed"});
+    // @doc summary: Toggle main brush, vacuum, and side brush motors
+    // @doc query: brush boolean 0..1 required
+    // @doc query: vacuum boolean 0..1 required
+    // @doc query: sideBrush boolean 0..1 required
+    // @doc response: Ok
+    // @doc errors: 503=manual mode inactive, 504=robot timeout
     registerPostRoute("/api/manual/motors", manualMgr, &ManualCleanManager::setMotors,
                       {"brush", "vacuum", "sideBrush"});
+    // @doc summary: Enable or disable manual mode (also enters TestMode and starts LIDAR)
+    // @doc query: enable boolean 0..1 required
+    // @doc response: Ok
+    // @doc errors: 503=cannot enter manual mode, 504=robot timeout
     registerPostRoute("/api/manual", manualMgr, &ManualCleanManager::enable, {"enable"});
 
     LOG("WEB", "Manual clean routes registered");
@@ -174,11 +242,23 @@ static String logListJson(const std::vector<LogFileInfo>& files) {
 }
 
 void WebServer::registerLogRoutes() {
+    // @tag Logs: Diagnostic log files stored in flash
+
     // GET /api/logs[/filename] — list logs or download a specific file
     // A single BackwardCompatible handler matches both "/api/logs" and "/api/logs/..."
     // This route uses server.on() directly instead of loggedRoute() because
     // compressed log downloads use chunked streaming (beginChunkedResponse) which
     // must not block — loggedRoute's sync wrapper would block until completion.
+    // @doc path: /api/logs
+    // @doc method: GET
+    // @doc summary: List all log files
+    // @doc response: array of LogFileInfo
+    // @doc path: /api/logs/{filename}
+    // @doc method: GET
+    // @doc summary: Download a single log file (transparently decompressed)
+    // @doc param: filename string required
+    // @doc response: application/x-ndjson
+    // @doc errors: 404=log not found
     server.on("/api/logs", HTTP_GET, [this](AsyncWebServerRequest *request) {
         unsigned long startMs = millis();
         String filename = request->url().substring(String("/api/logs/").length());
@@ -211,6 +291,16 @@ void WebServer::registerLogRoutes() {
     });
 
     // DELETE /api/logs[/filename] — delete all logs or a specific file
+    // @doc path: /api/logs
+    // @doc method: DELETE
+    // @doc summary: Delete all log files
+    // @doc response: Ok
+    // @doc path: /api/logs/{filename}
+    // @doc method: DELETE
+    // @doc summary: Delete a single log file
+    // @doc param: filename string required
+    // @doc response: Ok
+    // @doc errors: 404=log not found
     loggedRoute("/api/logs", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
         String filename = request->url().substring(String("/api/logs/").length());
 
@@ -235,13 +325,23 @@ void WebServer::registerLogRoutes() {
 // -- System health endpoint ---------------------------------------------------
 
 void WebServer::registerSystemRoutes() {
+    // @tag System: ESP32 system health and lifecycle
+
     // GET /api/system — live system health (heap, uptime, RSSI, storage, NTP)
+    // @doc path: /api/system
+    // @doc method: GET
+    // @doc summary: Get live system metrics (heap, uptime, WiFi RSSI, storage, NTP, time)
+    // @doc response: SystemData
     loggedRoute("/api/system", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         request->send(200, "application/json", sysMgr.getSystemHealth(settingsMgr.get().tz).toJson());
         return 200;
     });
 
     // POST /api/system/restart — deferred restart
+    // @doc path: /api/system/restart
+    // @doc method: POST
+    // @doc summary: Restart the ESP32 (deferred 500ms to flush HTTP response)
+    // @doc response: Ok
     loggedRoute("/api/system/restart", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.restart();
@@ -249,6 +349,10 @@ void WebServer::registerSystemRoutes() {
     });
 
     // POST /api/system/reset — factory reset (clears NVS + WiFi, then restarts)
+    // @doc path: /api/system/reset
+    // @doc method: POST
+    // @doc summary: Factory reset (clear NVS and WiFi credentials, then restart)
+    // @doc response: Ok
     loggedRoute("/api/system/reset", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.factoryReset();
@@ -256,6 +360,10 @@ void WebServer::registerSystemRoutes() {
     });
 
     // POST /api/system/format-fs — format filesystem (erases logs + map data, then restarts)
+    // @doc path: /api/system/format-fs
+    // @doc method: POST
+    // @doc summary: Format the SPIFFS filesystem (erases logs and history, then restart)
+    // @doc response: Ok
     loggedRoute("/api/system/format-fs", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.formatFs();
@@ -268,13 +376,25 @@ void WebServer::registerSystemRoutes() {
 // -- Settings endpoint -------------------------------------------------------
 
 void WebServer::registerSettingsRoutes() {
+    // @tag Settings: User-configurable bridge settings
+
     // GET /api/settings — all user-configurable settings
+    // @doc path: /api/settings
+    // @doc method: GET
+    // @doc summary: Get all bridge settings (timezone, logging, WiFi, navigation, schedule, notifications)
+    // @doc response: SettingsData
     loggedRoute("/api/settings", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         request->send(200, "application/json", settingsMgr.get().toJson());
         return 200;
     });
 
     // PUT /api/settings — partial update (only fields present are written)
+    // @doc path: /api/settings
+    // @doc method: PUT
+    // @doc summary: Partial settings update (only fields present in body are written)
+    // @doc body: SettingsData (partial)
+    // @doc response: SettingsData
+    // @doc errors: 400=invalid settings
     loggedBodyRoute("/api/settings", HTTP_PUT,
                     [this](AsyncWebServerRequest *request, uint8_t *data, size_t len) -> int {
                         String body = String(reinterpret_cast<const char *>(data), len);
@@ -296,6 +416,12 @@ void WebServer::registerSettingsRoutes() {
                     });
 
     // POST /api/notifications/test?topic=<topic> — send a test notification
+    // @doc path: /api/notifications/test
+    // @doc method: POST
+    // @doc summary: Send a test push notification to the given ntfy.sh topic
+    // @doc query: topic string required
+    // @doc response: Ok
+    // @doc errors: 400=missing or empty topic
     loggedRoute("/api/notifications/test", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         if (!request->hasParam("topic")) {
             sendError(request, 400, "missing topic");
@@ -317,7 +443,13 @@ void WebServer::registerSettingsRoutes() {
 // -- Firmware endpoints -------------------------------------------------------
 
 void WebServer::registerFirmwareRoutes() {
+    // @tag Firmware: ESP32 firmware version and OTA update
+
     // GET /api/firmware/version — current ESP32 firmware version + chip model + robot support status
+    // @doc path: /api/firmware/version
+    // @doc method: GET
+    // @doc summary: Get current ESP32 firmware version, chip model, robot model, and support status
+    // @doc response: FirmwareVersion
     loggedRoute("/api/firmware/version", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         std::vector<Field> fields = {
                 {"version", fwMgr.getFirmwareVersion(), FIELD_STRING},
@@ -332,6 +464,13 @@ void WebServer::registerFirmwareRoutes() {
     });
 
     // POST /api/firmware/update?hash=<md5> — single-request firmware upload
+    // @doc path: /api/firmware/update
+    // @doc method: POST
+    // @doc summary: Upload a new firmware image and verify against the supplied MD5
+    // @doc query: hash string required (MD5 of firmware binary)
+    // @doc body: multipart/form-data file=<firmware.bin>
+    // @doc response: text/plain "OK"
+    // @doc errors: 400=update failed (bad hash, write error, or MD5 mismatch)
     server.on(
             "/api/firmware/update", HTTP_POST,
             // Response handler (called after upload completes)
@@ -388,7 +527,19 @@ void WebServer::registerFirmwareRoutes() {
 // -- Map data endpoints -------------------------------------------------------
 
 void WebServer::registerMapRoutes() {
+    // @tag History: Cleaning session history and map data
+
     // GET /api/history[/filename] — list sessions, collection status, or download a specific file
+    // @doc path: /api/history
+    // @doc method: GET
+    // @doc summary: List all cleaning session files with embedded session and summary metadata
+    // @doc response: array of HistoryFileInfo
+    // @doc path: /api/history/{filename}
+    // @doc method: GET
+    // @doc summary: Download a single session file (transparently decompressed)
+    // @doc param: filename string required
+    // @doc response: application/x-ndjson
+    // @doc errors: 404=session not found
     server.on("/api/history", HTTP_GET, [this](AsyncWebServerRequest *request) {
         lastApiActivity = millis();
         unsigned long startMs = lastApiActivity;
@@ -443,6 +594,16 @@ void WebServer::registerMapRoutes() {
     });
 
     // DELETE /api/history[/filename] — delete one or all sessions
+    // @doc path: /api/history
+    // @doc method: DELETE
+    // @doc summary: Delete all cleaning session files
+    // @doc response: Ok
+    // @doc path: /api/history/{filename}
+    // @doc method: DELETE
+    // @doc summary: Delete a single cleaning session file
+    // @doc param: filename string required
+    // @doc response: Ok
+    // @doc errors: 404=session not found
     loggedRoute("/api/history", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
         String filename = request->url().substring(String("/api/history/").length());
 
@@ -462,6 +623,12 @@ void WebServer::registerMapRoutes() {
     });
 
     // POST /api/history/import — upload a .jsonl session file, compress and store
+    // @doc path: /api/history/import
+    // @doc method: POST
+    // @doc summary: Upload a JSONL session file (compressed and stored on flash)
+    // @doc body: multipart/form-data file=<session.jsonl>
+    // @doc response: Ok
+    // @doc errors: 400=import failed (invalid file or write error)
     server.on(
             "/api/history/import", HTTP_POST,
             // Response handler (called after upload completes)
diff --git a/frontend/package.json b/frontend/package.json
index f58f4ae..d68c33e 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -5,7 +5,7 @@
     "type": "module",
     "scripts": {
         "dev": "vite",
-        "build": "biome check && tsc --noEmit && vite build && node scripts/embed_frontend.js",
+        "build": "biome check && tsc --noEmit && vite build && node scripts/embed_frontend.js && node scripts/gen_api_docs.js",
         "preview": "vite preview",
         "check": "biome check",
         "fix": "biome check --write",
diff --git a/frontend/scripts/gen_api_docs.js b/frontend/scripts/gen_api_docs.js
new file mode 100644
index 0000000..a5c2c42
--- /dev/null
+++ b/frontend/scripts/gen_api_docs.js
@@ -0,0 +1,1013 @@
+// Generates an OpenAPI 3.0 spec and a human-readable Markdown reference for
+// the HTTP API exposed by the firmware.
+//
+// Sources:
+//   - firmware/src/web_server.cpp  (route registrations + // @doc directives)
+//   - frontend/src/types.ts        (response/body schemas via TSDoc)
+//
+// Outputs:
+//   - frontend/dist-docs/openapi.json
+//   - frontend/dist-docs/api-reference.md
+//
+// Usage: node frontend/scripts/gen_api_docs.js
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.join(__dirname, "..", "..");
+const cppPath = path.join(repoRoot, "firmware", "src", "web_server.cpp");
+const tsPath = path.join(repoRoot, "frontend", "src", "types.ts");
+const outDir = path.join(__dirname, "..", "dist-docs");
+
+const VERSION = process.env.OPENNEATO_VERSION || readFirmwareVersion();
+
+// Maps the manager method referenced in registerGetRoute(...) to the response
+// schema name in types.ts. Static_cast<...> wrappers are stripped before
+// lookup.
+const GET_RESPONSE_TYPES = {
+    "&NeatoSerial::getVersion": "VersionData",
+    "&NeatoSerial::getCharger": "ChargerData",
+    "&NeatoSerial::getMotors": "MotorData",
+    "&NeatoSerial::getState": "StateData",
+    "&NeatoSerial::getErr": "ErrorData",
+    "&NeatoSerial::getLdsScan": "LidarScan",
+    "&NeatoSerial::getUserSettings": "UserSettingsData",
+};
+
+const TAG_DEFAULTS = {
+    Sensors: "Read-only telemetry from the robot",
+    Actions: "Control commands sent to the robot",
+    Manual: "Manual cleaning mode (joystick, motors)",
+    Logs: "Diagnostic log files stored in flash",
+    System: "ESP32 system health and lifecycle",
+    Settings: "User-configurable bridge settings",
+    Firmware: "ESP32 firmware version and OTA update",
+    History: "Cleaning session history and map data",
+};
+
+// -- C++ route extraction ----------------------------------------------------
+
+function parseCpp() {
+    const src = fs.readFileSync(cppPath, "utf8");
+    const lines = src.split("\n");
+
+    const routes = [];
+    let pendingDoc = null;
+    let currentTag = null;
+
+    const blankEntry = () => ({
+        summary: null,
+        manualPath: null,
+        manualMethod: null,
+        queries: [],
+        pathParams: [],
+        body: null,
+        responses: [],
+        errors: [],
+        tag: null,
+    });
+
+    const startDoc = () => {
+        if (!pendingDoc) {
+            pendingDoc = {
+                skip: false,
+                tag: null,
+                entries: [],
+                _currentEntry: null,
+            };
+        }
+        if (!pendingDoc._currentEntry) {
+            pendingDoc._currentEntry = blankEntry();
+            pendingDoc.entries.push(pendingDoc._currentEntry);
+        }
+    };
+
+    const handleDocLine = (raw) => {
+        const tagMatch = raw.match(/^\s*\/\/\s*@tag\s+([A-Za-z][\w-]*)\s*:\s*(.+?)\s*$/);
+        if (tagMatch) {
+            const [, name, desc] = tagMatch;
+            currentTag = name;
+            TAG_DEFAULTS[name] = desc;
+            return;
+        }
+
+        const docMatch = raw.match(/^\s*\/\/\s*@doc\s+(.*)$/);
+        if (!docMatch) return;
+        const rest = docMatch[1].trim();
+
+        if (rest === "skip") {
+            startDoc();
+            pendingDoc.skip = true;
+            return;
+        }
+
+        const colon = rest.indexOf(":");
+        if (colon < 0) {
+            warn(`Malformed @doc directive: ${raw.trim()}`);
+            return;
+        }
+        const key = rest.slice(0, colon).trim().toLowerCase();
+        const value = rest.slice(colon + 1).trim();
+
+        startDoc();
+
+        // "path:" starts a new entry within the same comment block (e.g. when a
+        // single server.on() handler covers /api/logs and /api/logs/{filename}).
+        if (key === "path" && pendingDoc._currentEntry.manualPath) {
+            pendingDoc._currentEntry = blankEntry();
+            pendingDoc.entries.push(pendingDoc._currentEntry);
+        }
+
+        const entry = pendingDoc._currentEntry;
+        switch (key) {
+            case "path":
+                entry.manualPath = value;
+                break;
+            case "method":
+                entry.manualMethod = value.toUpperCase();
+                break;
+            case "tag":
+                entry.tag = value;
+                break;
+            case "summary":
+                entry.summary = value;
+                break;
+            case "query":
+                entry.queries.push(parseParamSpec(value));
+                break;
+            case "param":
+                entry.pathParams.push(parseParamSpec(value));
+                break;
+            case "body":
+                entry.body = parseBodySpec(value);
+                break;
+            case "response":
+                entry.responses.push(parseResponseSpec(value));
+                break;
+            case "errors":
+                entry.errors.push(...parseErrorsSpec(value));
+                break;
+            default:
+                warn(`Unknown @doc key: ${key}`);
+        }
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        if (/^\s*\/\/\s*@(doc|tag)\b/.test(line)) {
+            handleDocLine(line);
+            continue;
+        }
+
+        if (!pendingDoc) continue;
+
+        if (pendingDoc.skip) {
+            // Consume the next registration call and forget the pending doc.
+            if (looksLikeRegistration(line)) pendingDoc = null;
+            continue;
+        }
+
+        const consumed = tryConsumeRegistration(lines, i, pendingDoc, currentTag, routes);
+        if (consumed > 0) {
+            i += consumed - 1;
+            pendingDoc = null;
+        }
+    }
+
+    return routes;
+}
+
+function looksLikeRegistration(line) {
+    return /\b(registerGetRoute|registerPostRoute|loggedRoute|loggedBodyRoute|server\.on)\s*\(/.test(line);
+}
+
+// Reads a possibly multi-line registration call starting at lines[i] and, if
+// found, appends one or more route records to `routes`. Returns the number of
+// source lines consumed (0 if no registration was found on this line).
+function tryConsumeRegistration(lines, i, pendingDoc, currentTag, routes) {
+    if (!looksLikeRegistration(lines[i])) return 0;
+
+    let depth = 0;
+    let buf = "";
+    let consumed = 0;
+    let started = false;
+    for (let j = i; j < lines.length && j < i + 30; j++) {
+        const line = lines[j];
+        for (let k = 0; k < line.length; k++) {
+            const c = line[k];
+            if (c === "(") {
+                depth++;
+                started = true;
+            } else if (c === ")") {
+                depth--;
+            }
+            buf += c;
+            if (started && depth === 0) {
+                consumed = j - i + 1;
+                break;
+            }
+        }
+        buf += "\n";
+        if (started && depth === 0) break;
+        consumed = j - i + 1;
+    }
+
+    const helper = buf.match(/(registerGetRoute|registerPostRoute|loggedRoute|loggedBodyRoute|server\.on)\s*\(/);
+    if (!helper) return 0;
+    const helperName = helper[1];
+
+    const pathMatch = buf.match(/"([^"]+)"/);
+    const sniffedPath = pathMatch ? pathMatch[1] : null;
+
+    const methodMatch = buf.match(/HTTP_(GET|POST|PUT|DELETE|PATCH)/);
+    const sniffedMethod = methodMatch ? methodMatch[1] : null;
+
+    let methodPtr = null;
+    if (helperName === "registerGetRoute" || helperName === "registerPostRoute") {
+        const cast = buf.match(/static_cast<[^>]+>\s*\(\s*(&[A-Za-z_][\w:]*::[A-Za-z_]\w*)\s*\)/);
+        const direct = buf.match(/,\s*(&[A-Za-z_][\w:]*::[A-Za-z_]\w*)\s*,/);
+        methodPtr = cast ? cast[1] : direct ? direct[1] : null;
+    }
+
+    const helperMethod = {
+        registerGetRoute: "GET",
+        registerPostRoute: "POST",
+    }[helperName];
+
+    const entries = pendingDoc.entries.filter(hasContent);
+    if (entries.length === 0) entries.push({ ...pendingDoc.entries[0] });
+
+    for (const entry of entries) {
+        const route = {
+            path: entry.manualPath || sniffedPath,
+            method: entry.manualMethod || helperMethod || sniffedMethod,
+            tag: entry.tag || pendingDoc.tag || currentTag,
+            summary: entry.summary,
+            queries: entry.queries,
+            pathParams: entry.pathParams,
+            body: entry.body,
+            responses: entry.responses,
+            errors: entry.errors,
+        };
+
+        if (!route.path || !route.method) {
+            warn(`Registration without path/method (helper=${helperName}, line ${i + 1})`);
+            continue;
+        }
+
+        // Defaults for template helpers when @doc didn't override.
+        if (helperName === "registerGetRoute") {
+            if (route.responses.length === 0) {
+                const typeName = methodPtr && GET_RESPONSE_TYPES[methodPtr];
+                if (typeName) route.responses = [{ kind: "ref", value: typeName }];
+            }
+            if (route.errors.length === 0) {
+                route.errors = [{ code: 504, description: "robot timeout" }];
+            }
+        } else if (helperName === "registerPostRoute") {
+            if (route.responses.length === 0) {
+                route.responses = [{ kind: "ok" }];
+            }
+            if (route.errors.length === 0) {
+                route.errors = [
+                    { code: 503, description: "robot busy" },
+                    { code: 504, description: "robot timeout" },
+                ];
+            }
+        }
+
+        routes.push(route);
+    }
+
+    return consumed;
+}
+
+function hasContent(entry) {
+    return (
+        entry.manualPath ||
+        entry.summary ||
+        entry.queries.length ||
+        entry.pathParams.length ||
+        entry.body ||
+        entry.responses.length ||
+        entry.errors.length
+    );
+}
+
+// "name type [enum=a,b,c | int range | bool 0..1] [required] [(notes)]"
+function parseParamSpec(value) {
+    const tokens = tokenize(value.trim());
+    const out = {
+        name: tokens.shift(),
+        type: "string",
+        required: false,
+        enum: null,
+        notes: null,
+    };
+    while (tokens.length) {
+        const tok = tokens.shift();
+        if (tok === "required") out.required = true;
+        else if (tok === "boolean") out.type = "boolean";
+        else if (tok === "integer") out.type = "integer";
+        else if (tok === "number") out.type = "number";
+        else if (tok === "string") out.type = "string";
+        else if (tok.startsWith("enum=")) {
+            out.type = "string";
+            out.enum = tok.slice(5).split(",");
+        } else if (/^-?\d+\.\.-?\d+$/.test(tok)) {
+            const [min, max] = tok.split("..").map(Number);
+            out.minimum = min;
+            out.maximum = max;
+        } else if (tok.startsWith("(") && tok.endsWith(")")) {
+            out.notes = tok.slice(1, -1);
+        }
+    }
+    return out;
+}
+
+// Splits on whitespace but keeps "(...)" groups intact.
+function tokenize(s) {
+    const out = [];
+    let i = 0;
+    while (i < s.length) {
+        while (i < s.length && /\s/.test(s[i])) i++;
+        if (i >= s.length) break;
+        if (s[i] === "(") {
+            const end = s.indexOf(")", i);
+            if (end < 0) {
+                out.push(s.slice(i));
+                break;
+            }
+            out.push(s.slice(i, end + 1));
+            i = end + 1;
+        } else {
+            let j = i;
+            while (j < s.length && !/\s/.test(s[j])) j++;
+            out.push(s.slice(i, j));
+            i = j;
+        }
+    }
+    return out;
+}
+
+function parseBodySpec(value) {
+    const trimmed = value.trim();
+    if (/^multipart\/form-data/i.test(trimmed)) {
+        return { kind: "multipart", description: trimmed };
+    }
+    const refMatch = trimmed.match(/^([A-Z][A-Za-z0-9_]*)\s*(?:\(partial\))?$/);
+    if (refMatch) {
+        return { kind: "ref", ref: refMatch[1], partial: /\(partial\)/.test(trimmed) };
+    }
+    return { kind: "raw", description: trimmed };
+}
+
+function parseResponseSpec(value) {
+    const trimmed = value.trim();
+    if (trimmed === "Ok") return { kind: "ok" };
+    const arrMatch = trimmed.match(/^array of ([A-Z][A-Za-z0-9_]*)$/);
+    if (arrMatch) return { kind: "array", ref: arrMatch[1] };
+    if (/^[A-Z][A-Za-z0-9_]*$/.test(trimmed)) return { kind: "ref", value: trimmed };
+    return { kind: "raw", description: trimmed };
+}
+
+function parseErrorsSpec(value) {
+    // Split on commas, but ignore commas inside parentheses so descriptions
+    // like "400=update failed (bad hash, write error)" stay intact.
+    const parts = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of value) {
+        if (ch === "(") depth++;
+        else if (ch === ")") depth--;
+        if (ch === "," && depth === 0) {
+            parts.push(cur);
+            cur = "";
+        } else {
+            cur += ch;
+        }
+    }
+    if (cur) parts.push(cur);
+
+    return parts
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((part) => {
+            const m = part.match(/^(\d{3})\s*=\s*(.+)$/);
+            if (!m) {
+                warn(`Malformed error spec: ${part}`);
+                return null;
+            }
+            return { code: Number(m[1]), description: m[2].trim() };
+        })
+        .filter(Boolean);
+}
+
+// -- TypeScript types extraction --------------------------------------------
+
+function parseTypes() {
+    const program = ts.createProgram([tsPath], {
+        target: ts.ScriptTarget.ES2020,
+        module: ts.ModuleKind.ESNext,
+        strict: true,
+        noEmit: true,
+    });
+    const checker = program.getTypeChecker();
+    const sourceFile = program.getSourceFile(tsPath);
+    if (!sourceFile) throw new Error(`Could not load ${tsPath}`);
+
+    const interfaces = {};
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isInterfaceDeclaration(node)) {
+            interfaces[node.name.text] = describeInterface(node, checker);
+        } else if (ts.isTypeAliasDeclaration(node)) {
+            interfaces[node.name.text] = describeTypeAlias(node);
+        }
+    });
+    return interfaces;
+}
+
+function describeInterface(node, checker) {
+    const description = jsDocText(node);
+    const properties = node.members
+        .filter(ts.isPropertySignature)
+        .map((member) => describeProperty(member, checker))
+        .filter(Boolean);
+    return { kind: "object", description, properties };
+}
+
+function describeTypeAlias(node) {
+    return { kind: "alias", description: jsDocText(node), text: node.type.getText() };
+}
+
+function describeProperty(member, checker) {
+    const name = member.name.getText();
+    const optional = !!member.questionToken;
+    const description = jsDocText(member);
+    const schema = typeNodeToSchema(member.type, checker);
+    return { name, optional, description, schema };
+}
+
+function typeNodeToSchema(typeNode, checker) {
+    if (!typeNode) return { type: "string" };
+
+    switch (typeNode.kind) {
+        case ts.SyntaxKind.StringKeyword:
+            return { type: "string" };
+        case ts.SyntaxKind.NumberKeyword:
+            return { type: "number" };
+        case ts.SyntaxKind.BooleanKeyword:
+            return { type: "boolean" };
+        case ts.SyntaxKind.NullKeyword:
+            return { type: "null" };
+    }
+
+    if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+        return { type: "string", const: typeNode.literal.text };
+    }
+
+    if (ts.isUnionTypeNode(typeNode)) {
+        const parts = typeNode.types.map((t) => typeNodeToSchema(t, checker));
+        const stringLiterals = parts.filter((p) => p.type === "string" && p.const !== undefined);
+        const hasNull = parts.some((p) => p.type === "null");
+        const nonNull = parts.filter((p) => p.type !== "null");
+        if (stringLiterals.length === parts.length) {
+            return { type: "string", enum: stringLiterals.map((p) => p.const) };
+        }
+        if (nonNull.length === 1) {
+            return { ...nonNull[0], nullable: hasNull };
+        }
+        return { oneOf: parts };
+    }
+
+    if (ts.isArrayTypeNode(typeNode)) {
+        return { type: "array", items: typeNodeToSchema(typeNode.elementType, checker) };
+    }
+
+    if (ts.isTupleTypeNode(typeNode)) {
+        return {
+            type: "array",
+            prefixItems: typeNode.elements.map((e) => typeNodeToSchema(ts.isNamedTupleMember(e) ? e.type : e, checker)),
+        };
+    }
+
+    if (ts.isTypeReferenceNode(typeNode)) {
+        return { ref: typeNode.typeName.getText() };
+    }
+
+    return { type: "string" };
+}
+
+function jsDocText(node) {
+    const docs = ts.getJSDocCommentsAndTags(node);
+    if (!docs.length) return null;
+    const parts = docs
+        .map((d) => {
+            if (typeof d.comment === "string") return d.comment;
+            if (Array.isArray(d.comment)) return d.comment.map((c) => (typeof c === "string" ? c : c.text)).join("");
+            return "";
+        })
+        .filter(Boolean);
+    const text = parts.join(" ").trim();
+    return text || null;
+}
+
+// -- OpenAPI builder ---------------------------------------------------------
+
+function buildOpenApi(routes, types) {
+    const tagsUsed = new Set();
+    for (const r of routes) if (r.tag) tagsUsed.add(r.tag);
+
+    const openapi = {
+        openapi: "3.0.3",
+        info: {
+            title: "OpenNeato API",
+            version: VERSION,
+            description:
+                "HTTP API exposed by the OpenNeato firmware. All endpoints are served on the local network only " +
+                "(no authentication, no TLS). The diagnostic `/api/serial` passthrough is documented separately " +
+                "in the [user guide](https://github.com/renjfk/OpenNeato/blob/main/docs/user-guide.md#serial-api).",
+        },
+        servers: [
+            {
+                url: "http://{host}",
+                description: "OpenNeato bridge on local network",
+                variables: { host: { default: "neato.local" } },
+            },
+        ],
+        tags: [...tagsUsed].map((name) => ({ name, description: TAG_DEFAULTS[name] || "" })),
+        paths: {},
+        components: {
+            schemas: buildSchemas(types, routes),
+            responses: {
+                Ok: {
+                    description: "Success acknowledgement",
+                    content: {
+                        "application/json": {
+                            schema: { $ref: "#/components/schemas/Ok" },
+                        },
+                    },
+                },
+            },
+        },
+    };
+
+    for (const route of routes) {
+        if (!openapi.paths[route.path]) openapi.paths[route.path] = {};
+        const op = {};
+        if (route.tag) op.tags = [route.tag];
+        if (route.summary) op.summary = route.summary;
+        const params = buildParameters(route);
+        if (params.length) op.parameters = params;
+        const body = buildRequestBody(route);
+        if (body) op.requestBody = body;
+        op.responses = buildResponses(route);
+        openapi.paths[route.path][route.method.toLowerCase()] = op;
+    }
+
+    return openapi;
+}
+
+function buildSchemas(types, routes) {
+    const referenced = collectReferenced(routes, types);
+    const schemas = {
+        Ok: {
+            type: "object",
+            properties: { ok: { type: "boolean" } },
+            required: ["ok"],
+        },
+        Error: {
+            type: "object",
+            properties: { error: { type: "string" } },
+            required: ["error"],
+        },
+    };
+    for (const name of referenced) {
+        const def = types[name];
+        if (!def || def.kind !== "object") continue;
+        schemas[name] = objectToSchema(def);
+    }
+    return schemas;
+}
+
+function collectReferenced(routes, types) {
+    const out = new Set();
+    const visit = (n) => {
+        if (out.has(n)) return;
+        out.add(n);
+        const def = types[n];
+        if (!def || def.kind !== "object") return;
+        for (const prop of def.properties) walkSchema(prop.schema, visit);
+    };
+    for (const route of routes) {
+        if (route.body?.kind === "ref") visit(route.body.ref);
+        for (const r of route.responses || []) {
+            if (r.kind === "ref") visit(r.value);
+            if (r.kind === "array") visit(r.ref);
+        }
+    }
+    return out;
+}
+
+function walkSchema(node, visit) {
+    if (!node) return;
+    if (node.ref) visit(node.ref);
+    if (node.items) walkSchema(node.items, visit);
+    if (node.prefixItems) for (const i of node.prefixItems) walkSchema(i, visit);
+    if (node.oneOf) for (const o of node.oneOf) walkSchema(o, visit);
+}
+
+function objectToSchema(def) {
+    const properties = {};
+    const required = [];
+    for (const prop of def.properties) {
+        properties[prop.name] = propertyToSchema(prop);
+        if (!prop.optional) required.push(prop.name);
+    }
+    const out = { type: "object", properties };
+    if (def.description) out.description = def.description;
+    if (required.length) out.required = required;
+    return out;
+}
+
+function propertyToSchema(prop) {
+    const schema = schemaShape(prop.schema);
+    if (prop.description) schema.description = prop.description;
+    return schema;
+}
+
+function schemaShape(node) {
+    if (!node) return { type: "string" };
+    if (node.ref) return { $ref: `#/components/schemas/${node.ref}` };
+    if (node.oneOf) return { oneOf: node.oneOf.map(schemaShape) };
+    if (node.type === "array") {
+        const out = { type: "array" };
+        if (node.items) out.items = schemaShape(node.items);
+        // OpenAPI 3.0 doesn't support prefixItems; collapse to items of unknown
+        // type for tuple-shaped schemas. (Only used for MapCoverageCell which
+        // isn't part of any HTTP response in practice.)
+        if (node.prefixItems) out.items = {};
+        return out;
+    }
+    const out = { type: node.type };
+    if (node.const !== undefined) out.enum = [node.const];
+    if (node.enum) out.enum = node.enum;
+    if (node.nullable) out.nullable = true;
+    return out;
+}
+
+function buildParameters(route) {
+    const params = [];
+    for (const p of route.pathParams) {
+        params.push({
+            name: p.name,
+            in: "path",
+            required: true,
+            description: p.notes || undefined,
+            schema: paramSchema(p),
+        });
+    }
+    for (const q of route.queries) {
+        params.push({
+            name: q.name,
+            in: "query",
+            required: !!q.required,
+            description: q.notes || undefined,
+            schema: paramSchema(q),
+        });
+    }
+    return params.map(stripUndefined);
+}
+
+function paramSchema(p) {
+    const out = { type: p.type };
+    if (p.enum) out.enum = p.enum;
+    if (p.minimum !== undefined) out.minimum = p.minimum;
+    if (p.maximum !== undefined) out.maximum = p.maximum;
+    return out;
+}
+
+function buildRequestBody(route) {
+    if (!route.body) return null;
+    if (route.body.kind === "ref") {
+        return {
+            required: true,
+            content: {
+                "application/json": {
+                    schema: { $ref: `#/components/schemas/${route.body.ref}` },
+                },
+            },
+        };
+    }
+    if (route.body.kind === "multipart") {
+        return {
+            required: true,
+            content: {
+                "multipart/form-data": {
+                    schema: {
+                        type: "object",
+                        properties: { file: { type: "string", format: "binary" } },
+                        required: ["file"],
+                    },
+                },
+            },
+        };
+    }
+    return null;
+}
+
+function buildResponses(route) {
+    const out = {};
+    const responses = route.responses || [];
+    if (responses.length === 0) {
+        out["200"] = { $ref: "#/components/responses/Ok" };
+    } else {
+        for (const r of responses) {
+            if (r.kind === "ok") {
+                out["200"] = { $ref: "#/components/responses/Ok" };
+            } else if (r.kind === "ref") {
+                out["200"] = jsonResponse({ $ref: `#/components/schemas/${r.value}` });
+            } else if (r.kind === "array") {
+                out["200"] = jsonResponse({
+                    type: "array",
+                    items: { $ref: `#/components/schemas/${r.ref}` },
+                });
+            } else if (r.kind === "raw") {
+                const ct = r.description.split(/\s+/)[0];
+                out["200"] = {
+                    description: r.description,
+                    content: { [ct]: { schema: { type: "string" } } },
+                };
+            }
+        }
+    }
+    for (const e of route.errors) {
+        out[String(e.code)] = {
+            description: e.description,
+            content: {
+                "application/json": { schema: { $ref: "#/components/schemas/Error" } },
+            },
+        };
+    }
+    return out;
+}
+
+function jsonResponse(schema) {
+    return {
+        description: "OK",
+        content: { "application/json": { schema } },
+    };
+}
+
+function stripUndefined(obj) {
+    if (Array.isArray(obj)) return obj.map(stripUndefined);
+    if (obj && typeof obj === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (v === undefined) continue;
+            out[k] = stripUndefined(v);
+        }
+        return out;
+    }
+    return obj;
+}
+
+// -- Markdown renderer (operates on the validated OpenAPI document) ---------
+
+function renderMarkdown(spec) {
+    const lines = [];
+    lines.push(`# ${spec.info.title}`);
+    lines.push("");
+    lines.push(`Version: \`${spec.info.version}\``);
+    lines.push("");
+    if (spec.info.description) lines.push(spec.info.description);
+    lines.push("");
+    lines.push("## Base URL");
+    lines.push("");
+    for (const s of spec.servers || []) {
+        lines.push(`- \`${s.url}\` ${s.description ? `- ${s.description}` : ""}`);
+    }
+    lines.push("");
+
+    // Group operations by tag, preserving the order tags appear in the spec.
+    const byTag = new Map();
+    for (const tag of spec.tags || []) byTag.set(tag.name, []);
+    byTag.set("Other", []);
+
+    for (const [pathKey, pathItem] of Object.entries(spec.paths)) {
+        for (const method of ["get", "post", "put", "delete", "patch"]) {
+            const op = pathItem[method];
+            if (!op) continue;
+            const tag = op.tags?.[0] || "Other";
+            if (!byTag.has(tag)) byTag.set(tag, []);
+            byTag.get(tag).push({ method: method.toUpperCase(), path: pathKey, op });
+        }
+    }
+
+    lines.push("## Endpoints");
+    lines.push("");
+
+    for (const [tagName, ops] of byTag) {
+        if (ops.length === 0) continue;
+        const tagDef = (spec.tags || []).find((t) => t.name === tagName);
+        lines.push(`### ${tagName}`);
+        if (tagDef?.description) lines.push(tagDef.description);
+        lines.push("");
+        for (const { method, path: routePath, op } of ops) {
+            renderOperation(method, routePath, op, spec, lines);
+        }
+    }
+
+    lines.push("## Schemas");
+    lines.push("");
+    const schemas = spec.components?.schemas || {};
+    const schemaNames = Object.keys(schemas).sort();
+    for (const name of schemaNames) {
+        renderSchema(name, schemas[name], lines);
+    }
+
+    return lines.join("\n");
+}
+
+function renderOperation(method, routePath, op, spec, lines) {
+    lines.push(`#### \`${method} ${routePath}\``);
+    lines.push("");
+    if (op.summary) {
+        lines.push(op.summary);
+        lines.push("");
+    }
+    if (op.parameters?.length) {
+        lines.push("**Parameters**");
+        lines.push("");
+        lines.push("| Name | In | Type | Required | Description |");
+        lines.push("|------|----|------|----------|-------------|");
+        for (const p of op.parameters) {
+            lines.push(
+                `| \`${p.name}\` | ${p.in} | ${formatParamSchema(p.schema)} | ${p.required ? "yes" : "no"} | ${escapeMd(p.description || "")} |`,
+            );
+        }
+        lines.push("");
+    }
+    if (op.requestBody) {
+        lines.push("**Request body**");
+        lines.push("");
+        const content = op.requestBody.content || {};
+        const ct = Object.keys(content)[0];
+        if (ct === "application/json") {
+            const ref = content[ct]?.schema?.$ref;
+            if (ref) {
+                const name = ref.split("/").pop();
+                lines.push(`JSON object matching [\`${name}\`](#${name.toLowerCase()}).`);
+            } else {
+                lines.push("JSON body.");
+            }
+        } else if (ct === "multipart/form-data") {
+            lines.push("`multipart/form-data` with a `file` field containing the upload payload.");
+        } else if (ct) {
+            lines.push(`Content type \`${ct}\`.`);
+        }
+        lines.push("");
+    }
+    lines.push("**Responses**");
+    lines.push("");
+    lines.push("| Status | Description | Body |");
+    lines.push("|--------|-------------|------|");
+    for (const [status, resp] of Object.entries(op.responses || {})) {
+        const resolved = resolveResponse(resp, spec);
+        const body = describeResponseBody(resolved);
+        lines.push(`| ${status} | ${escapeMd(resolved.description || "")} | ${body} |`);
+    }
+    lines.push("");
+}
+
+function resolveResponse(resp, spec) {
+    if (!resp.$ref) return resp;
+    const name = resp.$ref.split("/").pop();
+    return spec.components?.responses?.[name] || { description: "" };
+}
+
+function describeResponseBody(resp) {
+    if (!resp.content) return "";
+    const ct = Object.keys(resp.content)[0];
+    if (!ct) return "";
+    const schema = resp.content[ct]?.schema;
+    if (!schema) return `\`${ct}\``;
+    if (schema.$ref) {
+        const name = schema.$ref.split("/").pop();
+        return `[\`${name}\`](#${name.toLowerCase()})`;
+    }
+    if (schema.type === "array" && schema.items?.$ref) {
+        const name = schema.items.$ref.split("/").pop();
+        return `array of [\`${name}\`](#${name.toLowerCase()})`;
+    }
+    if (schema.type === "object" && schema.properties) {
+        const fields = Object.keys(schema.properties)
+            .map((k) => `\`${k}\``)
+            .join(", ");
+        return `object: ${fields}`;
+    }
+    return `\`${ct}\``;
+}
+
+function renderSchema(name, schema, lines) {
+    lines.push(`### \`${name}\``);
+    if (schema.description) {
+        lines.push("");
+        lines.push(schema.description);
+    }
+    lines.push("");
+    if (schema.type === "object" && schema.properties) {
+        const required = new Set(schema.required || []);
+        lines.push("| Field | Type | Required | Description |");
+        lines.push("|-------|------|----------|-------------|");
+        for (const [field, fs] of Object.entries(schema.properties)) {
+            lines.push(
+                `| \`${field}\` | ${formatPropSchema(fs)} | ${required.has(field) ? "yes" : "no"} | ${escapeMd(fs.description || "")} |`,
+            );
+        }
+    }
+    lines.push("");
+}
+
+function formatParamSchema(schema) {
+    if (!schema) return "string";
+    if (schema.enum) return `${schema.type} (\`${schema.enum.join("\\|")}\`)`;
+    let out = schema.type || "string";
+    if (schema.minimum !== undefined || schema.maximum !== undefined) {
+        out += ` (${schema.minimum ?? "-∞"}..${schema.maximum ?? "∞"})`;
+    }
+    return out;
+}
+
+function formatPropSchema(schema) {
+    if (!schema) return "any";
+    if (schema.$ref) {
+        const n = schema.$ref.split("/").pop();
+        return `[\`${n}\`](#${n.toLowerCase()})`;
+    }
+    if (schema.type === "array") {
+        if (schema.items?.$ref) {
+            const n = schema.items.$ref.split("/").pop();
+            return `array of [\`${n}\`](#${n.toLowerCase()})`;
+        }
+        if (schema.items?.type) return `array of ${schema.items.type}`;
+        return "array";
+    }
+    if (schema.enum) return `${schema.type} (\`${schema.enum.join("\\|")}\`)`;
+    if (schema.oneOf) return schema.oneOf.map(formatPropSchema).join(" \\| ");
+    let out = schema.type || "any";
+    if (schema.nullable) out += " \\| null";
+    return out;
+}
+
+function escapeMd(s) {
+    return String(s).replace(/\|/g, "\\|");
+}
+
+// -- Helpers -----------------------------------------------------------------
+
+function readFirmwareVersion() {
+    try {
+        const ini = fs.readFileSync(path.join(repoRoot, "platformio.ini"), "utf8");
+        const m = ini.match(/FIRMWARE_VERSION\s*=\s*"?([^"\n\s]+)"?/);
+        if (m) return m[1];
+    } catch {}
+    return "0.0.0-dev";
+}
+
+function warn(msg) {
+    process.stderr.write(`[gen_api_docs] WARN: ${msg}\n`);
+}
+
+// -- Main --------------------------------------------------------------------
+
+function main() {
+    fs.mkdirSync(outDir, { recursive: true });
+
+    const routes = parseCpp();
+    const types = parseTypes();
+
+    const openapi = buildOpenApi(routes, types);
+    fs.writeFileSync(path.join(outDir, "openapi.json"), `${JSON.stringify(openapi, null, 2)}\n`);
+
+    const markdown = renderMarkdown(openapi);
+    fs.writeFileSync(path.join(outDir, "api-reference.md"), markdown);
+
+    process.stdout.write(
+        `[gen_api_docs] Wrote ${routes.length} routes, ${Object.keys(types).length} types -> ${path.relative(
+            repoRoot,
+            outDir,
+        )}\n`,
+    );
+}
+
+try {
+    main();
+} catch (err) {
+    process.stderr.write(`[gen_api_docs] ${err.stack || err.message}\n`);
+    process.exit(1);
+}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index f0f1251..555f427 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -1,71 +1,170 @@
+export interface VersionData {
+    /** Robot model name (e.g. "Botvac D7") */
+    modelName: string;
+    /** Robot serial number */
+    serialNumber: string;
+    /** Robot firmware version, format "Major.Minor.Build" */
+    softwareVersion: string;
+    /** LIDAR firmware version */
+    ldsVersion: string;
+    /** LIDAR serial number */
+    ldsSerial: string;
+    /** Main board hardware version */
+    mainBoardVersion: string;
+}
+
+export interface MotorData {
+    /** Main brush rotation speed in RPM */
+    brushRPM: number;
+    /** Main brush current draw in mA */
+    brushMA: number;
+    /** Vacuum motor speed in RPM */
+    vacuumRPM: number;
+    /** Vacuum motor current draw in mA */
+    vacuumMA: number;
+    /** Left wheel rotation speed in RPM */
+    leftWheelRPM: number;
+    /** Left wheel load percentage */
+    leftWheelLoad: number;
+    /** Left wheel position in millimeters since boot */
+    leftWheelPositionMM: number;
+    /** Left wheel speed in mm/s */
+    leftWheelSpeed: number;
+    /** Right wheel rotation speed in RPM */
+    rightWheelRPM: number;
+    /** Right wheel load percentage */
+    rightWheelLoad: number;
+    /** Right wheel position in millimeters since boot */
+    rightWheelPositionMM: number;
+    /** Right wheel speed in mm/s */
+    rightWheelSpeed: number;
+    /** Side brush current draw in mA */
+    sideBrushMA: number;
+    /** Laser turret rotation speed in RPM */
+    laserRPM: number;
+}
+
 export interface StateData {
+    /** UI state machine value, e.g. "UIMGR_STATE_STANDBY" */
     uiState: string;
+    /** Robot state machine value, e.g. "ST_C_Standby" */
     robotState: string;
 }
 
 export interface ChargerData {
+    /** Battery charge percentage (0-100, -1 = unknown) */
     fuelPercent: number;
+    /** Battery temperature exceeds safe limits */
     batteryOverTemp: boolean;
+    /** Charger currently delivering current */
     chargingActive: boolean;
+    /** Charging circuit enabled (independent of active flow) */
     chargingEnabled: boolean;
+    /** Fuel gauge reading is trusted */
     confidOnFuel: boolean;
+    /** Battery has dropped into reserve range */
     onReservedFuel: boolean;
+    /** Battery considered empty (robot will not start) */
     emptyFuel: boolean;
+    /** Battery hardware fault detected */
     batteryFailure: boolean;
+    /** External power supply (dock or barrel jack) connected */
     extPwrPresent: boolean;
+    /** Battery voltage in volts */
     vBattV: number;
+    /** External supply voltage in volts */
     vExtV: number;
+    /** Cumulative mAh delivered into the battery */
     chargerMAH: number;
+    /** Cumulative mAh discharged from the battery */
     dischargeMAH: number;
 }
 
 export interface ErrorData {
+    /** True if the robot is currently reporting an error or warning */
     hasError: boolean;
+    /** "error" for codes 243+, "warning" for codes 201-242 */
     kind: "error" | "warning";
+    /** Numeric error/warning code (200 = no error) */
     errorCode: number;
+    /** Full raw response from the robot (for diagnostics) */
     errorMessage: string;
+    /** Human-readable message suitable for UI and notifications */
     displayMessage: string;
 }
 
 export interface SystemData {
+    /** Free heap memory in bytes */
     heap: number;
+    /** Total heap memory in bytes */
     heapTotal: number;
+    /** Milliseconds since boot */
     uptime: number;
+    /** WiFi signal strength in dBm (negative, closer to 0 = stronger) */
     rssi: number;
+    /** SPIFFS bytes used */
     fsUsed: number;
+    /** SPIFFS total capacity in bytes */
     fsTotal: number;
+    /** NTP has successfully synced at least once */
     ntpSynced: boolean;
+    /** Current Unix epoch time in seconds (UTC) */
     time: number;
+    /** Time source: "ntp", "robot", or "boot" */
     timeSource: string;
+    /** Configured IANA timezone (e.g. "America/New_York") */
     tz: string;
-    localTime: string; // DST-aware local time, e.g. "Sat 17:45:01"
-    isDst: boolean; // true when daylight saving time is active
+    /** DST-aware local time, e.g. "Sat 17:45:01" */
+    localTime: string;
+    /** True when daylight saving time is active */
+    isDst: boolean;
 }
 
 // Per-day schedule fields (Mon=0..Sun=6), two slots per day.
 // Slot 0 (primary):   sched{0-6}Hour, sched{0-6}Min, sched{0-6}On
 // Slot 1 (secondary): sched{0-6}Slot1Hour, sched{0-6}Slot1Min, sched{0-6}Slot1On
 export interface SettingsData {
+    /** IANA timezone identifier (e.g. "America/New_York") */
     tz: string;
-    logLevel: number; // 0=off, 1=info, 2=debug
-    syslogEnabled: boolean; // When on, logs go to UDP syslog instead of flash
-    syslogIp: string; // IPv4 address of syslog receiver
-    wifiTxPower: number; // 0.25 dBm units (e.g. 34 = 8.5 dBm)
+    /** 0=off, 1=info, 2=debug */
+    logLevel: number;
+    /** When on, logs go to UDP syslog instead of flash */
+    syslogEnabled: boolean;
+    /** IPv4 address of syslog receiver */
+    syslogIp: string;
+    /** WiFi TX power in 0.25 dBm units (e.g. 34 = 8.5 dBm) */
+    wifiTxPower: number;
+    /** GPIO pin used for UART TX to the robot */
     uartTxPin: number;
+    /** GPIO pin used for UART RX from the robot */
     uartRxPin: number;
-    maxGpioPin: number; // Read-only — max valid GPIO for this chip (21 for C3, 39 for ESP32)
+    /** Read-only - max valid GPIO for this chip (21 for C3, 39 for ESP32) */
+    maxGpioPin: number;
+    /** mDNS hostname (e.g. "openneato") */
     hostname: string;
-    navMode: string; // Navigation mode for house cleaning: "Normal", "Gentle", "Deep", "Quick"
-    stallThreshold: number; // Wheel load % for stall detection (30-80)
-    brushRpm: number; // Main brush RPM (500-1600)
-    vacuumSpeed: number; // Vacuum speed % (40-100)
-    sideBrushPower: number; // Side brush power in mW (500-1500)
-    ntfyTopic: string; // ntfy.sh topic for push notifications (empty = disabled)
-    ntfyEnabled: boolean; // Global switch — must be on for any notification to fire
-    ntfyOnDone: boolean; // Notify when cleaning completes
-    ntfyOnError: boolean; // Notify on robot error (UI_ERROR_*, code 243+)
-    ntfyOnAlert: boolean; // Notify on robot alert (UI_ALERT_*, code 201-242)
-    ntfyOnDocking: boolean; // Notify when robot returns to base
+    /** Navigation mode for house cleaning: "Normal", "Gentle", "Deep", "Quick" */
+    navMode: string;
+    /** Wheel load % for stall detection (30-80) */
+    stallThreshold: number;
+    /** Main brush RPM (500-1600) */
+    brushRpm: number;
+    /** Vacuum speed % (40-100) */
+    vacuumSpeed: number;
+    /** Side brush power in mW (500-1500) */
+    sideBrushPower: number;
+    /** ntfy.sh topic for push notifications (empty = disabled) */
+    ntfyTopic: string;
+    /** Global switch - must be on for any notification to fire */
+    ntfyEnabled: boolean;
+    /** Notify when cleaning completes */
+    ntfyOnDone: boolean;
+    /** Notify on robot error (UI_ERROR_*, code 243+) */
+    ntfyOnError: boolean;
+    /** Notify on robot alert (UI_ALERT_*, code 201-242) */
+    ntfyOnAlert: boolean;
+    /** Notify when robot returns to base */
+    ntfyOnDocking: boolean;
+    /** Master switch for the weekly cleaning schedule */
     scheduleEnabled: boolean;
     // Slot 0 (primary)
     sched0Hour: number;
@@ -114,82 +213,138 @@ export interface SettingsData {
 }
 
 export interface UserSettingsData {
+    /** Play a click sound on button presses */
     buttonClick: boolean;
+    /** Play melodies (start, finish, etc.) */
     melodies: boolean;
+    /** Play warning chimes */
     warnings: boolean;
+    /** Reduced power cleaning (longer runtime, lower suction) */
     ecoMode: boolean;
+    /** Maximum power cleaning */
     intenseClean: boolean;
+    /** Stop and warn when dirt bin is full */
     binFullDetect: boolean;
+    /** Enable wall following along walls and edges */
     wallEnable: boolean;
+    /** Robot WiFi radio enabled (separate from bridge WiFi) */
     wifi: boolean;
+    /** Dim status LEDs at night */
     stealthLed: boolean;
-    filterChange: number; // seconds
-    brushChange: number; // seconds
-    dirtBin: number; // minutes
+    /** Filter change reminder interval in seconds */
+    filterChange: number;
+    /** Brush change reminder interval in seconds */
+    brushChange: number;
+    /** Dirt bin reminder interval in minutes */
+    dirtBin: number;
 }
 
 export interface LidarPoint {
+    /** Bearing in degrees (0-359, 0 = robot front) */
     angle: number;
+    /** Distance to target in millimeters (0 if invalid) */
     dist: number;
+    /** Return signal strength (0-255) */
     intensity: number;
+    /** Per-point error code (0 = valid) */
     error: number;
 }
 
 export interface LidarScan {
+    /** LIDAR turret rotation speed in Hz */
     rotationSpeed: number;
+    /** Count of points with error == 0 */
     validPoints: number;
+    /** Always 360 entries indexed by angle */
     points: LidarPoint[];
 }
 
 export interface FirmwareVersion {
+    /** Bridge firmware semantic version */
     version: string;
+    /** ESP32 chip model (e.g. "ESP32-C3") */
     chip: string;
+    /** Robot model name (e.g. "Botvac D7", empty until identified) */
+    model: string;
+    /** mDNS hostname (e.g. "openneato") */
     hostname: string;
+    /** True if the connected robot model is officially supported */
     supported: boolean;
+    /** True while the bridge is still probing the robot model */
     identifying: boolean;
 }
 
 export interface ManualStatus {
+    /** Manual mode currently engaged */
     active: boolean;
+    /** Main brush motor enabled */
     brush: boolean;
+    /** Vacuum motor enabled */
     vacuum: boolean;
+    /** Side brush motor enabled */
     sideBrush: boolean;
+    /** Robot wheel-drop sensor reports the robot is off the ground */
     lifted: boolean;
+    /** Front-left bumper contacted */
     bumperFrontLeft: boolean;
+    /** Front-right bumper contacted */
     bumperFrontRight: boolean;
+    /** Left side bumper contacted */
     bumperSideLeft: boolean;
+    /** Right side bumper contacted */
     bumperSideRight: boolean;
+    /** Front wheel stall detected */
     stallFront: boolean;
+    /** Rear wheel stall detected */
     stallRear: boolean;
 }
 
 export interface LogFileInfo {
+    /** File name as stored on flash (may include .hs compression suffix) */
     name: string;
+    /** File size in bytes */
     size: number;
+    /** True if stored with heatshrink compression */
     compressed: boolean;
 }
 
 export interface MapSession {
+    /** Always "session" - identifies the record type */
     type: "session";
+    /** Cleaning mode: "House", "Spot", or "Manual" */
     mode: string;
+    /** Unix epoch seconds when the session started */
     time: number;
+    /** Battery percentage at session start */
     battery: number;
 }
 
 export interface MapSummary {
+    /** Always "summary" - identifies the record type */
     type: "summary";
+    /** Unix epoch seconds when the session ended */
     time: number;
+    /** Session duration in seconds */
     duration: number;
+    /** Cleaning mode: "House", "Spot", or "Manual" */
     mode: string;
+    /** Number of times the robot returned to base to recharge */
     recharges: number;
+    /** Number of pose snapshots captured */
     snapshots: number;
+    /** Total distance traveled in meters */
     distanceTraveled: number;
+    /** Maximum distance from origin in meters */
     maxDistFromOrigin: number;
+    /** Total rotation in degrees */
     totalRotation: number;
+    /** Estimated area covered in square meters */
     areaCovered: number;
+    /** Number of errors encountered during cleaning */
     errorsDuringClean: number;
-    battery?: number; // Legacy: same as batteryStart (pre-fix firmware)
+    /** Battery percentage at session start */
     batteryStart?: number;
+    /** Battery percentage at session end */
     batteryEnd?: number;
 }
 
@@ -241,10 +396,16 @@ export interface MapData {
 }
 
 export interface HistoryFileInfo {
+    /** File name as stored on flash (may include .hs compression suffix) */
     name: string;
+    /** File size in bytes */
     size: number;
+    /** True if stored with heatshrink compression */
     compressed: boolean;
+    /** True if this session is currently being recorded */
     recording: boolean;
+    /** Session metadata, or null if not yet written */
     session: MapSession | null;
+    /** Session summary, or null if cleaning has not finished */
     summary: MapSummary | null;
 }
diff --git a/frontend/src/views/history/item.tsx b/frontend/src/views/history/item.tsx
index b6d434b..de7c944 100644
--- a/frontend/src/views/history/item.tsx
+++ b/frontend/src/views/history/item.tsx
@@ -140,7 +140,7 @@ export function HistoryItemView({ file, map, mapEmpty, recording }: HistoryItemV
                     <div class="history-stat">
                         <span class="history-stat-label">Battery</span>
                         <span class="history-stat-value">
-                            {session?.battery ?? "?"}% &rarr; {summary.batteryEnd ?? summary.battery ?? "?"}%
+                            {session?.battery ?? "?"}% &rarr; {summary.batteryEnd ?? "?"}%
                         </span>
                     </div>
                     {summary.recharges > 0 && (

From 388c9726283c7c2cef77ae8ff2fbd5032c1ad1f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <soner.koksal@relexsolutions.com>
Date: Mon, 27 Apr 2026 09:29:58 +0300
Subject: [PATCH 08/44] refactor: hand-edited OpenAPI YAML as single source of
 truth

---
 .github/workflows/release.yml       |    4 +-
 .gitignore                          |    2 +-
 .goreleaser.yml                     |   13 +-
 AGENTS.md                           |   13 +-
 firmware/src/web_server.cpp         |  160 ---
 frontend/api/openapi.yaml           | 1529 +++++++++++++++++++++++++++
 frontend/biome.json                 |    1 +
 frontend/package-lock.json          |  310 +++++-
 frontend/package.json               |    9 +-
 frontend/scripts/check_api_paths.js |   70 ++
 frontend/scripts/gen_api_docs.js    | 1013 ------------------
 frontend/src/types.ts               |  393 +------
 12 files changed, 1960 insertions(+), 1557 deletions(-)
 create mode 100644 frontend/api/openapi.yaml
 create mode 100644 frontend/scripts/check_api_paths.js
 delete mode 100644 frontend/scripts/gen_api_docs.js

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d7c4cf1..7e6f668 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -98,9 +98,7 @@ jobs:
         run: npm ci
         working-directory: frontend
 
-      - name: Build frontend (lint + typecheck + vite + embed + api docs)
-        env:
-          OPENNEATO_VERSION: ${{ needs.prepare.outputs.version }}
+      - name: Build frontend (lint + codegen + path-sync + typecheck + vite + embed)
         run: npm run build
         working-directory: frontend
 
diff --git a/.gitignore b/.gitignore
index d95fef0..579f249 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,7 @@ firmware/compile_commands.json
 firmware/src/web_assets.h
 frontend/node_modules
 frontend/dist
-frontend/dist-docs
+frontend/src/types.generated.ts
 flash/openneato-flash
 release/
 dist/
diff --git a/.goreleaser.yml b/.goreleaser.yml
index 43dc56c..7ef73c6 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -5,6 +5,13 @@ project_name: openneato
 env:
   - ESPTOOL_VERSION=v5.2.0
 
+before:
+  # Stamp the release version into the OpenAPI spec shipped as a release
+  # artifact. The in-repo file carries "0.0.0-dev" as a placeholder.
+  hooks:
+    - "sed -i.bak 's/^  version:.*/  version: {{ .Version }}/' frontend/api/openapi.yaml"
+    - "rm -f frontend/api/openapi.yaml.bak"
+
 builds:
   - id: openneato-flash
     dir: flash
@@ -53,16 +60,14 @@ release:
   extra_files:
     - glob: .pio/build/*-release/*-firmware.bin
     - glob: .pio/build/*-release/*-full.tar.gz
-    - glob: frontend/dist-docs/openapi.json
-    - glob: frontend/dist-docs/api-reference.md
+    - glob: frontend/api/openapi.yaml
 
 checksum:
   name_template: checksums.txt
   extra_files:
     - glob: .pio/build/*-release/*-firmware.bin
     - glob: .pio/build/*-release/*-full.tar.gz
-    - glob: frontend/dist-docs/openapi.json
-    - glob: frontend/dist-docs/api-reference.md
+    - glob: frontend/api/openapi.yaml
 
 changelog:
   sort: asc
diff --git a/AGENTS.md b/AGENTS.md
index 0c7a218..5eee504 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,8 +25,9 @@ Three top-level components: `firmware/` (ESP32 C/C++), `frontend/` (Preact SPA),
 - Flash tool: Go CLI, cross-compiled via GoReleaser, uses esptool subprocess
 - Mock server: `frontend/mock/server.js` Vite plugin, `SCENARIO` constant for state switching. Reset to `"ok"` before
   committing.
-- Build pipeline: `npm run build` -> lint -> tsc -> vite -> `embed_frontend.js` generates `web_assets.h` ->
-  `gen_api_docs.js` generates `frontend/dist-docs/{openapi.json, api-reference.md}` (shipped as release assets)
+- Build pipeline: `npm run build` -> lint -> `openapi-typescript` regenerates `src/types.generated.ts` from
+  `frontend/api/openapi.yaml` -> `check_api_paths.js` enforces firmware↔spec route parity -> tsc -> vite ->
+  `embed_frontend.js` generates `web_assets.h`. `frontend/api/openapi.yaml` ships as a release asset.
 
 ### Data Logging
 
@@ -46,10 +47,10 @@ are logged; at debug level, all serial commands including raw responses are incl
 
 ### API Documentation
 
-When adding/changing an HTTP route, annotate it with `// @doc` directives in
-`web_server.cpp` and keep TSDoc (`/** ... */`) on every field of the matching
-response/body interface in `frontend/src/types.ts`. The generator (`npm run build`)
-fails on drift between firmware JSON keys and TS interfaces.
+`frontend/api/openapi.yaml` is the single source of truth for the HTTP API.
+When adding/changing a route, edit it alongside `web_server.cpp` (the build
+fails if paths drift). Frontend types are generated from it; frontend-only
+types live in `frontend/src/types.ts`.
 
 ### Filesystem and Flash Wear
 
diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index e6535d4..19d07c0 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -77,78 +77,33 @@ void WebServer::begin() {
 
 void WebServer::registerApiRoutes() {
     // -- Sensor query endpoints ----------------------------------------------
-    // @tag Sensors: Read-only telemetry from the robot
 
-    // @doc summary: Get robot identity (model, serial, firmware versions)
-    // @doc response: VersionData
     registerGetRoute("/api/version", neato, &NeatoSerial::getVersion, {});
-    // @doc summary: Get battery and charger status
-    // @doc response: ChargerData
     registerGetRoute("/api/charger", neato, &NeatoSerial::getCharger, {});
-    // @doc summary: Get motor telemetry (brush, vacuum, wheels, side brush, laser)
-    // @doc response: MotorData
     registerGetRoute(
             "/api/motors", neato,
             static_cast<void (NeatoSerial::*)(std::function<void(bool, const MotorData&)>)>(&NeatoSerial::getMotors),
             {});
-    // @doc summary: Get current UI and robot state machine values
-    // @doc response: StateData
     registerGetRoute("/api/state", neato, &NeatoSerial::getState, {});
-    // @doc summary: Get current error or warning state
-    // @doc response: ErrorData
     registerGetRoute("/api/error", neato, &NeatoSerial::getErr, {});
-    // @doc summary: Get latest 360-point LIDAR scan
-    // @doc response: LidarScan
     registerGetRoute("/api/lidar", neato, &NeatoSerial::getLdsScan, {});
-    // @doc summary: Get robot on-board user settings (sounds, eco, wall follow, maintenance)
-    // @doc response: UserSettingsData
     registerGetRoute("/api/user-settings", neato, &NeatoSerial::getUserSettings, {});
 
     // -- Action endpoints ----------------------------------------------------
     // All parameterized actions use query strings: resource URL identifies the
     // command, query params carry arguments (mirrors Neato serial protocol).
-    // @tag Actions: Control commands sent to the robot
 
-    // @doc summary: Start, pause, resume, stop, or dock cleaning
-    // @doc query: action enum=house,spot,pause,stop,dock required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/clean", neato, &NeatoSerial::clean, {"action"});
-    // @doc summary: Play a robot sound effect
-    // @doc query: id integer 0..20 required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/sound", neato, &NeatoSerial::playSound, {"id"});
-    // @doc summary: Enter or exit test mode (required for manual control)
-    // @doc query: enable boolean 0..1 required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/testmode", neato, &NeatoSerial::testMode, {"enable"});
-    // @doc summary: Restart or shutdown the robot
-    // @doc query: action enum=restart,shutdown required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/power", neato, &NeatoSerial::powerControl, {"action"});
-    // @doc summary: Start or stop LIDAR turret rotation
-    // @doc query: enable boolean 0..1 required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/lidar/rotate", neato, &NeatoSerial::setLdsRotation, {"enable"});
-    // @doc summary: Set a single robot on-board user setting
-    // @doc query: key string required
-    // @doc query: value string required
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/user-settings", neato, &NeatoSerial::setUserSetting, {"key", "value"});
-    // @doc summary: Clear all UI errors and warnings on the robot
-    // @doc response: Ok
-    // @doc errors: 503=robot busy, 504=robot timeout
     registerPostRoute("/api/clear-errors", neato, &NeatoSerial::clearErrors, {});
 
     // Serial endpoint — send arbitrary serial command, returns raw response.
     // Always available (no debug gate — useful for diagnostics without enabling verbose logging).
     // Excluded from public API docs (diagnostics-only passthrough).
-    // @doc skip
     server.on("/api/serial", HTTP_POST, [this](AsyncWebServerRequest *request) {
         lastApiActivity = millis();
         unsigned long startMs = lastApiActivity;
@@ -187,35 +142,14 @@ void WebServer::registerApiRoutes() {
 void WebServer::registerManualRoutes() {
     // Register longer paths first — ESPAsyncWebServer matches routes by prefix,
     // so /api/manual would swallow /api/manual/move and /api/manual/motors.
-    // @tag Manual: Manual cleaning mode (joystick, motors)
 
-    // @doc path: /api/manual/status
-    // @doc method: GET
-    // @doc summary: Get manual mode state (active flag, motors, bumpers, stalls)
-    // @doc response: ManualStatus
     loggedRoute("/api/manual/status", HTTP_GET, [this](AsyncWebServerRequest *request) {
         request->send(200, "application/json", manualMgr.getStatusJson());
         return 200;
     });
-    // @doc summary: Drive the wheels for a specific distance at a given speed
-    // @doc query: left integer required (mm, negative=backward)
-    // @doc query: right integer required (mm, negative=backward)
-    // @doc query: speed integer required (mm/s)
-    // @doc response: Ok
-    // @doc errors: 503=manual mode inactive or unsafe state, 504=robot timeout
     registerPostRoute("/api/manual/move", manualMgr, &ManualCleanManager::move, {"left", "right", "speed"});
-    // @doc summary: Toggle main brush, vacuum, and side brush motors
-    // @doc query: brush boolean 0..1 required
-    // @doc query: vacuum boolean 0..1 required
-    // @doc query: sideBrush boolean 0..1 required
-    // @doc response: Ok
-    // @doc errors: 503=manual mode inactive, 504=robot timeout
     registerPostRoute("/api/manual/motors", manualMgr, &ManualCleanManager::setMotors,
                       {"brush", "vacuum", "sideBrush"});
-    // @doc summary: Enable or disable manual mode (also enters TestMode and starts LIDAR)
-    // @doc query: enable boolean 0..1 required
-    // @doc response: Ok
-    // @doc errors: 503=cannot enter manual mode, 504=robot timeout
     registerPostRoute("/api/manual", manualMgr, &ManualCleanManager::enable, {"enable"});
 
     LOG("WEB", "Manual clean routes registered");
@@ -242,23 +176,12 @@ static String logListJson(const std::vector<LogFileInfo>& files) {
 }
 
 void WebServer::registerLogRoutes() {
-    // @tag Logs: Diagnostic log files stored in flash
 
     // GET /api/logs[/filename] — list logs or download a specific file
     // A single BackwardCompatible handler matches both "/api/logs" and "/api/logs/..."
     // This route uses server.on() directly instead of loggedRoute() because
     // compressed log downloads use chunked streaming (beginChunkedResponse) which
     // must not block — loggedRoute's sync wrapper would block until completion.
-    // @doc path: /api/logs
-    // @doc method: GET
-    // @doc summary: List all log files
-    // @doc response: array of LogFileInfo
-    // @doc path: /api/logs/{filename}
-    // @doc method: GET
-    // @doc summary: Download a single log file (transparently decompressed)
-    // @doc param: filename string required
-    // @doc response: application/x-ndjson
-    // @doc errors: 404=log not found
     server.on("/api/logs", HTTP_GET, [this](AsyncWebServerRequest *request) {
         unsigned long startMs = millis();
         String filename = request->url().substring(String("/api/logs/").length());
@@ -291,16 +214,6 @@ void WebServer::registerLogRoutes() {
     });
 
     // DELETE /api/logs[/filename] — delete all logs or a specific file
-    // @doc path: /api/logs
-    // @doc method: DELETE
-    // @doc summary: Delete all log files
-    // @doc response: Ok
-    // @doc path: /api/logs/{filename}
-    // @doc method: DELETE
-    // @doc summary: Delete a single log file
-    // @doc param: filename string required
-    // @doc response: Ok
-    // @doc errors: 404=log not found
     loggedRoute("/api/logs", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
         String filename = request->url().substring(String("/api/logs/").length());
 
@@ -325,23 +238,14 @@ void WebServer::registerLogRoutes() {
 // -- System health endpoint ---------------------------------------------------
 
 void WebServer::registerSystemRoutes() {
-    // @tag System: ESP32 system health and lifecycle
 
     // GET /api/system — live system health (heap, uptime, RSSI, storage, NTP)
-    // @doc path: /api/system
-    // @doc method: GET
-    // @doc summary: Get live system metrics (heap, uptime, WiFi RSSI, storage, NTP, time)
-    // @doc response: SystemData
     loggedRoute("/api/system", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         request->send(200, "application/json", sysMgr.getSystemHealth(settingsMgr.get().tz).toJson());
         return 200;
     });
 
     // POST /api/system/restart — deferred restart
-    // @doc path: /api/system/restart
-    // @doc method: POST
-    // @doc summary: Restart the ESP32 (deferred 500ms to flush HTTP response)
-    // @doc response: Ok
     loggedRoute("/api/system/restart", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.restart();
@@ -349,10 +253,6 @@ void WebServer::registerSystemRoutes() {
     });
 
     // POST /api/system/reset — factory reset (clears NVS + WiFi, then restarts)
-    // @doc path: /api/system/reset
-    // @doc method: POST
-    // @doc summary: Factory reset (clear NVS and WiFi credentials, then restart)
-    // @doc response: Ok
     loggedRoute("/api/system/reset", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.factoryReset();
@@ -360,10 +260,6 @@ void WebServer::registerSystemRoutes() {
     });
 
     // POST /api/system/format-fs — format filesystem (erases logs + map data, then restarts)
-    // @doc path: /api/system/format-fs
-    // @doc method: POST
-    // @doc summary: Format the SPIFFS filesystem (erases logs and history, then restart)
-    // @doc response: Ok
     loggedRoute("/api/system/format-fs", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         sendOk(request);
         sysMgr.formatFs();
@@ -376,25 +272,14 @@ void WebServer::registerSystemRoutes() {
 // -- Settings endpoint -------------------------------------------------------
 
 void WebServer::registerSettingsRoutes() {
-    // @tag Settings: User-configurable bridge settings
 
     // GET /api/settings — all user-configurable settings
-    // @doc path: /api/settings
-    // @doc method: GET
-    // @doc summary: Get all bridge settings (timezone, logging, WiFi, navigation, schedule, notifications)
-    // @doc response: SettingsData
     loggedRoute("/api/settings", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         request->send(200, "application/json", settingsMgr.get().toJson());
         return 200;
     });
 
     // PUT /api/settings — partial update (only fields present are written)
-    // @doc path: /api/settings
-    // @doc method: PUT
-    // @doc summary: Partial settings update (only fields present in body are written)
-    // @doc body: SettingsData (partial)
-    // @doc response: SettingsData
-    // @doc errors: 400=invalid settings
     loggedBodyRoute("/api/settings", HTTP_PUT,
                     [this](AsyncWebServerRequest *request, uint8_t *data, size_t len) -> int {
                         String body = String(reinterpret_cast<const char *>(data), len);
@@ -416,12 +301,6 @@ void WebServer::registerSettingsRoutes() {
                     });
 
     // POST /api/notifications/test?topic=<topic> — send a test notification
-    // @doc path: /api/notifications/test
-    // @doc method: POST
-    // @doc summary: Send a test push notification to the given ntfy.sh topic
-    // @doc query: topic string required
-    // @doc response: Ok
-    // @doc errors: 400=missing or empty topic
     loggedRoute("/api/notifications/test", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
         if (!request->hasParam("topic")) {
             sendError(request, 400, "missing topic");
@@ -443,13 +322,8 @@ void WebServer::registerSettingsRoutes() {
 // -- Firmware endpoints -------------------------------------------------------
 
 void WebServer::registerFirmwareRoutes() {
-    // @tag Firmware: ESP32 firmware version and OTA update
 
     // GET /api/firmware/version — current ESP32 firmware version + chip model + robot support status
-    // @doc path: /api/firmware/version
-    // @doc method: GET
-    // @doc summary: Get current ESP32 firmware version, chip model, robot model, and support status
-    // @doc response: FirmwareVersion
     loggedRoute("/api/firmware/version", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         std::vector<Field> fields = {
                 {"version", fwMgr.getFirmwareVersion(), FIELD_STRING},
@@ -464,13 +338,6 @@ void WebServer::registerFirmwareRoutes() {
     });
 
     // POST /api/firmware/update?hash=<md5> — single-request firmware upload
-    // @doc path: /api/firmware/update
-    // @doc method: POST
-    // @doc summary: Upload a new firmware image and verify against the supplied MD5
-    // @doc query: hash string required (MD5 of firmware binary)
-    // @doc body: multipart/form-data file=<firmware.bin>
-    // @doc response: text/plain "OK"
-    // @doc errors: 400=update failed (bad hash, write error, or MD5 mismatch)
     server.on(
             "/api/firmware/update", HTTP_POST,
             // Response handler (called after upload completes)
@@ -527,19 +394,8 @@ void WebServer::registerFirmwareRoutes() {
 // -- Map data endpoints -------------------------------------------------------
 
 void WebServer::registerMapRoutes() {
-    // @tag History: Cleaning session history and map data
 
     // GET /api/history[/filename] — list sessions, collection status, or download a specific file
-    // @doc path: /api/history
-    // @doc method: GET
-    // @doc summary: List all cleaning session files with embedded session and summary metadata
-    // @doc response: array of HistoryFileInfo
-    // @doc path: /api/history/{filename}
-    // @doc method: GET
-    // @doc summary: Download a single session file (transparently decompressed)
-    // @doc param: filename string required
-    // @doc response: application/x-ndjson
-    // @doc errors: 404=session not found
     server.on("/api/history", HTTP_GET, [this](AsyncWebServerRequest *request) {
         lastApiActivity = millis();
         unsigned long startMs = lastApiActivity;
@@ -594,16 +450,6 @@ void WebServer::registerMapRoutes() {
     });
 
     // DELETE /api/history[/filename] — delete one or all sessions
-    // @doc path: /api/history
-    // @doc method: DELETE
-    // @doc summary: Delete all cleaning session files
-    // @doc response: Ok
-    // @doc path: /api/history/{filename}
-    // @doc method: DELETE
-    // @doc summary: Delete a single cleaning session file
-    // @doc param: filename string required
-    // @doc response: Ok
-    // @doc errors: 404=session not found
     loggedRoute("/api/history", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
         String filename = request->url().substring(String("/api/history/").length());
 
@@ -623,12 +469,6 @@ void WebServer::registerMapRoutes() {
     });
 
     // POST /api/history/import — upload a .jsonl session file, compress and store
-    // @doc path: /api/history/import
-    // @doc method: POST
-    // @doc summary: Upload a JSONL session file (compressed and stored on flash)
-    // @doc body: multipart/form-data file=<session.jsonl>
-    // @doc response: Ok
-    // @doc errors: 400=import failed (invalid file or write error)
     server.on(
             "/api/history/import", HTTP_POST,
             // Response handler (called after upload completes)
diff --git a/frontend/api/openapi.yaml b/frontend/api/openapi.yaml
new file mode 100644
index 0000000..2b0c3a2
--- /dev/null
+++ b/frontend/api/openapi.yaml
@@ -0,0 +1,1529 @@
+openapi: 3.0.3
+info:
+  title: OpenNeato API
+  version: 0.0.0-dev
+  description: HTTP API exposed by the OpenNeato firmware. All endpoints are served on the local network only (no authentication, no TLS). The diagnostic `/api/serial` passthrough is documented separately in the [user guide](https://github.com/renjfk/OpenNeato/blob/main/docs/user-guide.md#serial-api).
+servers:
+  - url: http://{host}
+    description: OpenNeato bridge on local network
+    variables:
+      host:
+        default: neato.local
+tags:
+  - name: Sensors
+    description: Read-only telemetry from the robot
+  - name: Actions
+    description: Control commands sent to the robot
+  - name: Manual
+    description: Manual cleaning mode (joystick, motors)
+  - name: Logs
+    description: Diagnostic log files stored in flash
+  - name: System
+    description: ESP32 system health and lifecycle
+  - name: Settings
+    description: User-configurable bridge settings
+  - name: Firmware
+    description: ESP32 firmware version and OTA update
+  - name: History
+    description: Cleaning session history and map data
+paths:
+  /api/version:
+    get:
+      tags:
+        - Sensors
+      summary: Get robot identity (model, serial, firmware versions)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VersionData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/charger:
+    get:
+      tags:
+        - Sensors
+      summary: Get battery and charger status
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChargerData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/motors:
+    get:
+      tags:
+        - Sensors
+      summary: Get motor telemetry (brush, vacuum, wheels, side brush, laser)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MotorData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/state:
+    get:
+      tags:
+        - Sensors
+      summary: Get current UI and robot state machine values
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StateData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/error:
+    get:
+      tags:
+        - Sensors
+      summary: Get current error or warning state
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/lidar:
+    get:
+      tags:
+        - Sensors
+      summary: Get latest 360-point LIDAR scan
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LidarScan"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/user-settings:
+    get:
+      tags:
+        - Sensors
+      summary: Get robot on-board user settings (sounds, eco, wall follow, maintenance)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserSettingsData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      tags:
+        - Actions
+      summary: Set a single robot on-board user setting
+      parameters:
+        - name: key
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: value
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/clean:
+    post:
+      tags:
+        - Actions
+      summary: Start, pause, resume, stop, or dock cleaning
+      parameters:
+        - name: action
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - house
+              - spot
+              - pause
+              - stop
+              - dock
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/sound:
+    post:
+      tags:
+        - Actions
+      summary: Play a robot sound effect
+      parameters:
+        - name: id
+          in: query
+          required: true
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 20
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/testmode:
+    post:
+      tags:
+        - Actions
+      summary: Enter or exit test mode (required for manual control)
+      parameters:
+        - name: enable
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/power:
+    post:
+      tags:
+        - Actions
+      summary: Restart or shutdown the robot
+      parameters:
+        - name: action
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - restart
+              - shutdown
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/lidar/rotate:
+    post:
+      tags:
+        - Actions
+      summary: Start or stop LIDAR turret rotation
+      parameters:
+        - name: enable
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/clear-errors:
+    post:
+      tags:
+        - Actions
+      summary: Clear all UI errors and warnings on the robot
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: robot busy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/manual/status:
+    get:
+      tags:
+        - Manual
+      summary: Get manual mode state (active flag, motors, bumpers, stalls)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ManualStatus"
+  /api/manual/move:
+    post:
+      tags:
+        - Manual
+      summary: Drive the wheels for a specific distance at a given speed
+      parameters:
+        - name: left
+          in: query
+          required: true
+          description: mm, negative=backward
+          schema:
+            type: integer
+        - name: right
+          in: query
+          required: true
+          description: mm, negative=backward
+          schema:
+            type: integer
+        - name: speed
+          in: query
+          required: true
+          description: mm/s
+          schema:
+            type: integer
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: manual mode inactive or unsafe state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/manual/motors:
+    post:
+      tags:
+        - Manual
+      summary: Toggle main brush, vacuum, and side brush motors
+      parameters:
+        - name: brush
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+        - name: vacuum
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+        - name: sideBrush
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: manual mode inactive
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/manual:
+    post:
+      tags:
+        - Manual
+      summary: Enable or disable manual mode (also enters TestMode and starts LIDAR)
+      parameters:
+        - name: enable
+          in: query
+          required: true
+          schema:
+            type: boolean
+            minimum: 0
+            maximum: 1
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "503":
+          description: cannot enter manual mode
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/logs:
+    get:
+      tags:
+        - Logs
+      summary: List all log files
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/LogFileInfo"
+    delete:
+      tags:
+        - Logs
+      summary: Delete all log files
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+  /api/logs/{filename}:
+    get:
+      tags:
+        - Logs
+      summary: Download a single log file (transparently decompressed)
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: application/x-ndjson
+          content:
+            application/x-ndjson:
+              schema:
+                type: string
+        "404":
+          description: log not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    delete:
+      tags:
+        - Logs
+      summary: Delete a single log file
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "404":
+          description: log not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/system:
+    get:
+      tags:
+        - System
+      summary: Get live system metrics (heap, uptime, WiFi RSSI, storage, NTP, time)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SystemData"
+  /api/system/restart:
+    post:
+      tags:
+        - System
+      summary: Restart the ESP32 (deferred 500ms to flush HTTP response)
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+  /api/system/reset:
+    post:
+      tags:
+        - System
+      summary: Factory reset (clear NVS and WiFi credentials, then restart)
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+  /api/system/format-fs:
+    post:
+      tags:
+        - System
+      summary: Format the SPIFFS filesystem (erases logs and history, then restart)
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+  /api/settings:
+    get:
+      tags:
+        - Settings
+      summary: Get all bridge settings (timezone, logging, WiFi, navigation, schedule, notifications)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SettingsData"
+    put:
+      tags:
+        - Settings
+      summary: Partial settings update (only fields present in body are written)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SettingsData"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SettingsData"
+        "400":
+          description: invalid settings
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/notifications/test:
+    post:
+      tags:
+        - Settings
+      summary: Send a test push notification to the given ntfy.sh topic
+      parameters:
+        - name: topic
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "400":
+          description: missing or empty topic
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/firmware/version:
+    get:
+      tags:
+        - Firmware
+      summary: Get current ESP32 firmware version, chip model, robot model, and support status
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FirmwareVersion"
+  /api/firmware/update:
+    post:
+      tags:
+        - Firmware
+      summary: Upload a new firmware image and verify against the supplied MD5
+      parameters:
+        - name: hash
+          in: query
+          required: true
+          description: MD5 of firmware binary
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+              required:
+                - file
+      responses:
+        "200":
+          description: text/plain "OK"
+          content:
+            text/plain:
+              schema:
+                type: string
+        "400":
+          description: update failed (bad hash, write error, or MD5 mismatch)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/history:
+    get:
+      tags:
+        - History
+      summary: List all cleaning session files with embedded session and summary metadata
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/HistoryFileInfo"
+    delete:
+      tags:
+        - History
+      summary: Delete all cleaning session files
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+  /api/history/{filename}:
+    get:
+      tags:
+        - History
+      summary: Download a single session file (transparently decompressed)
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: application/x-ndjson
+          content:
+            application/x-ndjson:
+              schema:
+                type: string
+        "404":
+          description: session not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    delete:
+      tags:
+        - History
+      summary: Delete a single cleaning session file
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "404":
+          description: session not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/history/import:
+    post:
+      tags:
+        - History
+      summary: Upload a JSONL session file (compressed and stored on flash)
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+              required:
+                - file
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "400":
+          description: import failed (invalid file or write error)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+components:
+  schemas:
+    Ok:
+      type: object
+      properties:
+        ok:
+          type: boolean
+      required:
+        - ok
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+      required:
+        - error
+    VersionData:
+      type: object
+      properties:
+        modelName:
+          type: string
+          description: Robot model name (e.g. "Botvac D7")
+        serialNumber:
+          type: string
+          description: Robot serial number
+        softwareVersion:
+          type: string
+          description: Robot firmware version, format "Major.Minor.Build"
+        ldsVersion:
+          type: string
+          description: LIDAR firmware version
+        ldsSerial:
+          type: string
+          description: LIDAR serial number
+        mainBoardVersion:
+          type: string
+          description: Main board hardware version
+      required:
+        - modelName
+        - serialNumber
+        - softwareVersion
+        - ldsVersion
+        - ldsSerial
+        - mainBoardVersion
+    ChargerData:
+      type: object
+      properties:
+        fuelPercent:
+          type: number
+          description: Battery charge percentage (0-100, -1 = unknown)
+        batteryOverTemp:
+          type: boolean
+          description: Battery temperature exceeds safe limits
+        chargingActive:
+          type: boolean
+          description: Charger currently delivering current
+        chargingEnabled:
+          type: boolean
+          description: Charging circuit enabled (independent of active flow)
+        confidOnFuel:
+          type: boolean
+          description: Fuel gauge reading is trusted
+        onReservedFuel:
+          type: boolean
+          description: Battery has dropped into reserve range
+        emptyFuel:
+          type: boolean
+          description: Battery considered empty (robot will not start)
+        batteryFailure:
+          type: boolean
+          description: Battery hardware fault detected
+        extPwrPresent:
+          type: boolean
+          description: External power supply (dock or barrel jack) connected
+        vBattV:
+          type: number
+          description: Battery voltage in volts
+        vExtV:
+          type: number
+          description: External supply voltage in volts
+        chargerMAH:
+          type: number
+          description: Cumulative mAh delivered into the battery
+        dischargeMAH:
+          type: number
+          description: Cumulative mAh discharged from the battery
+      required:
+        - fuelPercent
+        - batteryOverTemp
+        - chargingActive
+        - chargingEnabled
+        - confidOnFuel
+        - onReservedFuel
+        - emptyFuel
+        - batteryFailure
+        - extPwrPresent
+        - vBattV
+        - vExtV
+        - chargerMAH
+        - dischargeMAH
+    MotorData:
+      type: object
+      properties:
+        brushRPM:
+          type: number
+          description: Main brush rotation speed in RPM
+        brushMA:
+          type: number
+          description: Main brush current draw in mA
+        vacuumRPM:
+          type: number
+          description: Vacuum motor speed in RPM
+        vacuumMA:
+          type: number
+          description: Vacuum motor current draw in mA
+        leftWheelRPM:
+          type: number
+          description: Left wheel rotation speed in RPM
+        leftWheelLoad:
+          type: number
+          description: Left wheel load percentage
+        leftWheelPositionMM:
+          type: number
+          description: Left wheel position in millimeters since boot
+        leftWheelSpeed:
+          type: number
+          description: Left wheel speed in mm/s
+        rightWheelRPM:
+          type: number
+          description: Right wheel rotation speed in RPM
+        rightWheelLoad:
+          type: number
+          description: Right wheel load percentage
+        rightWheelPositionMM:
+          type: number
+          description: Right wheel position in millimeters since boot
+        rightWheelSpeed:
+          type: number
+          description: Right wheel speed in mm/s
+        sideBrushMA:
+          type: number
+          description: Side brush current draw in mA
+        laserRPM:
+          type: number
+          description: Laser turret rotation speed in RPM
+      required:
+        - brushRPM
+        - brushMA
+        - vacuumRPM
+        - vacuumMA
+        - leftWheelRPM
+        - leftWheelLoad
+        - leftWheelPositionMM
+        - leftWheelSpeed
+        - rightWheelRPM
+        - rightWheelLoad
+        - rightWheelPositionMM
+        - rightWheelSpeed
+        - sideBrushMA
+        - laserRPM
+    StateData:
+      type: object
+      properties:
+        uiState:
+          type: string
+          description: UI state machine value, e.g. "UIMGR_STATE_STANDBY"
+        robotState:
+          type: string
+          description: Robot state machine value, e.g. "ST_C_Standby"
+      required:
+        - uiState
+        - robotState
+    ErrorData:
+      type: object
+      properties:
+        hasError:
+          type: boolean
+          description: True if the robot is currently reporting an error or warning
+        kind:
+          type: string
+          enum:
+            - error
+            - warning
+          description: '"error" for codes 243+, "warning" for codes 201-242'
+        errorCode:
+          type: number
+          description: Numeric error/warning code (200 = no error)
+        errorMessage:
+          type: string
+          description: Full raw response from the robot (for diagnostics)
+        displayMessage:
+          type: string
+          description: Human-readable message suitable for UI and notifications
+      required:
+        - hasError
+        - kind
+        - errorCode
+        - errorMessage
+        - displayMessage
+    LidarScan:
+      type: object
+      properties:
+        rotationSpeed:
+          type: number
+          description: LIDAR turret rotation speed in Hz
+        validPoints:
+          type: number
+          description: Count of points with error == 0
+        points:
+          type: array
+          items:
+            $ref: "#/components/schemas/LidarPoint"
+          description: Always 360 entries indexed by angle
+      required:
+        - rotationSpeed
+        - validPoints
+        - points
+    LidarPoint:
+      type: object
+      properties:
+        angle:
+          type: number
+          description: Bearing in degrees (0-359, 0 = robot front)
+        dist:
+          type: number
+          description: Distance to target in millimeters (0 if invalid)
+        intensity:
+          type: number
+          description: Return signal strength (0-255)
+        error:
+          type: number
+          description: Per-point error code (0 = valid)
+      required:
+        - angle
+        - dist
+        - intensity
+        - error
+    UserSettingsData:
+      type: object
+      properties:
+        buttonClick:
+          type: boolean
+          description: Play a click sound on button presses
+        melodies:
+          type: boolean
+          description: Play melodies (start, finish, etc.)
+        warnings:
+          type: boolean
+          description: Play warning chimes
+        ecoMode:
+          type: boolean
+          description: Reduced power cleaning (longer runtime, lower suction)
+        intenseClean:
+          type: boolean
+          description: Maximum power cleaning
+        binFullDetect:
+          type: boolean
+          description: Stop and warn when dirt bin is full
+        wallEnable:
+          type: boolean
+          description: Enable wall following along walls and edges
+        wifi:
+          type: boolean
+          description: Robot WiFi radio enabled (separate from bridge WiFi)
+        stealthLed:
+          type: boolean
+          description: Dim status LEDs at night
+        filterChange:
+          type: number
+          description: Filter change reminder interval in seconds
+        brushChange:
+          type: number
+          description: Brush change reminder interval in seconds
+        dirtBin:
+          type: number
+          description: Dirt bin reminder interval in minutes
+      required:
+        - buttonClick
+        - melodies
+        - warnings
+        - ecoMode
+        - intenseClean
+        - binFullDetect
+        - wallEnable
+        - wifi
+        - stealthLed
+        - filterChange
+        - brushChange
+        - dirtBin
+    ManualStatus:
+      type: object
+      properties:
+        active:
+          type: boolean
+          description: Manual mode currently engaged
+        brush:
+          type: boolean
+          description: Main brush motor enabled
+        vacuum:
+          type: boolean
+          description: Vacuum motor enabled
+        sideBrush:
+          type: boolean
+          description: Side brush motor enabled
+        lifted:
+          type: boolean
+          description: Robot wheel-drop sensor reports the robot is off the ground
+        bumperFrontLeft:
+          type: boolean
+          description: Front-left bumper contacted
+        bumperFrontRight:
+          type: boolean
+          description: Front-right bumper contacted
+        bumperSideLeft:
+          type: boolean
+          description: Left side bumper contacted
+        bumperSideRight:
+          type: boolean
+          description: Right side bumper contacted
+        stallFront:
+          type: boolean
+          description: Front wheel stall detected
+        stallRear:
+          type: boolean
+          description: Rear wheel stall detected
+      required:
+        - active
+        - brush
+        - vacuum
+        - sideBrush
+        - lifted
+        - bumperFrontLeft
+        - bumperFrontRight
+        - bumperSideLeft
+        - bumperSideRight
+        - stallFront
+        - stallRear
+    LogFileInfo:
+      type: object
+      properties:
+        name:
+          type: string
+          description: File name as stored on flash (may include .hs compression suffix)
+        size:
+          type: number
+          description: File size in bytes
+        compressed:
+          type: boolean
+          description: True if stored with heatshrink compression
+      required:
+        - name
+        - size
+        - compressed
+    SystemData:
+      type: object
+      properties:
+        heap:
+          type: number
+          description: Free heap memory in bytes
+        heapTotal:
+          type: number
+          description: Total heap memory in bytes
+        uptime:
+          type: number
+          description: Milliseconds since boot
+        rssi:
+          type: number
+          description: WiFi signal strength in dBm (negative, closer to 0 = stronger)
+        fsUsed:
+          type: number
+          description: SPIFFS bytes used
+        fsTotal:
+          type: number
+          description: SPIFFS total capacity in bytes
+        ntpSynced:
+          type: boolean
+          description: NTP has successfully synced at least once
+        time:
+          type: number
+          description: Current Unix epoch time in seconds (UTC)
+        timeSource:
+          type: string
+          description: 'Time source: "ntp", "robot", or "boot"'
+        tz:
+          type: string
+          description: Configured IANA timezone (e.g. "America/New_York")
+        localTime:
+          type: string
+          description: DST-aware local time, e.g. "Sat 17:45:01"
+        isDst:
+          type: boolean
+          description: True when daylight saving time is active
+      required:
+        - heap
+        - heapTotal
+        - uptime
+        - rssi
+        - fsUsed
+        - fsTotal
+        - ntpSynced
+        - time
+        - timeSource
+        - tz
+        - localTime
+        - isDst
+    SettingsData:
+      type: object
+      properties:
+        tz:
+          type: string
+          description: IANA timezone identifier (e.g. "America/New_York")
+        logLevel:
+          type: number
+          description: 0=off, 1=info, 2=debug
+        syslogEnabled:
+          type: boolean
+          description: When on, logs go to UDP syslog instead of flash
+        syslogIp:
+          type: string
+          description: IPv4 address of syslog receiver
+        wifiTxPower:
+          type: number
+          description: WiFi TX power in 0.25 dBm units (e.g. 34 = 8.5 dBm)
+        uartTxPin:
+          type: number
+          description: GPIO pin used for UART TX to the robot
+        uartRxPin:
+          type: number
+          description: GPIO pin used for UART RX from the robot
+        maxGpioPin:
+          type: number
+          description: Read-only - max valid GPIO for this chip (21 for C3, 39 for ESP32)
+        hostname:
+          type: string
+          description: mDNS hostname (e.g. "openneato")
+        navMode:
+          type: string
+          description: 'Navigation mode for house cleaning: "Normal", "Gentle", "Deep", "Quick"'
+        stallThreshold:
+          type: number
+          description: Wheel load % for stall detection (30-80)
+        brushRpm:
+          type: number
+          description: Main brush RPM (500-1600)
+        vacuumSpeed:
+          type: number
+          description: Vacuum speed % (40-100)
+        sideBrushPower:
+          type: number
+          description: Side brush power in mW (500-1500)
+        ntfyTopic:
+          type: string
+          description: ntfy.sh topic for push notifications (empty = disabled)
+        ntfyEnabled:
+          type: boolean
+          description: Global switch - must be on for any notification to fire
+        ntfyOnDone:
+          type: boolean
+          description: Notify when cleaning completes
+        ntfyOnError:
+          type: boolean
+          description: Notify on robot error (UI_ERROR_*, code 243+)
+        ntfyOnAlert:
+          type: boolean
+          description: Notify on robot alert (UI_ALERT_*, code 201-242)
+        ntfyOnDocking:
+          type: boolean
+          description: Notify when robot returns to base
+        scheduleEnabled:
+          type: boolean
+          description: Master switch for the weekly cleaning schedule
+        sched0Hour:
+          type: number
+        sched0Min:
+          type: number
+        sched0On:
+          type: boolean
+        sched1Hour:
+          type: number
+        sched1Min:
+          type: number
+        sched1On:
+          type: boolean
+        sched2Hour:
+          type: number
+        sched2Min:
+          type: number
+        sched2On:
+          type: boolean
+        sched3Hour:
+          type: number
+        sched3Min:
+          type: number
+        sched3On:
+          type: boolean
+        sched4Hour:
+          type: number
+        sched4Min:
+          type: number
+        sched4On:
+          type: boolean
+        sched5Hour:
+          type: number
+        sched5Min:
+          type: number
+        sched5On:
+          type: boolean
+        sched6Hour:
+          type: number
+        sched6Min:
+          type: number
+        sched6On:
+          type: boolean
+        sched0Slot1Hour:
+          type: number
+        sched0Slot1Min:
+          type: number
+        sched0Slot1On:
+          type: boolean
+        sched1Slot1Hour:
+          type: number
+        sched1Slot1Min:
+          type: number
+        sched1Slot1On:
+          type: boolean
+        sched2Slot1Hour:
+          type: number
+        sched2Slot1Min:
+          type: number
+        sched2Slot1On:
+          type: boolean
+        sched3Slot1Hour:
+          type: number
+        sched3Slot1Min:
+          type: number
+        sched3Slot1On:
+          type: boolean
+        sched4Slot1Hour:
+          type: number
+        sched4Slot1Min:
+          type: number
+        sched4Slot1On:
+          type: boolean
+        sched5Slot1Hour:
+          type: number
+        sched5Slot1Min:
+          type: number
+        sched5Slot1On:
+          type: boolean
+        sched6Slot1Hour:
+          type: number
+        sched6Slot1Min:
+          type: number
+        sched6Slot1On:
+          type: boolean
+      required:
+        - tz
+        - logLevel
+        - syslogEnabled
+        - syslogIp
+        - wifiTxPower
+        - uartTxPin
+        - uartRxPin
+        - maxGpioPin
+        - hostname
+        - navMode
+        - stallThreshold
+        - brushRpm
+        - vacuumSpeed
+        - sideBrushPower
+        - ntfyTopic
+        - ntfyEnabled
+        - ntfyOnDone
+        - ntfyOnError
+        - ntfyOnAlert
+        - ntfyOnDocking
+        - scheduleEnabled
+        - sched0Hour
+        - sched0Min
+        - sched0On
+        - sched1Hour
+        - sched1Min
+        - sched1On
+        - sched2Hour
+        - sched2Min
+        - sched2On
+        - sched3Hour
+        - sched3Min
+        - sched3On
+        - sched4Hour
+        - sched4Min
+        - sched4On
+        - sched5Hour
+        - sched5Min
+        - sched5On
+        - sched6Hour
+        - sched6Min
+        - sched6On
+        - sched0Slot1Hour
+        - sched0Slot1Min
+        - sched0Slot1On
+        - sched1Slot1Hour
+        - sched1Slot1Min
+        - sched1Slot1On
+        - sched2Slot1Hour
+        - sched2Slot1Min
+        - sched2Slot1On
+        - sched3Slot1Hour
+        - sched3Slot1Min
+        - sched3Slot1On
+        - sched4Slot1Hour
+        - sched4Slot1Min
+        - sched4Slot1On
+        - sched5Slot1Hour
+        - sched5Slot1Min
+        - sched5Slot1On
+        - sched6Slot1Hour
+        - sched6Slot1Min
+        - sched6Slot1On
+    FirmwareVersion:
+      type: object
+      properties:
+        version:
+          type: string
+          description: Bridge firmware semantic version
+        chip:
+          type: string
+          description: ESP32 chip model (e.g. "ESP32-C3")
+        model:
+          type: string
+          description: Robot model name (e.g. "Botvac D7", empty until identified)
+        hostname:
+          type: string
+          description: mDNS hostname (e.g. "openneato")
+        supported:
+          type: boolean
+          description: True if the connected robot model is officially supported
+        identifying:
+          type: boolean
+          description: True while the bridge is still probing the robot model
+      required:
+        - version
+        - chip
+        - model
+        - hostname
+        - supported
+        - identifying
+    HistoryFileInfo:
+      type: object
+      properties:
+        name:
+          type: string
+          description: File name as stored on flash (may include .hs compression suffix)
+        size:
+          type: number
+          description: File size in bytes
+        compressed:
+          type: boolean
+          description: True if stored with heatshrink compression
+        recording:
+          type: boolean
+          description: True if this session is currently being recorded
+        session:
+          description: Session metadata, or null if not yet written
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/MapSession"
+        summary:
+          description: Session summary, or null if cleaning has not finished
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/MapSummary"
+      required:
+        - name
+        - size
+        - compressed
+        - recording
+        - session
+        - summary
+    MapSession:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - session
+          description: Always "session" - identifies the record type
+        mode:
+          type: string
+          description: 'Cleaning mode: "House", "Spot", or "Manual"'
+        time:
+          type: number
+          description: Unix epoch seconds when the session started
+        battery:
+          type: number
+          description: Battery percentage at session start
+      required:
+        - type
+        - mode
+        - time
+        - battery
+    MapSummary:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - summary
+          description: Always "summary" - identifies the record type
+        time:
+          type: number
+          description: Unix epoch seconds when the session ended
+        duration:
+          type: number
+          description: Session duration in seconds
+        mode:
+          type: string
+          description: 'Cleaning mode: "House", "Spot", or "Manual"'
+        recharges:
+          type: number
+          description: Number of times the robot returned to base to recharge
+        snapshots:
+          type: number
+          description: Number of pose snapshots captured
+        distanceTraveled:
+          type: number
+          description: Total distance traveled in meters
+        maxDistFromOrigin:
+          type: number
+          description: Maximum distance from origin in meters
+        totalRotation:
+          type: number
+          description: Total rotation in degrees
+        areaCovered:
+          type: number
+          description: Estimated area covered in square meters
+        errorsDuringClean:
+          type: number
+          description: Number of errors encountered during cleaning
+        batteryStart:
+          type: number
+          description: Battery percentage at session start
+        batteryEnd:
+          type: number
+          description: Battery percentage at session end
+      required:
+        - type
+        - time
+        - duration
+        - mode
+        - recharges
+        - snapshots
+        - distanceTraveled
+        - maxDistFromOrigin
+        - totalRotation
+        - areaCovered
+        - errorsDuringClean
+  responses:
+    Ok:
+      description: Success acknowledgement
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Ok"
diff --git a/frontend/biome.json b/frontend/biome.json
index 67e4982..1f69473 100644
--- a/frontend/biome.json
+++ b/frontend/biome.json
@@ -4,6 +4,7 @@
     "files": {
         "includes": [
             "src/**",
+            "!src/types.generated.ts",
             "mock/*.js",
             "scripts/**",
             "vite.config.ts",
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index ce0a779..27221fd 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,8 +13,10 @@
             "devDependencies": {
                 "@biomejs/biome": "2.4.13",
                 "@preact/preset-vite": "2.10.5",
+                "openapi-typescript": "^7.13.0",
                 "typescript": "6.0.3",
-                "vite": "8.0.10"
+                "vite": "8.0.10",
+                "yaml": "^2.8.3"
             }
         },
         "node_modules/@babel/code-frame": {
@@ -712,6 +714,52 @@
                 "url": "https://github.com/sponsors/jonschlinkert"
             }
         },
+        "node_modules/@redocly/ajv": {
+            "version": "8.11.2",
+            "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.11.2.tgz",
+            "integrity": "sha512-io1JpnwtIcvojV7QKDUSIuMN/ikdOUd1ReEnUnMKGfDVridQZ31J0MmIuqwuRjWDZfmvr+Q0MqCcfHM2gTivOg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "fast-deep-equal": "^3.1.1",
+                "json-schema-traverse": "^1.0.0",
+                "require-from-string": "^2.0.2",
+                "uri-js-replace": "^1.0.1"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/epoberezkin"
+            }
+        },
+        "node_modules/@redocly/config": {
+            "version": "0.22.0",
+            "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.22.0.tgz",
+            "integrity": "sha512-gAy93Ddo01Z3bHuVdPWfCwzgfaYgMdaZPcfL7JZ7hWJoK9V0lXDbigTWkhiPFAaLWzbOJ+kbUQG1+XwIm0KRGQ==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@redocly/openapi-core": {
+            "version": "1.34.12",
+            "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.34.12.tgz",
+            "integrity": "sha512-b32XWsz6enN6K4bx8xWsqUaXTJR/DnYT3lL1CzDYzIYKw243NNlz6fexmr71q/U4HrEcMoJGBvwAfcxOb8ymQw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@redocly/ajv": "8.11.2",
+                "@redocly/config": "0.22.0",
+                "colorette": "1.4.0",
+                "https-proxy-agent": "7.0.6",
+                "js-levenshtein": "1.1.6",
+                "js-yaml": "4.1.1",
+                "minimatch": "5.1.9",
+                "pluralize": "8.0.0",
+                "yaml-ast-parser": "0.0.43"
+            },
+            "engines": {
+                "node": ">=18.17.0",
+                "npm": ">=9.5.0"
+            }
+        },
         "node_modules/@rolldown/binding-android-arm64": {
             "version": "1.0.0-rc.17",
             "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
@@ -1035,6 +1083,33 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/agent-base": {
+            "version": "7.1.4",
+            "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+            "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 14"
+            }
+        },
+        "node_modules/ansi-colors": {
+            "version": "4.1.3",
+            "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz",
+            "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
+        "node_modules/argparse": {
+            "version": "2.0.1",
+            "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+            "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+            "dev": true,
+            "license": "Python-2.0"
+        },
         "node_modules/babel-plugin-transform-hook-names": {
             "version": "1.0.2",
             "resolved": "https://registry.npmjs.org/babel-plugin-transform-hook-names/-/babel-plugin-transform-hook-names-1.0.2.tgz",
@@ -1045,6 +1120,13 @@
                 "@babel/core": "^7.12.10"
             }
         },
+        "node_modules/balanced-match": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+            "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/baseline-browser-mapping": {
             "version": "2.10.8",
             "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.8.tgz",
@@ -1065,6 +1147,16 @@
             "dev": true,
             "license": "ISC"
         },
+        "node_modules/brace-expansion": {
+            "version": "2.1.0",
+            "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz",
+            "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "balanced-match": "^1.0.0"
+            }
+        },
         "node_modules/browserslist": {
             "version": "4.28.1",
             "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz",
@@ -1120,6 +1212,20 @@
             ],
             "license": "CC-BY-4.0"
         },
+        "node_modules/change-case": {
+            "version": "5.4.4",
+            "resolved": "https://registry.npmjs.org/change-case/-/change-case-5.4.4.tgz",
+            "integrity": "sha512-HRQyTk2/YPEkt9TnUPbOpr64Uw3KOicFWPVBb+xiHvd6eBx/qPr9xqfBFDT8P2vWsvvz4jbEkfDe71W3VyNu2w==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/colorette": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/colorette/-/colorette-1.4.0.tgz",
+            "integrity": "sha512-Y2oEozpomLn7Q3HFP7dpww7AtMJplbM9lGZP6RDfHqmbeRjiwRg4n6VM6j4KLmRke85uWEI7JqF17f3pqdRA0g==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/convert-source-map": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -1281,6 +1387,13 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/fast-deep-equal": {
+            "version": "3.1.3",
+            "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+            "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/fdir": {
             "version": "6.5.0",
             "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -1334,6 +1447,43 @@
                 "he": "bin/he"
             }
         },
+        "node_modules/https-proxy-agent": {
+            "version": "7.0.6",
+            "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+            "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "agent-base": "^7.1.2",
+                "debug": "4"
+            },
+            "engines": {
+                "node": ">= 14"
+            }
+        },
+        "node_modules/index-to-position": {
+            "version": "1.2.0",
+            "resolved": "https://registry.npmjs.org/index-to-position/-/index-to-position-1.2.0.tgz",
+            "integrity": "sha512-Yg7+ztRkqslMAS2iFaU+Oa4KTSidr63OsFGlOrJoW981kIYO3CGCS3wA95P1mUi/IVSJkn0D479KTJpVpvFNuw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/js-levenshtein": {
+            "version": "1.1.6",
+            "resolved": "https://registry.npmjs.org/js-levenshtein/-/js-levenshtein-1.1.6.tgz",
+            "integrity": "sha512-X2BB11YZtrRqY4EnQcLX5Rh373zbK4alC1FW7D7MBhL2gtcC17cTnr6DmfHZeS0s2rTHjUTMMHfG7gO8SSdw+g==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
         "node_modules/js-tokens": {
             "version": "4.0.0",
             "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -1341,6 +1491,19 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/js-yaml": {
+            "version": "4.1.1",
+            "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+            "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "argparse": "^2.0.1"
+            },
+            "bin": {
+                "js-yaml": "bin/js-yaml.js"
+            }
+        },
         "node_modules/jsesc": {
             "version": "3.1.0",
             "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -1354,6 +1517,13 @@
                 "node": ">=6"
             }
         },
+        "node_modules/json-schema-traverse": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+            "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/json5": {
             "version": "2.2.3",
             "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
@@ -1667,6 +1837,19 @@
                 "@jridgewell/sourcemap-codec": "^1.5.5"
             }
         },
+        "node_modules/minimatch": {
+            "version": "5.1.9",
+            "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.9.tgz",
+            "integrity": "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "brace-expansion": "^2.0.1"
+            },
+            "engines": {
+                "node": ">=10"
+            }
+        },
         "node_modules/ms": {
             "version": "2.1.3",
             "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1724,6 +1907,45 @@
                 "url": "https://github.com/fb55/nth-check?sponsor=1"
             }
         },
+        "node_modules/openapi-typescript": {
+            "version": "7.13.0",
+            "resolved": "https://registry.npmjs.org/openapi-typescript/-/openapi-typescript-7.13.0.tgz",
+            "integrity": "sha512-EFP392gcqXS7ntPvbhBzbF8TyBA+baIYEm791Hy5YkjDYKTnk/Tn5OQeKm5BIZvJihpp8Zzr4hzx0Irde1LNGQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@redocly/openapi-core": "^1.34.6",
+                "ansi-colors": "^4.1.3",
+                "change-case": "^5.4.4",
+                "parse-json": "^8.3.0",
+                "supports-color": "^10.2.2",
+                "yargs-parser": "^21.1.1"
+            },
+            "bin": {
+                "openapi-typescript": "bin/cli.js"
+            },
+            "peerDependencies": {
+                "typescript": "^5.x"
+            }
+        },
+        "node_modules/parse-json": {
+            "version": "8.3.0",
+            "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-8.3.0.tgz",
+            "integrity": "sha512-ybiGyvspI+fAoRQbIPRddCcSTV9/LsJbf0e/S85VLowVGzRmokfneg2kwVW/KU5rOXrPSbF1qAKPMgNTqqROQQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@babel/code-frame": "^7.26.2",
+                "index-to-position": "^1.1.0",
+                "type-fest": "^4.39.1"
+            },
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/picocolors": {
             "version": "1.1.1",
             "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1744,6 +1966,16 @@
                 "url": "https://github.com/sponsors/jonschlinkert"
             }
         },
+        "node_modules/pluralize": {
+            "version": "8.0.0",
+            "resolved": "https://registry.npmjs.org/pluralize/-/pluralize-8.0.0.tgz",
+            "integrity": "sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=4"
+            }
+        },
         "node_modules/postcss": {
             "version": "8.5.12",
             "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
@@ -1783,6 +2015,16 @@
                 "url": "https://opencollective.com/preact"
             }
         },
+        "node_modules/require-from-string": {
+            "version": "2.0.2",
+            "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+            "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
         "node_modules/rolldown": {
             "version": "1.0.0-rc.17",
             "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
@@ -1867,6 +2109,19 @@
                 "node": ">=16"
             }
         },
+        "node_modules/supports-color": {
+            "version": "10.2.2",
+            "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz",
+            "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/chalk/supports-color?sponsor=1"
+            }
+        },
         "node_modules/tinyglobby": {
             "version": "0.2.16",
             "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
@@ -1892,6 +2147,19 @@
             "license": "0BSD",
             "optional": true
         },
+        "node_modules/type-fest": {
+            "version": "4.41.0",
+            "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
+            "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
+            "dev": true,
+            "license": "(MIT OR CC0-1.0)",
+            "engines": {
+                "node": ">=16"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/typescript": {
             "version": "6.0.3",
             "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
@@ -1937,6 +2205,13 @@
                 "browserslist": ">= 4.21.0"
             }
         },
+        "node_modules/uri-js-replace": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/uri-js-replace/-/uri-js-replace-1.0.1.tgz",
+            "integrity": "sha512-W+C9NWNLFOoBI2QWDp4UT9pv65r2w5Cx+3sTYFvtMdDBxkKt1syCqsUdSFAChbEe1uK5TfS04wt/nGwmaeIQ0g==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/vite": {
             "version": "8.0.10",
             "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
@@ -2040,6 +2315,39 @@
             "dev": true,
             "license": "ISC"
         },
+        "node_modules/yaml": {
+            "version": "2.8.3",
+            "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
+            "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+            "dev": true,
+            "license": "ISC",
+            "bin": {
+                "yaml": "bin.mjs"
+            },
+            "engines": {
+                "node": ">= 14.6"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/eemeli"
+            }
+        },
+        "node_modules/yaml-ast-parser": {
+            "version": "0.0.43",
+            "resolved": "https://registry.npmjs.org/yaml-ast-parser/-/yaml-ast-parser-0.0.43.tgz",
+            "integrity": "sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==",
+            "dev": true,
+            "license": "Apache-2.0"
+        },
+        "node_modules/yargs-parser": {
+            "version": "21.1.1",
+            "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+            "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+            "dev": true,
+            "license": "ISC",
+            "engines": {
+                "node": ">=12"
+            }
+        },
         "node_modules/zimmerframe": {
             "version": "1.1.4",
             "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index d68c33e..b55f8c5 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -4,8 +4,9 @@
     "version": "0.0.1",
     "type": "module",
     "scripts": {
-        "dev": "vite",
-        "build": "biome check && tsc --noEmit && vite build && node scripts/embed_frontend.js && node scripts/gen_api_docs.js",
+        "dev": "npm run gen:types && vite",
+        "gen:types": "openapi-typescript --root-types --root-types-no-schema-prefix --output src/types.generated.ts api/openapi.yaml",
+        "build": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build && node scripts/embed_frontend.js",
         "preview": "vite preview",
         "check": "biome check",
         "fix": "biome check --write",
@@ -17,7 +18,9 @@
     "devDependencies": {
         "@biomejs/biome": "2.4.13",
         "@preact/preset-vite": "2.10.5",
+        "openapi-typescript": "^7.13.0",
         "typescript": "6.0.3",
-        "vite": "8.0.10"
+        "vite": "8.0.10",
+        "yaml": "^2.8.3"
     }
 }
diff --git a/frontend/scripts/check_api_paths.js b/frontend/scripts/check_api_paths.js
new file mode 100644
index 0000000..c8db940
--- /dev/null
+++ b/frontend/scripts/check_api_paths.js
@@ -0,0 +1,70 @@
+// Compares route paths registered in firmware/src/web_server.cpp against the
+// paths declared in frontend/api/openapi.yaml. Fails the build if either side
+// has paths the other doesn't, so a new route can't ship without spec updates
+// (and a deleted route can't linger in the spec).
+//
+// Routes intentionally omitted from the spec must be listed in IGNORED_PATHS
+// below.
+//
+// Usage: node frontend/scripts/check_api_paths.js
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.join(__dirname, "..", "..");
+const cppPath = path.join(repoRoot, "firmware", "src", "web_server.cpp");
+const yamlPath = path.join(__dirname, "..", "api", "openapi.yaml");
+
+// Routes registered in firmware but deliberately undocumented (e.g. diagnostic
+// passthroughs that shouldn't be advertised as a stable API).
+const IGNORED_PATHS = new Set(["/api/serial"]);
+
+function extractFirmwarePaths() {
+    const src = fs.readFileSync(cppPath, "utf8");
+    const re = /(?:registerGetRoute|registerPostRoute|loggedRoute|loggedBodyRoute|server\.on)\s*\(\s*"(\/api\/[^"]+)"/g;
+    const paths = new Set();
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: classic regex loop
+    while ((m = re.exec(src))) {
+        if (!IGNORED_PATHS.has(m[1])) paths.add(m[1]);
+    }
+    return paths;
+}
+
+function extractSpecPaths() {
+    const src = fs.readFileSync(yamlPath, "utf8");
+    const doc = YAML.parse(src);
+    const paths = new Set();
+    for (const p of Object.keys(doc.paths || {})) {
+        // OpenAPI paths use {param} placeholders; firmware paths don't (the
+        // handler resolves the trailing segment from request->url()). Compare
+        // by the leading static prefix.
+        const prefix = p.replace(/\/\{[^}]+\}.*/, "");
+        paths.add(prefix);
+    }
+    return paths;
+}
+
+const firmwarePaths = extractFirmwarePaths();
+const specPaths = extractSpecPaths();
+
+const missingInSpec = [...firmwarePaths].filter((p) => !specPaths.has(p)).sort();
+const missingInFirmware = [...specPaths].filter((p) => !firmwarePaths.has(p)).sort();
+
+if (missingInSpec.length || missingInFirmware.length) {
+    process.stderr.write("[check_api_paths] HTTP route surface drift detected:\n");
+    if (missingInSpec.length) {
+        process.stderr.write(`  registered in firmware but missing from openapi.yaml: ${missingInSpec.join(", ")}\n`);
+    }
+    if (missingInFirmware.length) {
+        process.stderr.write(
+            `  declared in openapi.yaml but not registered in firmware: ${missingInFirmware.join(", ")}\n`,
+        );
+    }
+    process.exit(1);
+}
+
+process.stdout.write(`[check_api_paths] OK - ${firmwarePaths.size} routes in sync\n`);
diff --git a/frontend/scripts/gen_api_docs.js b/frontend/scripts/gen_api_docs.js
deleted file mode 100644
index a5c2c42..0000000
--- a/frontend/scripts/gen_api_docs.js
+++ /dev/null
@@ -1,1013 +0,0 @@
-// Generates an OpenAPI 3.0 spec and a human-readable Markdown reference for
-// the HTTP API exposed by the firmware.
-//
-// Sources:
-//   - firmware/src/web_server.cpp  (route registrations + // @doc directives)
-//   - frontend/src/types.ts        (response/body schemas via TSDoc)
-//
-// Outputs:
-//   - frontend/dist-docs/openapi.json
-//   - frontend/dist-docs/api-reference.md
-//
-// Usage: node frontend/scripts/gen_api_docs.js
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import ts from "typescript";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const repoRoot = path.join(__dirname, "..", "..");
-const cppPath = path.join(repoRoot, "firmware", "src", "web_server.cpp");
-const tsPath = path.join(repoRoot, "frontend", "src", "types.ts");
-const outDir = path.join(__dirname, "..", "dist-docs");
-
-const VERSION = process.env.OPENNEATO_VERSION || readFirmwareVersion();
-
-// Maps the manager method referenced in registerGetRoute(...) to the response
-// schema name in types.ts. Static_cast<...> wrappers are stripped before
-// lookup.
-const GET_RESPONSE_TYPES = {
-    "&NeatoSerial::getVersion": "VersionData",
-    "&NeatoSerial::getCharger": "ChargerData",
-    "&NeatoSerial::getMotors": "MotorData",
-    "&NeatoSerial::getState": "StateData",
-    "&NeatoSerial::getErr": "ErrorData",
-    "&NeatoSerial::getLdsScan": "LidarScan",
-    "&NeatoSerial::getUserSettings": "UserSettingsData",
-};
-
-const TAG_DEFAULTS = {
-    Sensors: "Read-only telemetry from the robot",
-    Actions: "Control commands sent to the robot",
-    Manual: "Manual cleaning mode (joystick, motors)",
-    Logs: "Diagnostic log files stored in flash",
-    System: "ESP32 system health and lifecycle",
-    Settings: "User-configurable bridge settings",
-    Firmware: "ESP32 firmware version and OTA update",
-    History: "Cleaning session history and map data",
-};
-
-// -- C++ route extraction ----------------------------------------------------
-
-function parseCpp() {
-    const src = fs.readFileSync(cppPath, "utf8");
-    const lines = src.split("\n");
-
-    const routes = [];
-    let pendingDoc = null;
-    let currentTag = null;
-
-    const blankEntry = () => ({
-        summary: null,
-        manualPath: null,
-        manualMethod: null,
-        queries: [],
-        pathParams: [],
-        body: null,
-        responses: [],
-        errors: [],
-        tag: null,
-    });
-
-    const startDoc = () => {
-        if (!pendingDoc) {
-            pendingDoc = {
-                skip: false,
-                tag: null,
-                entries: [],
-                _currentEntry: null,
-            };
-        }
-        if (!pendingDoc._currentEntry) {
-            pendingDoc._currentEntry = blankEntry();
-            pendingDoc.entries.push(pendingDoc._currentEntry);
-        }
-    };
-
-    const handleDocLine = (raw) => {
-        const tagMatch = raw.match(/^\s*\/\/\s*@tag\s+([A-Za-z][\w-]*)\s*:\s*(.+?)\s*$/);
-        if (tagMatch) {
-            const [, name, desc] = tagMatch;
-            currentTag = name;
-            TAG_DEFAULTS[name] = desc;
-            return;
-        }
-
-        const docMatch = raw.match(/^\s*\/\/\s*@doc\s+(.*)$/);
-        if (!docMatch) return;
-        const rest = docMatch[1].trim();
-
-        if (rest === "skip") {
-            startDoc();
-            pendingDoc.skip = true;
-            return;
-        }
-
-        const colon = rest.indexOf(":");
-        if (colon < 0) {
-            warn(`Malformed @doc directive: ${raw.trim()}`);
-            return;
-        }
-        const key = rest.slice(0, colon).trim().toLowerCase();
-        const value = rest.slice(colon + 1).trim();
-
-        startDoc();
-
-        // "path:" starts a new entry within the same comment block (e.g. when a
-        // single server.on() handler covers /api/logs and /api/logs/{filename}).
-        if (key === "path" && pendingDoc._currentEntry.manualPath) {
-            pendingDoc._currentEntry = blankEntry();
-            pendingDoc.entries.push(pendingDoc._currentEntry);
-        }
-
-        const entry = pendingDoc._currentEntry;
-        switch (key) {
-            case "path":
-                entry.manualPath = value;
-                break;
-            case "method":
-                entry.manualMethod = value.toUpperCase();
-                break;
-            case "tag":
-                entry.tag = value;
-                break;
-            case "summary":
-                entry.summary = value;
-                break;
-            case "query":
-                entry.queries.push(parseParamSpec(value));
-                break;
-            case "param":
-                entry.pathParams.push(parseParamSpec(value));
-                break;
-            case "body":
-                entry.body = parseBodySpec(value);
-                break;
-            case "response":
-                entry.responses.push(parseResponseSpec(value));
-                break;
-            case "errors":
-                entry.errors.push(...parseErrorsSpec(value));
-                break;
-            default:
-                warn(`Unknown @doc key: ${key}`);
-        }
-    };
-
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-
-        if (/^\s*\/\/\s*@(doc|tag)\b/.test(line)) {
-            handleDocLine(line);
-            continue;
-        }
-
-        if (!pendingDoc) continue;
-
-        if (pendingDoc.skip) {
-            // Consume the next registration call and forget the pending doc.
-            if (looksLikeRegistration(line)) pendingDoc = null;
-            continue;
-        }
-
-        const consumed = tryConsumeRegistration(lines, i, pendingDoc, currentTag, routes);
-        if (consumed > 0) {
-            i += consumed - 1;
-            pendingDoc = null;
-        }
-    }
-
-    return routes;
-}
-
-function looksLikeRegistration(line) {
-    return /\b(registerGetRoute|registerPostRoute|loggedRoute|loggedBodyRoute|server\.on)\s*\(/.test(line);
-}
-
-// Reads a possibly multi-line registration call starting at lines[i] and, if
-// found, appends one or more route records to `routes`. Returns the number of
-// source lines consumed (0 if no registration was found on this line).
-function tryConsumeRegistration(lines, i, pendingDoc, currentTag, routes) {
-    if (!looksLikeRegistration(lines[i])) return 0;
-
-    let depth = 0;
-    let buf = "";
-    let consumed = 0;
-    let started = false;
-    for (let j = i; j < lines.length && j < i + 30; j++) {
-        const line = lines[j];
-        for (let k = 0; k < line.length; k++) {
-            const c = line[k];
-            if (c === "(") {
-                depth++;
-                started = true;
-            } else if (c === ")") {
-                depth--;
-            }
-            buf += c;
-            if (started && depth === 0) {
-                consumed = j - i + 1;
-                break;
-            }
-        }
-        buf += "\n";
-        if (started && depth === 0) break;
-        consumed = j - i + 1;
-    }
-
-    const helper = buf.match(/(registerGetRoute|registerPostRoute|loggedRoute|loggedBodyRoute|server\.on)\s*\(/);
-    if (!helper) return 0;
-    const helperName = helper[1];
-
-    const pathMatch = buf.match(/"([^"]+)"/);
-    const sniffedPath = pathMatch ? pathMatch[1] : null;
-
-    const methodMatch = buf.match(/HTTP_(GET|POST|PUT|DELETE|PATCH)/);
-    const sniffedMethod = methodMatch ? methodMatch[1] : null;
-
-    let methodPtr = null;
-    if (helperName === "registerGetRoute" || helperName === "registerPostRoute") {
-        const cast = buf.match(/static_cast<[^>]+>\s*\(\s*(&[A-Za-z_][\w:]*::[A-Za-z_]\w*)\s*\)/);
-        const direct = buf.match(/,\s*(&[A-Za-z_][\w:]*::[A-Za-z_]\w*)\s*,/);
-        methodPtr = cast ? cast[1] : direct ? direct[1] : null;
-    }
-
-    const helperMethod = {
-        registerGetRoute: "GET",
-        registerPostRoute: "POST",
-    }[helperName];
-
-    const entries = pendingDoc.entries.filter(hasContent);
-    if (entries.length === 0) entries.push({ ...pendingDoc.entries[0] });
-
-    for (const entry of entries) {
-        const route = {
-            path: entry.manualPath || sniffedPath,
-            method: entry.manualMethod || helperMethod || sniffedMethod,
-            tag: entry.tag || pendingDoc.tag || currentTag,
-            summary: entry.summary,
-            queries: entry.queries,
-            pathParams: entry.pathParams,
-            body: entry.body,
-            responses: entry.responses,
-            errors: entry.errors,
-        };
-
-        if (!route.path || !route.method) {
-            warn(`Registration without path/method (helper=${helperName}, line ${i + 1})`);
-            continue;
-        }
-
-        // Defaults for template helpers when @doc didn't override.
-        if (helperName === "registerGetRoute") {
-            if (route.responses.length === 0) {
-                const typeName = methodPtr && GET_RESPONSE_TYPES[methodPtr];
-                if (typeName) route.responses = [{ kind: "ref", value: typeName }];
-            }
-            if (route.errors.length === 0) {
-                route.errors = [{ code: 504, description: "robot timeout" }];
-            }
-        } else if (helperName === "registerPostRoute") {
-            if (route.responses.length === 0) {
-                route.responses = [{ kind: "ok" }];
-            }
-            if (route.errors.length === 0) {
-                route.errors = [
-                    { code: 503, description: "robot busy" },
-                    { code: 504, description: "robot timeout" },
-                ];
-            }
-        }
-
-        routes.push(route);
-    }
-
-    return consumed;
-}
-
-function hasContent(entry) {
-    return (
-        entry.manualPath ||
-        entry.summary ||
-        entry.queries.length ||
-        entry.pathParams.length ||
-        entry.body ||
-        entry.responses.length ||
-        entry.errors.length
-    );
-}
-
-// "name type [enum=a,b,c | int range | bool 0..1] [required] [(notes)]"
-function parseParamSpec(value) {
-    const tokens = tokenize(value.trim());
-    const out = {
-        name: tokens.shift(),
-        type: "string",
-        required: false,
-        enum: null,
-        notes: null,
-    };
-    while (tokens.length) {
-        const tok = tokens.shift();
-        if (tok === "required") out.required = true;
-        else if (tok === "boolean") out.type = "boolean";
-        else if (tok === "integer") out.type = "integer";
-        else if (tok === "number") out.type = "number";
-        else if (tok === "string") out.type = "string";
-        else if (tok.startsWith("enum=")) {
-            out.type = "string";
-            out.enum = tok.slice(5).split(",");
-        } else if (/^-?\d+\.\.-?\d+$/.test(tok)) {
-            const [min, max] = tok.split("..").map(Number);
-            out.minimum = min;
-            out.maximum = max;
-        } else if (tok.startsWith("(") && tok.endsWith(")")) {
-            out.notes = tok.slice(1, -1);
-        }
-    }
-    return out;
-}
-
-// Splits on whitespace but keeps "(...)" groups intact.
-function tokenize(s) {
-    const out = [];
-    let i = 0;
-    while (i < s.length) {
-        while (i < s.length && /\s/.test(s[i])) i++;
-        if (i >= s.length) break;
-        if (s[i] === "(") {
-            const end = s.indexOf(")", i);
-            if (end < 0) {
-                out.push(s.slice(i));
-                break;
-            }
-            out.push(s.slice(i, end + 1));
-            i = end + 1;
-        } else {
-            let j = i;
-            while (j < s.length && !/\s/.test(s[j])) j++;
-            out.push(s.slice(i, j));
-            i = j;
-        }
-    }
-    return out;
-}
-
-function parseBodySpec(value) {
-    const trimmed = value.trim();
-    if (/^multipart\/form-data/i.test(trimmed)) {
-        return { kind: "multipart", description: trimmed };
-    }
-    const refMatch = trimmed.match(/^([A-Z][A-Za-z0-9_]*)\s*(?:\(partial\))?$/);
-    if (refMatch) {
-        return { kind: "ref", ref: refMatch[1], partial: /\(partial\)/.test(trimmed) };
-    }
-    return { kind: "raw", description: trimmed };
-}
-
-function parseResponseSpec(value) {
-    const trimmed = value.trim();
-    if (trimmed === "Ok") return { kind: "ok" };
-    const arrMatch = trimmed.match(/^array of ([A-Z][A-Za-z0-9_]*)$/);
-    if (arrMatch) return { kind: "array", ref: arrMatch[1] };
-    if (/^[A-Z][A-Za-z0-9_]*$/.test(trimmed)) return { kind: "ref", value: trimmed };
-    return { kind: "raw", description: trimmed };
-}
-
-function parseErrorsSpec(value) {
-    // Split on commas, but ignore commas inside parentheses so descriptions
-    // like "400=update failed (bad hash, write error)" stay intact.
-    const parts = [];
-    let depth = 0;
-    let cur = "";
-    for (const ch of value) {
-        if (ch === "(") depth++;
-        else if (ch === ")") depth--;
-        if (ch === "," && depth === 0) {
-            parts.push(cur);
-            cur = "";
-        } else {
-            cur += ch;
-        }
-    }
-    if (cur) parts.push(cur);
-
-    return parts
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .map((part) => {
-            const m = part.match(/^(\d{3})\s*=\s*(.+)$/);
-            if (!m) {
-                warn(`Malformed error spec: ${part}`);
-                return null;
-            }
-            return { code: Number(m[1]), description: m[2].trim() };
-        })
-        .filter(Boolean);
-}
-
-// -- TypeScript types extraction --------------------------------------------
-
-function parseTypes() {
-    const program = ts.createProgram([tsPath], {
-        target: ts.ScriptTarget.ES2020,
-        module: ts.ModuleKind.ESNext,
-        strict: true,
-        noEmit: true,
-    });
-    const checker = program.getTypeChecker();
-    const sourceFile = program.getSourceFile(tsPath);
-    if (!sourceFile) throw new Error(`Could not load ${tsPath}`);
-
-    const interfaces = {};
-    ts.forEachChild(sourceFile, (node) => {
-        if (ts.isInterfaceDeclaration(node)) {
-            interfaces[node.name.text] = describeInterface(node, checker);
-        } else if (ts.isTypeAliasDeclaration(node)) {
-            interfaces[node.name.text] = describeTypeAlias(node);
-        }
-    });
-    return interfaces;
-}
-
-function describeInterface(node, checker) {
-    const description = jsDocText(node);
-    const properties = node.members
-        .filter(ts.isPropertySignature)
-        .map((member) => describeProperty(member, checker))
-        .filter(Boolean);
-    return { kind: "object", description, properties };
-}
-
-function describeTypeAlias(node) {
-    return { kind: "alias", description: jsDocText(node), text: node.type.getText() };
-}
-
-function describeProperty(member, checker) {
-    const name = member.name.getText();
-    const optional = !!member.questionToken;
-    const description = jsDocText(member);
-    const schema = typeNodeToSchema(member.type, checker);
-    return { name, optional, description, schema };
-}
-
-function typeNodeToSchema(typeNode, checker) {
-    if (!typeNode) return { type: "string" };
-
-    switch (typeNode.kind) {
-        case ts.SyntaxKind.StringKeyword:
-            return { type: "string" };
-        case ts.SyntaxKind.NumberKeyword:
-            return { type: "number" };
-        case ts.SyntaxKind.BooleanKeyword:
-            return { type: "boolean" };
-        case ts.SyntaxKind.NullKeyword:
-            return { type: "null" };
-    }
-
-    if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
-        return { type: "string", const: typeNode.literal.text };
-    }
-
-    if (ts.isUnionTypeNode(typeNode)) {
-        const parts = typeNode.types.map((t) => typeNodeToSchema(t, checker));
-        const stringLiterals = parts.filter((p) => p.type === "string" && p.const !== undefined);
-        const hasNull = parts.some((p) => p.type === "null");
-        const nonNull = parts.filter((p) => p.type !== "null");
-        if (stringLiterals.length === parts.length) {
-            return { type: "string", enum: stringLiterals.map((p) => p.const) };
-        }
-        if (nonNull.length === 1) {
-            return { ...nonNull[0], nullable: hasNull };
-        }
-        return { oneOf: parts };
-    }
-
-    if (ts.isArrayTypeNode(typeNode)) {
-        return { type: "array", items: typeNodeToSchema(typeNode.elementType, checker) };
-    }
-
-    if (ts.isTupleTypeNode(typeNode)) {
-        return {
-            type: "array",
-            prefixItems: typeNode.elements.map((e) => typeNodeToSchema(ts.isNamedTupleMember(e) ? e.type : e, checker)),
-        };
-    }
-
-    if (ts.isTypeReferenceNode(typeNode)) {
-        return { ref: typeNode.typeName.getText() };
-    }
-
-    return { type: "string" };
-}
-
-function jsDocText(node) {
-    const docs = ts.getJSDocCommentsAndTags(node);
-    if (!docs.length) return null;
-    const parts = docs
-        .map((d) => {
-            if (typeof d.comment === "string") return d.comment;
-            if (Array.isArray(d.comment)) return d.comment.map((c) => (typeof c === "string" ? c : c.text)).join("");
-            return "";
-        })
-        .filter(Boolean);
-    const text = parts.join(" ").trim();
-    return text || null;
-}
-
-// -- OpenAPI builder ---------------------------------------------------------
-
-function buildOpenApi(routes, types) {
-    const tagsUsed = new Set();
-    for (const r of routes) if (r.tag) tagsUsed.add(r.tag);
-
-    const openapi = {
-        openapi: "3.0.3",
-        info: {
-            title: "OpenNeato API",
-            version: VERSION,
-            description:
-                "HTTP API exposed by the OpenNeato firmware. All endpoints are served on the local network only " +
-                "(no authentication, no TLS). The diagnostic `/api/serial` passthrough is documented separately " +
-                "in the [user guide](https://github.com/renjfk/OpenNeato/blob/main/docs/user-guide.md#serial-api).",
-        },
-        servers: [
-            {
-                url: "http://{host}",
-                description: "OpenNeato bridge on local network",
-                variables: { host: { default: "neato.local" } },
-            },
-        ],
-        tags: [...tagsUsed].map((name) => ({ name, description: TAG_DEFAULTS[name] || "" })),
-        paths: {},
-        components: {
-            schemas: buildSchemas(types, routes),
-            responses: {
-                Ok: {
-                    description: "Success acknowledgement",
-                    content: {
-                        "application/json": {
-                            schema: { $ref: "#/components/schemas/Ok" },
-                        },
-                    },
-                },
-            },
-        },
-    };
-
-    for (const route of routes) {
-        if (!openapi.paths[route.path]) openapi.paths[route.path] = {};
-        const op = {};
-        if (route.tag) op.tags = [route.tag];
-        if (route.summary) op.summary = route.summary;
-        const params = buildParameters(route);
-        if (params.length) op.parameters = params;
-        const body = buildRequestBody(route);
-        if (body) op.requestBody = body;
-        op.responses = buildResponses(route);
-        openapi.paths[route.path][route.method.toLowerCase()] = op;
-    }
-
-    return openapi;
-}
-
-function buildSchemas(types, routes) {
-    const referenced = collectReferenced(routes, types);
-    const schemas = {
-        Ok: {
-            type: "object",
-            properties: { ok: { type: "boolean" } },
-            required: ["ok"],
-        },
-        Error: {
-            type: "object",
-            properties: { error: { type: "string" } },
-            required: ["error"],
-        },
-    };
-    for (const name of referenced) {
-        const def = types[name];
-        if (!def || def.kind !== "object") continue;
-        schemas[name] = objectToSchema(def);
-    }
-    return schemas;
-}
-
-function collectReferenced(routes, types) {
-    const out = new Set();
-    const visit = (n) => {
-        if (out.has(n)) return;
-        out.add(n);
-        const def = types[n];
-        if (!def || def.kind !== "object") return;
-        for (const prop of def.properties) walkSchema(prop.schema, visit);
-    };
-    for (const route of routes) {
-        if (route.body?.kind === "ref") visit(route.body.ref);
-        for (const r of route.responses || []) {
-            if (r.kind === "ref") visit(r.value);
-            if (r.kind === "array") visit(r.ref);
-        }
-    }
-    return out;
-}
-
-function walkSchema(node, visit) {
-    if (!node) return;
-    if (node.ref) visit(node.ref);
-    if (node.items) walkSchema(node.items, visit);
-    if (node.prefixItems) for (const i of node.prefixItems) walkSchema(i, visit);
-    if (node.oneOf) for (const o of node.oneOf) walkSchema(o, visit);
-}
-
-function objectToSchema(def) {
-    const properties = {};
-    const required = [];
-    for (const prop of def.properties) {
-        properties[prop.name] = propertyToSchema(prop);
-        if (!prop.optional) required.push(prop.name);
-    }
-    const out = { type: "object", properties };
-    if (def.description) out.description = def.description;
-    if (required.length) out.required = required;
-    return out;
-}
-
-function propertyToSchema(prop) {
-    const schema = schemaShape(prop.schema);
-    if (prop.description) schema.description = prop.description;
-    return schema;
-}
-
-function schemaShape(node) {
-    if (!node) return { type: "string" };
-    if (node.ref) return { $ref: `#/components/schemas/${node.ref}` };
-    if (node.oneOf) return { oneOf: node.oneOf.map(schemaShape) };
-    if (node.type === "array") {
-        const out = { type: "array" };
-        if (node.items) out.items = schemaShape(node.items);
-        // OpenAPI 3.0 doesn't support prefixItems; collapse to items of unknown
-        // type for tuple-shaped schemas. (Only used for MapCoverageCell which
-        // isn't part of any HTTP response in practice.)
-        if (node.prefixItems) out.items = {};
-        return out;
-    }
-    const out = { type: node.type };
-    if (node.const !== undefined) out.enum = [node.const];
-    if (node.enum) out.enum = node.enum;
-    if (node.nullable) out.nullable = true;
-    return out;
-}
-
-function buildParameters(route) {
-    const params = [];
-    for (const p of route.pathParams) {
-        params.push({
-            name: p.name,
-            in: "path",
-            required: true,
-            description: p.notes || undefined,
-            schema: paramSchema(p),
-        });
-    }
-    for (const q of route.queries) {
-        params.push({
-            name: q.name,
-            in: "query",
-            required: !!q.required,
-            description: q.notes || undefined,
-            schema: paramSchema(q),
-        });
-    }
-    return params.map(stripUndefined);
-}
-
-function paramSchema(p) {
-    const out = { type: p.type };
-    if (p.enum) out.enum = p.enum;
-    if (p.minimum !== undefined) out.minimum = p.minimum;
-    if (p.maximum !== undefined) out.maximum = p.maximum;
-    return out;
-}
-
-function buildRequestBody(route) {
-    if (!route.body) return null;
-    if (route.body.kind === "ref") {
-        return {
-            required: true,
-            content: {
-                "application/json": {
-                    schema: { $ref: `#/components/schemas/${route.body.ref}` },
-                },
-            },
-        };
-    }
-    if (route.body.kind === "multipart") {
-        return {
-            required: true,
-            content: {
-                "multipart/form-data": {
-                    schema: {
-                        type: "object",
-                        properties: { file: { type: "string", format: "binary" } },
-                        required: ["file"],
-                    },
-                },
-            },
-        };
-    }
-    return null;
-}
-
-function buildResponses(route) {
-    const out = {};
-    const responses = route.responses || [];
-    if (responses.length === 0) {
-        out["200"] = { $ref: "#/components/responses/Ok" };
-    } else {
-        for (const r of responses) {
-            if (r.kind === "ok") {
-                out["200"] = { $ref: "#/components/responses/Ok" };
-            } else if (r.kind === "ref") {
-                out["200"] = jsonResponse({ $ref: `#/components/schemas/${r.value}` });
-            } else if (r.kind === "array") {
-                out["200"] = jsonResponse({
-                    type: "array",
-                    items: { $ref: `#/components/schemas/${r.ref}` },
-                });
-            } else if (r.kind === "raw") {
-                const ct = r.description.split(/\s+/)[0];
-                out["200"] = {
-                    description: r.description,
-                    content: { [ct]: { schema: { type: "string" } } },
-                };
-            }
-        }
-    }
-    for (const e of route.errors) {
-        out[String(e.code)] = {
-            description: e.description,
-            content: {
-                "application/json": { schema: { $ref: "#/components/schemas/Error" } },
-            },
-        };
-    }
-    return out;
-}
-
-function jsonResponse(schema) {
-    return {
-        description: "OK",
-        content: { "application/json": { schema } },
-    };
-}
-
-function stripUndefined(obj) {
-    if (Array.isArray(obj)) return obj.map(stripUndefined);
-    if (obj && typeof obj === "object") {
-        const out = {};
-        for (const [k, v] of Object.entries(obj)) {
-            if (v === undefined) continue;
-            out[k] = stripUndefined(v);
-        }
-        return out;
-    }
-    return obj;
-}
-
-// -- Markdown renderer (operates on the validated OpenAPI document) ---------
-
-function renderMarkdown(spec) {
-    const lines = [];
-    lines.push(`# ${spec.info.title}`);
-    lines.push("");
-    lines.push(`Version: \`${spec.info.version}\``);
-    lines.push("");
-    if (spec.info.description) lines.push(spec.info.description);
-    lines.push("");
-    lines.push("## Base URL");
-    lines.push("");
-    for (const s of spec.servers || []) {
-        lines.push(`- \`${s.url}\` ${s.description ? `- ${s.description}` : ""}`);
-    }
-    lines.push("");
-
-    // Group operations by tag, preserving the order tags appear in the spec.
-    const byTag = new Map();
-    for (const tag of spec.tags || []) byTag.set(tag.name, []);
-    byTag.set("Other", []);
-
-    for (const [pathKey, pathItem] of Object.entries(spec.paths)) {
-        for (const method of ["get", "post", "put", "delete", "patch"]) {
-            const op = pathItem[method];
-            if (!op) continue;
-            const tag = op.tags?.[0] || "Other";
-            if (!byTag.has(tag)) byTag.set(tag, []);
-            byTag.get(tag).push({ method: method.toUpperCase(), path: pathKey, op });
-        }
-    }
-
-    lines.push("## Endpoints");
-    lines.push("");
-
-    for (const [tagName, ops] of byTag) {
-        if (ops.length === 0) continue;
-        const tagDef = (spec.tags || []).find((t) => t.name === tagName);
-        lines.push(`### ${tagName}`);
-        if (tagDef?.description) lines.push(tagDef.description);
-        lines.push("");
-        for (const { method, path: routePath, op } of ops) {
-            renderOperation(method, routePath, op, spec, lines);
-        }
-    }
-
-    lines.push("## Schemas");
-    lines.push("");
-    const schemas = spec.components?.schemas || {};
-    const schemaNames = Object.keys(schemas).sort();
-    for (const name of schemaNames) {
-        renderSchema(name, schemas[name], lines);
-    }
-
-    return lines.join("\n");
-}
-
-function renderOperation(method, routePath, op, spec, lines) {
-    lines.push(`#### \`${method} ${routePath}\``);
-    lines.push("");
-    if (op.summary) {
-        lines.push(op.summary);
-        lines.push("");
-    }
-    if (op.parameters?.length) {
-        lines.push("**Parameters**");
-        lines.push("");
-        lines.push("| Name | In | Type | Required | Description |");
-        lines.push("|------|----|------|----------|-------------|");
-        for (const p of op.parameters) {
-            lines.push(
-                `| \`${p.name}\` | ${p.in} | ${formatParamSchema(p.schema)} | ${p.required ? "yes" : "no"} | ${escapeMd(p.description || "")} |`,
-            );
-        }
-        lines.push("");
-    }
-    if (op.requestBody) {
-        lines.push("**Request body**");
-        lines.push("");
-        const content = op.requestBody.content || {};
-        const ct = Object.keys(content)[0];
-        if (ct === "application/json") {
-            const ref = content[ct]?.schema?.$ref;
-            if (ref) {
-                const name = ref.split("/").pop();
-                lines.push(`JSON object matching [\`${name}\`](#${name.toLowerCase()}).`);
-            } else {
-                lines.push("JSON body.");
-            }
-        } else if (ct === "multipart/form-data") {
-            lines.push("`multipart/form-data` with a `file` field containing the upload payload.");
-        } else if (ct) {
-            lines.push(`Content type \`${ct}\`.`);
-        }
-        lines.push("");
-    }
-    lines.push("**Responses**");
-    lines.push("");
-    lines.push("| Status | Description | Body |");
-    lines.push("|--------|-------------|------|");
-    for (const [status, resp] of Object.entries(op.responses || {})) {
-        const resolved = resolveResponse(resp, spec);
-        const body = describeResponseBody(resolved);
-        lines.push(`| ${status} | ${escapeMd(resolved.description || "")} | ${body} |`);
-    }
-    lines.push("");
-}
-
-function resolveResponse(resp, spec) {
-    if (!resp.$ref) return resp;
-    const name = resp.$ref.split("/").pop();
-    return spec.components?.responses?.[name] || { description: "" };
-}
-
-function describeResponseBody(resp) {
-    if (!resp.content) return "";
-    const ct = Object.keys(resp.content)[0];
-    if (!ct) return "";
-    const schema = resp.content[ct]?.schema;
-    if (!schema) return `\`${ct}\``;
-    if (schema.$ref) {
-        const name = schema.$ref.split("/").pop();
-        return `[\`${name}\`](#${name.toLowerCase()})`;
-    }
-    if (schema.type === "array" && schema.items?.$ref) {
-        const name = schema.items.$ref.split("/").pop();
-        return `array of [\`${name}\`](#${name.toLowerCase()})`;
-    }
-    if (schema.type === "object" && schema.properties) {
-        const fields = Object.keys(schema.properties)
-            .map((k) => `\`${k}\``)
-            .join(", ");
-        return `object: ${fields}`;
-    }
-    return `\`${ct}\``;
-}
-
-function renderSchema(name, schema, lines) {
-    lines.push(`### \`${name}\``);
-    if (schema.description) {
-        lines.push("");
-        lines.push(schema.description);
-    }
-    lines.push("");
-    if (schema.type === "object" && schema.properties) {
-        const required = new Set(schema.required || []);
-        lines.push("| Field | Type | Required | Description |");
-        lines.push("|-------|------|----------|-------------|");
-        for (const [field, fs] of Object.entries(schema.properties)) {
-            lines.push(
-                `| \`${field}\` | ${formatPropSchema(fs)} | ${required.has(field) ? "yes" : "no"} | ${escapeMd(fs.description || "")} |`,
-            );
-        }
-    }
-    lines.push("");
-}
-
-function formatParamSchema(schema) {
-    if (!schema) return "string";
-    if (schema.enum) return `${schema.type} (\`${schema.enum.join("\\|")}\`)`;
-    let out = schema.type || "string";
-    if (schema.minimum !== undefined || schema.maximum !== undefined) {
-        out += ` (${schema.minimum ?? "-∞"}..${schema.maximum ?? "∞"})`;
-    }
-    return out;
-}
-
-function formatPropSchema(schema) {
-    if (!schema) return "any";
-    if (schema.$ref) {
-        const n = schema.$ref.split("/").pop();
-        return `[\`${n}\`](#${n.toLowerCase()})`;
-    }
-    if (schema.type === "array") {
-        if (schema.items?.$ref) {
-            const n = schema.items.$ref.split("/").pop();
-            return `array of [\`${n}\`](#${n.toLowerCase()})`;
-        }
-        if (schema.items?.type) return `array of ${schema.items.type}`;
-        return "array";
-    }
-    if (schema.enum) return `${schema.type} (\`${schema.enum.join("\\|")}\`)`;
-    if (schema.oneOf) return schema.oneOf.map(formatPropSchema).join(" \\| ");
-    let out = schema.type || "any";
-    if (schema.nullable) out += " \\| null";
-    return out;
-}
-
-function escapeMd(s) {
-    return String(s).replace(/\|/g, "\\|");
-}
-
-// -- Helpers -----------------------------------------------------------------
-
-function readFirmwareVersion() {
-    try {
-        const ini = fs.readFileSync(path.join(repoRoot, "platformio.ini"), "utf8");
-        const m = ini.match(/FIRMWARE_VERSION\s*=\s*"?([^"\n\s]+)"?/);
-        if (m) return m[1];
-    } catch {}
-    return "0.0.0-dev";
-}
-
-function warn(msg) {
-    process.stderr.write(`[gen_api_docs] WARN: ${msg}\n`);
-}
-
-// -- Main --------------------------------------------------------------------
-
-function main() {
-    fs.mkdirSync(outDir, { recursive: true });
-
-    const routes = parseCpp();
-    const types = parseTypes();
-
-    const openapi = buildOpenApi(routes, types);
-    fs.writeFileSync(path.join(outDir, "openapi.json"), `${JSON.stringify(openapi, null, 2)}\n`);
-
-    const markdown = renderMarkdown(openapi);
-    fs.writeFileSync(path.join(outDir, "api-reference.md"), markdown);
-
-    process.stdout.write(
-        `[gen_api_docs] Wrote ${routes.length} routes, ${Object.keys(types).length} types -> ${path.relative(
-            repoRoot,
-            outDir,
-        )}\n`,
-    );
-}
-
-try {
-    main();
-} catch (err) {
-    process.stderr.write(`[gen_api_docs] ${err.stack || err.message}\n`);
-    process.exit(1);
-}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 555f427..57ca141 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -1,352 +1,28 @@
-export interface VersionData {
-    /** Robot model name (e.g. "Botvac D7") */
-    modelName: string;
-    /** Robot serial number */
-    serialNumber: string;
-    /** Robot firmware version, format "Major.Minor.Build" */
-    softwareVersion: string;
-    /** LIDAR firmware version */
-    ldsVersion: string;
-    /** LIDAR serial number */
-    ldsSerial: string;
-    /** Main board hardware version */
-    mainBoardVersion: string;
-}
-
-export interface MotorData {
-    /** Main brush rotation speed in RPM */
-    brushRPM: number;
-    /** Main brush current draw in mA */
-    brushMA: number;
-    /** Vacuum motor speed in RPM */
-    vacuumRPM: number;
-    /** Vacuum motor current draw in mA */
-    vacuumMA: number;
-    /** Left wheel rotation speed in RPM */
-    leftWheelRPM: number;
-    /** Left wheel load percentage */
-    leftWheelLoad: number;
-    /** Left wheel position in millimeters since boot */
-    leftWheelPositionMM: number;
-    /** Left wheel speed in mm/s */
-    leftWheelSpeed: number;
-    /** Right wheel rotation speed in RPM */
-    rightWheelRPM: number;
-    /** Right wheel load percentage */
-    rightWheelLoad: number;
-    /** Right wheel position in millimeters since boot */
-    rightWheelPositionMM: number;
-    /** Right wheel speed in mm/s */
-    rightWheelSpeed: number;
-    /** Side brush current draw in mA */
-    sideBrushMA: number;
-    /** Laser turret rotation speed in RPM */
-    laserRPM: number;
-}
-
-export interface StateData {
-    /** UI state machine value, e.g. "UIMGR_STATE_STANDBY" */
-    uiState: string;
-    /** Robot state machine value, e.g. "ST_C_Standby" */
-    robotState: string;
-}
-
-export interface ChargerData {
-    /** Battery charge percentage (0-100, -1 = unknown) */
-    fuelPercent: number;
-    /** Battery temperature exceeds safe limits */
-    batteryOverTemp: boolean;
-    /** Charger currently delivering current */
-    chargingActive: boolean;
-    /** Charging circuit enabled (independent of active flow) */
-    chargingEnabled: boolean;
-    /** Fuel gauge reading is trusted */
-    confidOnFuel: boolean;
-    /** Battery has dropped into reserve range */
-    onReservedFuel: boolean;
-    /** Battery considered empty (robot will not start) */
-    emptyFuel: boolean;
-    /** Battery hardware fault detected */
-    batteryFailure: boolean;
-    /** External power supply (dock or barrel jack) connected */
-    extPwrPresent: boolean;
-    /** Battery voltage in volts */
-    vBattV: number;
-    /** External supply voltage in volts */
-    vExtV: number;
-    /** Cumulative mAh delivered into the battery */
-    chargerMAH: number;
-    /** Cumulative mAh discharged from the battery */
-    dischargeMAH: number;
-}
-
-export interface ErrorData {
-    /** True if the robot is currently reporting an error or warning */
-    hasError: boolean;
-    /** "error" for codes 243+, "warning" for codes 201-242 */
-    kind: "error" | "warning";
-    /** Numeric error/warning code (200 = no error) */
-    errorCode: number;
-    /** Full raw response from the robot (for diagnostics) */
-    errorMessage: string;
-    /** Human-readable message suitable for UI and notifications */
-    displayMessage: string;
-}
-
-export interface SystemData {
-    /** Free heap memory in bytes */
-    heap: number;
-    /** Total heap memory in bytes */
-    heapTotal: number;
-    /** Milliseconds since boot */
-    uptime: number;
-    /** WiFi signal strength in dBm (negative, closer to 0 = stronger) */
-    rssi: number;
-    /** SPIFFS bytes used */
-    fsUsed: number;
-    /** SPIFFS total capacity in bytes */
-    fsTotal: number;
-    /** NTP has successfully synced at least once */
-    ntpSynced: boolean;
-    /** Current Unix epoch time in seconds (UTC) */
-    time: number;
-    /** Time source: "ntp", "robot", or "boot" */
-    timeSource: string;
-    /** Configured IANA timezone (e.g. "America/New_York") */
-    tz: string;
-    /** DST-aware local time, e.g. "Sat 17:45:01" */
-    localTime: string;
-    /** True when daylight saving time is active */
-    isDst: boolean;
-}
-
-// Per-day schedule fields (Mon=0..Sun=6), two slots per day.
-// Slot 0 (primary):   sched{0-6}Hour, sched{0-6}Min, sched{0-6}On
-// Slot 1 (secondary): sched{0-6}Slot1Hour, sched{0-6}Slot1Min, sched{0-6}Slot1On
-export interface SettingsData {
-    /** IANA timezone identifier (e.g. "America/New_York") */
-    tz: string;
-    /** 0=off, 1=info, 2=debug */
-    logLevel: number;
-    /** When on, logs go to UDP syslog instead of flash */
-    syslogEnabled: boolean;
-    /** IPv4 address of syslog receiver */
-    syslogIp: string;
-    /** WiFi TX power in 0.25 dBm units (e.g. 34 = 8.5 dBm) */
-    wifiTxPower: number;
-    /** GPIO pin used for UART TX to the robot */
-    uartTxPin: number;
-    /** GPIO pin used for UART RX from the robot */
-    uartRxPin: number;
-    /** Read-only - max valid GPIO for this chip (21 for C3, 39 for ESP32) */
-    maxGpioPin: number;
-    /** mDNS hostname (e.g. "openneato") */
-    hostname: string;
-    /** Navigation mode for house cleaning: "Normal", "Gentle", "Deep", "Quick" */
-    navMode: string;
-    /** Wheel load % for stall detection (30-80) */
-    stallThreshold: number;
-    /** Main brush RPM (500-1600) */
-    brushRpm: number;
-    /** Vacuum speed % (40-100) */
-    vacuumSpeed: number;
-    /** Side brush power in mW (500-1500) */
-    sideBrushPower: number;
-    /** ntfy.sh topic for push notifications (empty = disabled) */
-    ntfyTopic: string;
-    /** Global switch - must be on for any notification to fire */
-    ntfyEnabled: boolean;
-    /** Notify when cleaning completes */
-    ntfyOnDone: boolean;
-    /** Notify on robot error (UI_ERROR_*, code 243+) */
-    ntfyOnError: boolean;
-    /** Notify on robot alert (UI_ALERT_*, code 201-242) */
-    ntfyOnAlert: boolean;
-    /** Notify when robot returns to base */
-    ntfyOnDocking: boolean;
-    /** Master switch for the weekly cleaning schedule */
-    scheduleEnabled: boolean;
-    // Slot 0 (primary)
-    sched0Hour: number;
-    sched0Min: number;
-    sched0On: boolean;
-    sched1Hour: number;
-    sched1Min: number;
-    sched1On: boolean;
-    sched2Hour: number;
-    sched2Min: number;
-    sched2On: boolean;
-    sched3Hour: number;
-    sched3Min: number;
-    sched3On: boolean;
-    sched4Hour: number;
-    sched4Min: number;
-    sched4On: boolean;
-    sched5Hour: number;
-    sched5Min: number;
-    sched5On: boolean;
-    sched6Hour: number;
-    sched6Min: number;
-    sched6On: boolean;
-    // Slot 1 (secondary)
-    sched0Slot1Hour: number;
-    sched0Slot1Min: number;
-    sched0Slot1On: boolean;
-    sched1Slot1Hour: number;
-    sched1Slot1Min: number;
-    sched1Slot1On: boolean;
-    sched2Slot1Hour: number;
-    sched2Slot1Min: number;
-    sched2Slot1On: boolean;
-    sched3Slot1Hour: number;
-    sched3Slot1Min: number;
-    sched3Slot1On: boolean;
-    sched4Slot1Hour: number;
-    sched4Slot1Min: number;
-    sched4Slot1On: boolean;
-    sched5Slot1Hour: number;
-    sched5Slot1Min: number;
-    sched5Slot1On: boolean;
-    sched6Slot1Hour: number;
-    sched6Slot1Min: number;
-    sched6Slot1On: boolean;
-}
-
-export interface UserSettingsData {
-    /** Play a click sound on button presses */
-    buttonClick: boolean;
-    /** Play melodies (start, finish, etc.) */
-    melodies: boolean;
-    /** Play warning chimes */
-    warnings: boolean;
-    /** Reduced power cleaning (longer runtime, lower suction) */
-    ecoMode: boolean;
-    /** Maximum power cleaning */
-    intenseClean: boolean;
-    /** Stop and warn when dirt bin is full */
-    binFullDetect: boolean;
-    /** Enable wall following along walls and edges */
-    wallEnable: boolean;
-    /** Robot WiFi radio enabled (separate from bridge WiFi) */
-    wifi: boolean;
-    /** Dim status LEDs at night */
-    stealthLed: boolean;
-    /** Filter change reminder interval in seconds */
-    filterChange: number;
-    /** Brush change reminder interval in seconds */
-    brushChange: number;
-    /** Dirt bin reminder interval in minutes */
-    dirtBin: number;
-}
-
-export interface LidarPoint {
-    /** Bearing in degrees (0-359, 0 = robot front) */
-    angle: number;
-    /** Distance to target in millimeters (0 if invalid) */
-    dist: number;
-    /** Return signal strength (0-255) */
-    intensity: number;
-    /** Per-point error code (0 = valid) */
-    error: number;
-}
-
-export interface LidarScan {
-    /** LIDAR turret rotation speed in Hz */
-    rotationSpeed: number;
-    /** Count of points with error == 0 */
-    validPoints: number;
-    /** Always 360 entries indexed by angle */
-    points: LidarPoint[];
-}
-
-export interface FirmwareVersion {
-    /** Bridge firmware semantic version */
-    version: string;
-    /** ESP32 chip model (e.g. "ESP32-C3") */
-    chip: string;
-    /** Robot model name (e.g. "Botvac D7", empty until identified) */
-    model: string;
-    /** mDNS hostname (e.g. "openneato") */
-    hostname: string;
-    /** True if the connected robot model is officially supported */
-    supported: boolean;
-    /** True while the bridge is still probing the robot model */
-    identifying: boolean;
-}
-
-export interface ManualStatus {
-    /** Manual mode currently engaged */
-    active: boolean;
-    /** Main brush motor enabled */
-    brush: boolean;
-    /** Vacuum motor enabled */
-    vacuum: boolean;
-    /** Side brush motor enabled */
-    sideBrush: boolean;
-    /** Robot wheel-drop sensor reports the robot is off the ground */
-    lifted: boolean;
-    /** Front-left bumper contacted */
-    bumperFrontLeft: boolean;
-    /** Front-right bumper contacted */
-    bumperFrontRight: boolean;
-    /** Left side bumper contacted */
-    bumperSideLeft: boolean;
-    /** Right side bumper contacted */
-    bumperSideRight: boolean;
-    /** Front wheel stall detected */
-    stallFront: boolean;
-    /** Rear wheel stall detected */
-    stallRear: boolean;
-}
-
-export interface LogFileInfo {
-    /** File name as stored on flash (may include .hs compression suffix) */
-    name: string;
-    /** File size in bytes */
-    size: number;
-    /** True if stored with heatshrink compression */
-    compressed: boolean;
-}
-
-export interface MapSession {
-    /** Always "session" - identifies the record type */
-    type: "session";
-    /** Cleaning mode: "House", "Spot", or "Manual" */
-    mode: string;
-    /** Unix epoch seconds when the session started */
-    time: number;
-    /** Battery percentage at session start */
-    battery: number;
-}
-
-export interface MapSummary {
-    /** Always "summary" - identifies the record type */
-    type: "summary";
-    /** Unix epoch seconds when the session ended */
-    time: number;
-    /** Session duration in seconds */
-    duration: number;
-    /** Cleaning mode: "House", "Spot", or "Manual" */
-    mode: string;
-    /** Number of times the robot returned to base to recharge */
-    recharges: number;
-    /** Number of pose snapshots captured */
-    snapshots: number;
-    /** Total distance traveled in meters */
-    distanceTraveled: number;
-    /** Maximum distance from origin in meters */
-    maxDistFromOrigin: number;
-    /** Total rotation in degrees */
-    totalRotation: number;
-    /** Estimated area covered in square meters */
-    areaCovered: number;
-    /** Number of errors encountered during cleaning */
-    errorsDuringClean: number;
-    /** Battery percentage at session start */
-    batteryStart?: number;
-    /** Battery percentage at session end */
-    batteryEnd?: number;
-}
+// HTTP API types are generated from frontend/api/openapi.yaml. Edit the spec,
+// not this file. The build pipeline runs `openapi-typescript` to refresh
+// types.generated.ts before tsc.
+export type {
+    ChargerData,
+    ErrorData,
+    FirmwareVersion,
+    HistoryFileInfo,
+    LidarPoint,
+    LidarScan,
+    LogFileInfo,
+    ManualStatus,
+    MapSession,
+    MapSummary,
+    MotorData,
+    SettingsData,
+    StateData,
+    SystemData,
+    UserSettingsData,
+    VersionData,
+} from "./types.generated";
+
+// -- Frontend-only types (not part of the HTTP API) --------------------------
+// These describe shapes used internally by the map view and aren't exchanged
+// over the wire.
 
 export interface MapPathPoint {
     x: number;
@@ -386,26 +62,11 @@ export interface MapTransform {
 }
 
 export interface MapData {
-    session: MapSession | null;
-    summary: MapSummary | null;
+    session: import("./types.generated").MapSession | null;
+    summary: import("./types.generated").MapSummary | null;
     path: MapPathPoint[];
     coverage: MapCoverageCell[];
     recharges: MapRechargePoint[];
     bounds: MapBounds | null;
     cellSize: number;
 }
-
-export interface HistoryFileInfo {
-    /** File name as stored on flash (may include .hs compression suffix) */
-    name: string;
-    /** File size in bytes */
-    size: number;
-    /** True if stored with heatshrink compression */
-    compressed: boolean;
-    /** True if this session is currently being recorded */
-    recording: boolean;
-    /** Session metadata, or null if not yet written */
-    session: MapSession | null;
-    /** Session summary, or null if cleaning has not finished */
-    summary: MapSummary | null;
-}

From be2790f4d51b8ba35b81beb43e536e77b088d255 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <soner.koksal@relexsolutions.com>
Date: Mon, 27 Apr 2026 09:31:40 +0300
Subject: [PATCH 09/44] ci: allow legacy peer deps for openapi-typescript on
 TS6

---
 frontend/.npmrc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 frontend/.npmrc

diff --git a/frontend/.npmrc b/frontend/.npmrc
new file mode 100644
index 0000000..521a9f7
--- /dev/null
+++ b/frontend/.npmrc
@@ -0,0 +1 @@
+legacy-peer-deps=true

From 1356b144bd167aaa8166a1b7f50a1cdf5eb22dd9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Tue, 28 Apr 2026 00:13:58 +0300
Subject: [PATCH 10/44] feat: fallback WiFi access point for browser-based
 provisioning (#110)

---
 AGENTS.md                                     |   3 +
 docs/user-guide.md                            |  54 +++-
 firmware/src/config.h                         |  12 +
 firmware/src/main.cpp                         |  69 +++--
 firmware/src/settings_manager.cpp             |  15 +
 firmware/src/settings_manager.h               |  11 +
 firmware/src/web_server.cpp                   |  26 +-
 firmware/src/web_server.h                     |   5 +-
 firmware/src/wifi_manager.cpp                 | 247 +++++++++++++++-
 firmware/src/wifi_manager.h                   |  79 ++++-
 frontend/api/openapi.yaml                     | 138 +++++++++
 frontend/mock/server.js                       |  82 ++++++
 frontend/src/api.ts                           |   8 +
 frontend/src/assets/icons/globe.svg           |   5 +
 frontend/src/components/confirm-dialog.tsx    |  54 +++-
 frontend/src/style.css                        | 235 +++++++--------
 frontend/src/types.ts                         |   5 +-
 frontend/src/views/settings.tsx               |  22 +-
 frontend/src/views/settings/constants.ts      |   1 +
 .../src/views/settings/settings-category.tsx  |  23 +-
 .../src/views/settings/use-settings-form.ts   |   8 +
 frontend/src/views/settings/wifi-section.tsx  | 278 ++++++++++++++++++
 22 files changed, 1204 insertions(+), 176 deletions(-)
 create mode 100644 frontend/src/assets/icons/globe.svg
 create mode 100644 frontend/src/views/settings/wifi-section.tsx

diff --git a/AGENTS.md b/AGENTS.md
index 5eee504..e0ba1dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,6 +118,9 @@ CSS frameworks, routing, or HTTP wrapper libraries.
 
 - 4-space indent, double quotes, semicolons, 120-col (Biome)
 - Named `interface`/`type` only, never inline object type literals
+- Reuse existing CSS utilities and component classes before adding new ones.
+  When two rules share a body, consolidate via a shared selector list, a
+  shared class, or a CSS custom property.
 
 ## Hardware
 
diff --git a/docs/user-guide.md b/docs/user-guide.md
index c221939..374e0d7 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -15,10 +15,12 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
     - [Command Reference](#command-reference)
     - [Troubleshooting Flash Issues](#troubleshooting-flash-issues)
 - [First-Time WiFi Setup](#first-time-wifi-setup)
-    - [Serial Monitor](#serial-monitor)
+    - [Option A: Fallback Access Point (no serial cable)](#option-a-fallback-access-point-no-serial-cable)
+    - [Option B: Serial Monitor](#option-b-serial-monitor)
     - [WiFi Configuration Menu](#wifi-configuration-menu)
     - [Verifying the Connection](#verifying-the-connection)
     - [Quick Commands](#quick-commands)
+    - [Reconfiguring WiFi Later](#reconfiguring-wifi-later)
 - [Troubleshooting](#troubleshooting)
     - [Enabling Logging](#enabling-logging)
     - [Collecting Logs](#collecting-logs)
@@ -232,23 +234,48 @@ Windows, close any other serial monitor that might have the port open.
 
 ## First-Time WiFi Setup
 
-After flashing, the tool opens a serial monitor where you'll configure WiFi.
+After flashing, the device has no saved WiFi credentials and won't be on your network yet.
+You have two ways to provision it: a browser via the fallback access point (no serial cable
+needed), or the serial menu that the flash tool opens for you.
 
-### Serial Monitor
+### Option A: Fallback Access Point (no serial cable)
+
+When the device has no saved credentials, it broadcasts an open WiFi network so you can
+configure it from any phone or laptop browser. This works even after you've unplugged the
+USB cable and tucked the ESP32 inside the robot.
+
+1. From your phone or laptop, connect to the WiFi network named **`neato-ap`** (or
+   `<hostname>-ap` if you've changed the hostname). It's an open network , no password.
+2. Open a browser and go to `http://192.168.4.1`. You'll land on the OpenNeato dashboard.
+3. Open **Settings -> WiFi**, tap **Scan**, pick your home network from the dropdown, and
+   enter the password.
+4. After confirming, the device joins your home network and reboots. The `neato-ap` network
+   disappears at that point , reconnect your phone/laptop to your home WiFi to keep using
+   the web UI at `http://neato.local` (or the IP shown on the dashboard).
+
+> [!NOTE]
+> The fallback AP is unencrypted because there's no way to display a password to a user
+> who hasn't set one up yet. It only runs while the device has no saved credentials or
+> cannot reach your home network. Once connected, it shuts down automatically.
+
+### Option B: Serial Monitor
 
 The serial monitor connects at 115,200 baud and shows the ESP32's boot output. You'll see
-the boot banner:
+the boot banner. With no credentials saved, the fallback AP comes up automatically and the
+banner reflects that:
 
 ```
 ========================================
   OpenNeato v0.1
 ========================================
-  WiFi: not configured
+  WiFi: AP mode, connect to neato-ap and open http://192.168.4.1
   Press 'm' for menu, 's' for status
 ========================================
 ```
 
-If WiFi is not configured, the configuration menu appears automatically.
+You can finish provisioning either by joining `neato-ap` from a browser (Option A above) or
+by pressing `m` to open the WiFi configuration menu over serial , both end up in the same
+place.
 
 ### WiFi Configuration Menu
 
@@ -309,6 +336,21 @@ Once connected, you can type single-key commands in the serial monitor at any ti
 | `m` | Open WiFi configuration menu            |
 | `s` | Print WiFi status (SSID, IP, MAC, RSSI) |
 
+### Reconfiguring WiFi Later
+
+Once the device is on your home network you can change networks from the web UI directly:
+**Settings -> WiFi -> Scan**, pick a new network, enter the password.
+
+If your home network goes down or you've moved house, the bridge falls back to the
+`<hostname>-ap` access point automatically so you can re-provision it from a browser without
+opening up the robot. This behavior is controlled by the **Fallback AP on disconnect** toggle
+in the WiFi section , it's on by default. If you turn it off, recovery from a broken WiFi
+config requires the serial menu.
+
+To wipe credentials entirely and force the device back into first-time setup mode (always-on
+AP, no auto-reconnect), use **Settings -> WiFi -> Forget current network**. The device will
+broadcast `<hostname>-ap` until you provision a new network.
+
 ---
 
 ## Troubleshooting
diff --git a/firmware/src/config.h b/firmware/src/config.h
index a9f2637..365fbbf 100644
--- a/firmware/src/config.h
+++ b/firmware/src/config.h
@@ -110,6 +110,18 @@ enum CommandStatus {
 // NVS keys — WiFi
 #define NVS_KEY_WIFI_SSID "wifi_ssid"
 #define NVS_KEY_WIFI_PASS "wifi_pass"
+#define NVS_KEY_AP_FALLBACK "ap_fallback"
+
+// Fallback Access Point (provisioning AP)
+// SSID is derived from hostname: "<hostname>-ap". Network is open (no password).
+// AP is automatic: always on when no STA credentials saved; on/off based on
+// apFallbackOnDisconnect setting when STA connection drops.
+#define AP_SSID_SUFFIX "-ap"
+#define AP_DEFAULT_IP IPAddress(192, 168, 4, 1)
+#define AP_GATEWAY IPAddress(192, 168, 4, 1)
+#define AP_SUBNET IPAddress(255, 255, 255, 0)
+#define AP_CHANNEL 1
+#define AP_MAX_CONNECTIONS 4
 
 // NVS keys — Time/NTP
 #define NVS_KEY_TIMEZONE "tz"
diff --git a/firmware/src/main.cpp b/firmware/src/main.cpp
index 5d8e0dc..cc80dc8 100644
--- a/firmware/src/main.cpp
+++ b/firmware/src/main.cpp
@@ -30,7 +30,7 @@ ManualCleanManager manualClean(neatoSerial);
 NotificationManager notifMgr(neatoSerial, settingsManager, dataLogger);
 CleaningHistory cleaningHistory(neatoSerial, dataLogger, systemManager);
 WebServer webServer(server, neatoSerial, dataLogger, systemManager, firmwareManager, settingsManager, manualClean,
-                    notifMgr, cleaningHistory);
+                    notifMgr, cleaningHistory, wifiManager);
 
 // Tracks whether web server has been started (may be deferred if WiFi was slow at boot)
 bool webServerStarted = false;
@@ -54,8 +54,12 @@ void setup() {
     settingsManager.onTzChange([&](const String& tz) { systemManager.applyTimezone(tz); });
     settingsManager.onTxPowerChange([&](int quarterDbm) { wifiManager.setTxPower(quarterDbm); });
     settingsManager.onRebootRequired([&] { systemManager.restart(); });
+    settingsManager.onApFallbackChange([&](bool enabled) { wifiManager.setApFallbackOnDisconnect(enabled); });
     settingsManager.begin();
 
+    // Push initial AP fallback policy into WiFiManager before begin()
+    wifiManager.setApFallbackOnDisconnect(settingsManager.get().apFallbackOnDisconnect);
+
     // Apply manual clean settings from NVS (stall threshold, motor speeds)
     const auto& s = settingsManager.get();
     manualClean.setStallThreshold(s.stallThreshold);
@@ -115,19 +119,24 @@ void setup() {
         dataLogger.logNtp("sync_ok", {{"epoch", String(static_cast<long>(t)), FIELD_INT}});
     });
 
-    // Initialize web server and OTA if WiFi is already connected.
-    // If WiFi is slow (e.g. DHCP timeout after OTA), the web server will be
-    // started later in loop() once WiFi comes up — see deferred start below.
-    if (wifiManager.isConnected()) {
+    // Initialize web server and OTA if any network interface is up , STA
+    // (normal operation) or fallback AP (provisioning). Without either, the
+    // server has no socket to bind to. The deferred path in loop() picks up
+    // any late-arriving STA association.
+    if (wifiManager.isConnected() || wifiManager.isApActive()) {
         LOG("BOOT", "Initializing web server...");
         webServer.begin();
         LOG("BOOT", "Starting HTTP server...");
         server.begin();
         webServerStarted = true;
 
-        // Mark firmware as valid — cancels auto-rollback on next reboot
-        esp_ota_mark_app_valid_cancel_rollback();
-        LOG("BOOT", "Firmware marked valid");
+        // Mark firmware as valid , cancels auto-rollback on next reboot.
+        // Only cancel rollback once we have STA connectivity, otherwise an OTA
+        // image that broke STA but kept AP working would still be marked valid.
+        if (wifiManager.isConnected()) {
+            esp_ota_mark_app_valid_cancel_rollback();
+            LOG("BOOT", "Firmware marked valid");
+        }
     } else {
         LOG("BOOT", "WiFi not ready — web server will start when connected");
     }
@@ -161,14 +170,21 @@ void setup() {
 
     LOG("BOOT", "System initialization complete");
 
-    // User-facing boot banner (visible in serial monitor / flash tool)
-    if (wifiManager.isConnected()) {
-        SerialMenu::printBanner("OpenNeato", FIRMWARE_VERSION,
-                                "WiFi: " + WiFi.SSID() + " (" + WiFi.localIP().toString() + ")",
-                                "Press 'm' for menu, 's' for status");
-    } else {
-        SerialMenu::printBanner("OpenNeato", FIRMWARE_VERSION, "WiFi: not configured");
-    }
+    // User-facing boot banner (visible in serial monitor / flash tool).
+    // Build the status line from the current WiFi state, then call
+    // printBanner once (a single call avoids bugprone-branch-clone warnings
+    // from clang-tidy for chained conditionals that all end the same way).
+    auto bannerStatus = [&]() -> String {
+        if (wifiManager.isConnected())
+            return "WiFi: " + WiFi.SSID() + " (" + WiFi.localIP().toString() + ")";
+        if (wifiManager.isApActive())
+            return "WiFi: AP mode, connect to " + (settingsManager.get().hostname + String(AP_SSID_SUFFIX)) +
+                   " and open http://" + WiFi.softAPIP().toString();
+        return "WiFi: not configured";
+    }();
+    String bannerHint =
+            (wifiManager.isConnected() || wifiManager.isApActive()) ? "Press 'm' for menu, 's' for status" : "";
+    SerialMenu::printBanner("OpenNeato", FIRMWARE_VERSION, bannerStatus, bannerHint);
 
     // Show WiFi config menu if needed
     if (!wifiManager.isConnected()) {
@@ -189,17 +205,20 @@ void loop() {
     // WiFi auto-reconnect with exponential backoff
     wifiManager.loop();
 
-    // Deferred web server start — if WiFi was slow at boot (e.g. DHCP timeout
-    // after OTA), start the web server once WiFi eventually connects.
-    if (!webServerStarted && wifiManager.isConnected()) {
-        LOG("MAIN", "WiFi connected late — starting web server now");
+    // Deferred web server start , if WiFi was slow at boot (e.g. DHCP timeout
+    // after OTA), start the web server once WiFi eventually connects, or once
+    // the fallback AP comes up so the user can reconfigure WiFi from a browser.
+    if (!webServerStarted && (wifiManager.isConnected() || wifiManager.isApActive())) {
+        LOG("MAIN", "WiFi available late , starting web server now");
         dataLogger.logWifi("deferred_start");
         webServer.begin();
         server.begin();
         webServerStarted = true;
 
-        esp_ota_mark_app_valid_cancel_rollback();
-        LOG("MAIN", "Firmware marked valid (deferred)");
+        if (wifiManager.isConnected()) {
+            esp_ota_mark_app_valid_cancel_rollback();
+            LOG("MAIN", "Firmware marked valid (deferred)");
+        }
     }
 
     // Check for button press (runtime reset)
@@ -227,8 +246,10 @@ void loop() {
         }
     }
 
-    // Firmware update handling (only if connected)
-    if (wifiManager.isConnected()) {
+    // Firmware update handling , runs while either STA or fallback AP is up so
+    // the user can recover from a broken STA config by uploading firmware over
+    // the AP.
+    if (wifiManager.isConnected() || wifiManager.isApActive()) {
         firmwareManager.loop();
 
         // Skip other operations during firmware update
diff --git a/firmware/src/settings_manager.cpp b/firmware/src/settings_manager.cpp
index 1c879a1..832c045 100644
--- a/firmware/src/settings_manager.cpp
+++ b/firmware/src/settings_manager.cpp
@@ -63,6 +63,7 @@ void SettingsManager::load() {
     current.brushRpm = prefs.getInt(NVS_KEY_MC_BRUSH_RPM, MANUAL_BRUSH_RPM);
     current.vacuumSpeed = prefs.getInt(NVS_KEY_MC_VACUUM_PCT, MANUAL_VACUUM_SPEED_PCT);
     current.sideBrushPower = prefs.getInt(NVS_KEY_MC_SBRUSH_MW, MANUAL_SIDE_BRUSH_POWER_MW);
+    current.apFallbackOnDisconnect = prefs.getBool(NVS_KEY_AP_FALLBACK, true);
     current.syslogEnabled = prefs.getBool(NVS_KEY_SYSLOG_ENABLED, false);
     current.syslogIp = prefs.getString(NVS_KEY_SYSLOG_IP, "");
     current.ntfyTopic = prefs.getString(NVS_KEY_NTFY_TOPIC, "");
@@ -93,6 +94,7 @@ void SettingsManager::save() {
     prefs.putInt(NVS_KEY_MC_BRUSH_RPM, current.brushRpm);
     prefs.putInt(NVS_KEY_MC_VACUUM_PCT, current.vacuumSpeed);
     prefs.putInt(NVS_KEY_MC_SBRUSH_MW, current.sideBrushPower);
+    prefs.putBool(NVS_KEY_AP_FALLBACK, current.apFallbackOnDisconnect);
     prefs.putBool(NVS_KEY_SYSLOG_ENABLED, current.syslogEnabled);
     prefs.putString(NVS_KEY_SYSLOG_IP, current.syslogIp);
     prefs.putString(NVS_KEY_NTFY_TOPIC, current.ntfyTopic);
@@ -250,6 +252,14 @@ ApplyResult SettingsManager::apply(const String& json) {
         LOG("SETTINGS", "Side brush power -> %d mW", current.sideBrushPower);
     }
 
+    if (incoming.apFallbackOnDisconnect != current.apFallbackOnDisconnect) {
+        current.apFallbackOnDisconnect = incoming.apFallbackOnDisconnect;
+        changed = true;
+        if (apFallbackChangeCb)
+            apFallbackChangeCb(current.apFallbackOnDisconnect);
+        LOG("SETTINGS", "AP fallback -> %s", current.apFallbackOnDisconnect ? "on" : "off");
+    }
+
     if (incoming.syslogEnabled != current.syslogEnabled) {
         current.syslogEnabled = incoming.syslogEnabled;
         changed = true;
@@ -343,6 +353,7 @@ std::vector<Field> Settings::toFields() const {
             {"brushRpm", String(brushRpm), FIELD_INT},
             {"vacuumSpeed", String(vacuumSpeed), FIELD_INT},
             {"sideBrushPower", String(sideBrushPower), FIELD_INT},
+            {"apFallbackOnDisconnect", apFallbackOnDisconnect ? "true" : "false", FIELD_BOOL},
             {"syslogEnabled", syslogEnabled ? "true" : "false", FIELD_BOOL},
             {"syslogIp", syslogIp, FIELD_STRING},
             {"ntfyTopic", ntfyTopic, FIELD_STRING},
@@ -416,6 +427,10 @@ bool Settings::fromFields(const std::vector<Field>& fields) {
         sideBrushPower = f->value.toInt();
         applied = true;
     }
+    if ((f = findField(fields, "apFallbackOnDisconnect")) && f->type == FIELD_BOOL) {
+        apFallbackOnDisconnect = (f->value == "true");
+        applied = true;
+    }
     if ((f = findField(fields, "syslogEnabled")) && f->type == FIELD_BOOL) {
         syslogEnabled = (f->value == "true");
         applied = true;
diff --git a/firmware/src/settings_manager.h b/firmware/src/settings_manager.h
index 54d3ff8..45338a1 100644
--- a/firmware/src/settings_manager.h
+++ b/firmware/src/settings_manager.h
@@ -35,6 +35,11 @@ struct Settings : public JsonSerializable {
     int vacuumSpeed = MANUAL_VACUUM_SPEED_PCT; // Vacuum speed % (40-100)
     int sideBrushPower = MANUAL_SIDE_BRUSH_POWER_MW; // Side brush power in mW (500-1500)
 
+    // Fallback Access Point , when STA connection is lost, expose an AP for
+    // browser-based reconfiguration. Always on when no STA credentials are
+    // saved; controlled by this flag once credentials exist.
+    bool apFallbackOnDisconnect = true;
+
     // Remote syslog (UDP) — when enabled, logs go to network instead of flash
     bool syslogEnabled = false;
     String syslogIp; // IPv4 address of syslog receiver
@@ -81,12 +86,18 @@ class SettingsManager {
     using RebootCallback = std::function<void()>;
     void onRebootRequired(RebootCallback cb) { rebootCb = cb; }
 
+    // Callback fired when AP fallback policy changes (so WiFiManager can
+    // re-evaluate whether the AP should be active right now).
+    using ApFallbackChangeCallback = std::function<void(bool enabled)>;
+    void onApFallbackChange(ApFallbackChangeCallback cb) { apFallbackChangeCb = cb; }
+
 private:
     Preferences& prefs;
     Settings current;
     TzChangeCallback tzChangeCb;
     TxPowerChangeCallback txPowerChangeCb;
     RebootCallback rebootCb;
+    ApFallbackChangeCallback apFallbackChangeCb;
     unsigned long logLevelEnabledAt = 0; // millis() when log level was changed from off (0 = off/never)
 
     void load();
diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index 19d07c0..17411e6 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -8,15 +8,16 @@
 #include "manual_clean_manager.h"
 #include "notification_manager.h"
 #include "cleaning_history.h"
+#include "wifi_manager.h"
 #include <SPIFFS.h>
 
 unsigned long WebServer::lastApiActivity = 0;
 
 WebServer::WebServer(AsyncWebServer& server, NeatoSerial& neato, DataLogger& logger, SystemManager& sys,
                      FirmwareManager& fw, SettingsManager& settings, ManualCleanManager& manual,
-                     NotificationManager& notif, CleaningHistory& history) :
+                     NotificationManager& notif, CleaningHistory& history, WiFiManager& wifi) :
     server(server), neato(neato), logger(logger), sysMgr(sys), fwMgr(fw), settingsMgr(settings), manualMgr(manual),
-    notifMgr(notif), historyMgr(history) {}
+    notifMgr(notif), historyMgr(history), wifiMgr(wifi) {}
 
 void WebServer::loggedRoute(const char *path, WebRequestMethodComposite httpMethod, SyncHandler handler) {
     server.on(path, httpMethod, [this, handler](AsyncWebServerRequest *request) {
@@ -71,6 +72,7 @@ void WebServer::begin() {
     registerSettingsRoutes();
     registerFirmwareRoutes();
     registerMapRoutes();
+    registerWiFiRoutes();
 
     LOG("WEB", "Frontend and API routes registered");
 }
@@ -505,3 +507,23 @@ void WebServer::registerMapRoutes() {
 
     LOG("WEB", "History routes registered");
 }
+
+// -- WiFi management endpoints -----------------------------------------------
+
+void WebServer::registerWiFiRoutes() {
+    // GET /api/wifi/status , STA + fallback AP snapshot
+    registerGetRoute("/api/wifi/status", wifiMgr, &WiFiManager::getStatus, {});
+
+    // GET /api/wifi/scan , list nearby networks
+    registerGetRoute("/api/wifi/scan", wifiMgr, &WiFiManager::scanNetworks, {});
+
+    // POST /api/wifi/connect?ssid=&password= , save credentials and connect.
+    // On success the device reboots into normal STA mode; on failure the
+    // fallback AP stays up so the user can retry.
+    registerPostRoute("/api/wifi/connect", wifiMgr, &WiFiManager::connect, {"ssid", "password"});
+
+    // POST /api/wifi/disconnect , clear credentials and drop the connection
+    registerPostRoute("/api/wifi/disconnect", wifiMgr, &WiFiManager::disconnect, {});
+
+    LOG("WEB", "WiFi routes registered");
+}
diff --git a/firmware/src/web_server.h b/firmware/src/web_server.h
index e999f2c..db864ab 100644
--- a/firmware/src/web_server.h
+++ b/firmware/src/web_server.h
@@ -17,12 +17,13 @@ class SettingsManager;
 class ManualCleanManager;
 class NotificationManager;
 class CleaningHistory;
+class WiFiManager;
 
 class WebServer {
 public:
     WebServer(AsyncWebServer& server, NeatoSerial& neato, DataLogger& logger, SystemManager& sys, FirmwareManager& fw,
               SettingsManager& settings, ManualCleanManager& manual, NotificationManager& notif,
-              CleaningHistory& history);
+              CleaningHistory& history, WiFiManager& wifi);
     void begin();
 
     // Last time any API request was received (millis()). Any module can check
@@ -39,6 +40,7 @@ class WebServer {
     ManualCleanManager& manualMgr;
     NotificationManager& notifMgr;
     CleaningHistory& historyMgr;
+    WiFiManager& wifiMgr;
 
     void registerApiRoutes();
     void registerManualRoutes();
@@ -47,6 +49,7 @@ class WebServer {
     void registerSettingsRoutes();
     void registerFirmwareRoutes();
     void registerMapRoutes();
+    void registerWiFiRoutes();
     static void sendGzipAsset(AsyncWebServerRequest *request, const uint8_t *data, size_t len, const char *contentType);
     static void sendError(AsyncWebServerRequest *request, int code, const String& msg);
     static void sendOk(AsyncWebServerRequest *request);
diff --git a/firmware/src/wifi_manager.cpp b/firmware/src/wifi_manager.cpp
index b8a3e9f..56312ea 100644
--- a/firmware/src/wifi_manager.cpp
+++ b/firmware/src/wifi_manager.cpp
@@ -3,6 +3,44 @@
 #include <esp_task_wdt.h>
 #include <esp_wifi.h>
 
+// -- Helper structs ----------------------------------------------------------
+
+std::vector<Field> WiFiStatus::toFields() const {
+    return {
+            {"staConnected", staConnected ? "true" : "false", FIELD_BOOL},
+            {"ssid", ssid, FIELD_STRING},
+            {"ip", ip, FIELD_STRING},
+            {"rssi", String(rssi), FIELD_INT},
+            {"apActive", apActive ? "true" : "false", FIELD_BOOL},
+            {"apSsid", apSsid, FIELD_STRING},
+            {"apIp", apIp, FIELD_STRING},
+            {"apClients", String(apClients), FIELD_INT},
+            {"apFallbackOnDisconnect", apFallbackOnDisconnect ? "true" : "false", FIELD_BOOL},
+            {"lastError", lastError, FIELD_STRING},
+    };
+}
+
+std::vector<Field> WiFiNetwork::toFields() const {
+    return {
+            {"ssid", ssid, FIELD_STRING},
+            {"rssi", String(rssi), FIELD_INT},
+            {"open", open ? "true" : "false", FIELD_BOOL},
+    };
+}
+
+String WiFiScanResult::toJson() const {
+    String json = "{\"networks\":[";
+    for (size_t i = 0; i < networks.size(); i++) {
+        if (i > 0)
+            json += ",";
+        json += networks[i].toJson();
+    }
+    json += "]}";
+    return json;
+}
+
+// -- WiFiManager -------------------------------------------------------------
+
 WiFiManager::WiFiManager(Preferences& prefs, DataLogger& logger) :
     LoopTask(WIFI_RECONNECT_INTERVAL), prefs(prefs), dataLogger(logger), menu("WiFi Configuration Menu"),
     networkMenu("Available WiFi Networks") {}
@@ -29,6 +67,7 @@ void WiFiManager::begin() {
             return;
         }
         LOG("WIFI", "Failed to connect with saved credentials");
+        lastStaError = wifiStatusReason(WiFi.status());
 
         // Log boot connection failure
         dataLogger.logWifi("boot_connect_fail",
@@ -40,6 +79,9 @@ void WiFiManager::begin() {
     // No credentials or connection failed
     LOG("WIFI", "WiFi not configured!");
     inConfigMode = true;
+
+    // Bring up the fallback AP so users can provision via browser
+    reevaluateFallbackAp();
 }
 
 void WiFiManager::showMenu() {
@@ -48,7 +90,7 @@ void WiFiManager::showMenu() {
 
     // Build menu items
     menu.clearItems();
-    menu.addItem("Scan WiFi networks", "Scan and select from available networks", [this]() { scanNetworks(); });
+    menu.addItem("Scan WiFi networks", "Scan and select from available networks", [this]() { scanNetworksMenu(); });
     menu.addItem("Enter SSID manually", "Type network name manually", [this]() { manualSSID(); });
     menu.addItem("Show current status", "Display WiFi connection status", [this]() { showStatus(); });
     menu.addItem("Reset all settings", "Erase all saved settings and restart", [this]() { resetCredentials(); });
@@ -94,6 +136,10 @@ void WiFiManager::handleSerialInput() {
             if (loadCredentials(ssid, pass)) {
                 menu.printKeyValue("Saved SSID", ssid);
             }
+            if (apActive) {
+                menu.printKeyValue("Fallback AP", apSsidName());
+                menu.printKeyValue("AP IP", WiFi.softAPIP().toString());
+            }
             menu.printSeparator();
             menu.printStatus("Quick commands: [m]enu, [s]tatus");
         } else if (c != '\n' && c != '\r') {
@@ -106,7 +152,7 @@ void WiFiManager::handleSerialInput() {
     }
 }
 
-void WiFiManager::scanNetworks() {
+void WiFiManager::scanNetworksMenu() {
     menu.printStatus("Scanning WiFi networks...");
     scannedNetworkCount = WiFi.scanNetworks();
 
@@ -246,6 +292,12 @@ void WiFiManager::showStatus() {
         menu.printKeyValue("Saved SSID", ssid);
     }
 
+    if (apActive) {
+        menu.printKeyValue("Fallback AP", apSsidName());
+        menu.printKeyValue("AP IP", WiFi.softAPIP().toString());
+        menu.printKeyValue("AP clients", String(WiFi.softAPgetStationNum()));
+    }
+
     menu.printSeparator();
     menu.printStatus(""); // Print newline
 
@@ -273,7 +325,9 @@ bool WiFiManager::connectToWiFi(const String& ssid, const String& password) {
     delay(100);
 
     WiFi.setHostname(hostname.c_str());
-    WiFi.mode(WIFI_STA);
+    // Use AP+STA mode if the fallback AP is currently active so we keep
+    // serving the provisioning page during the connection attempt.
+    WiFi.mode(apActive ? WIFI_AP_STA : WIFI_STA);
     // Enable modem sleep — radio powers down between AP beacons (~100ms),
     // reducing idle current from ~120mA to ~15-20mA. WiFi association stays
     // active; AP buffers frames during sleep. TX power is unaffected.
@@ -300,8 +354,10 @@ bool WiFiManager::connectToWiFi(const String& ssid, const String& password) {
         wasConnected = true;
         reconnectBackoff = WIFI_RECONNECT_INTERVAL;
         reconnectAttemptCount = 0;
+        lastStaError = "";
     } else {
         LOG("WIFI", "Connect failed after %lu ms (%d attempts), status=%d", connectMs, attempts, WiFi.status());
+        lastStaError = wifiStatusReason(WiFi.status());
         // Enable auto-reconnect even if boot connect timed out (e.g. slow DHCP).
         // WiFi may still be associating in the background — let loop() handle
         // reconnection so the deferred web server start can pick it up.
@@ -322,7 +378,16 @@ void WiFiManager::setTxPower(int quarterDbm) {
     LOG("WIFI", "TX power updated to %.1f dBm", quarterDbm * 0.25f);
 }
 
+void WiFiManager::setApFallbackOnDisconnect(bool enabled) {
+    apFallbackOnDisconnect = enabled;
+    reevaluateFallbackAp();
+}
+
 void WiFiManager::tick() {
+    // Re-evaluate the AP regardless of STA state , this also handles the
+    // recovery case where credentials are wiped via the API.
+    reevaluateFallbackAp();
+
     // Only attempt auto-reconnect if we were previously connected and are not
     // in config mode (user is actively setting up WiFi through the serial menu)
     if (inConfigMode || !wasConnected || WiFi.status() == WL_CONNECTED)
@@ -365,11 +430,13 @@ void WiFiManager::tick() {
         reconnectBackoff = WIFI_RECONNECT_INTERVAL; // Reset backoff on success
         setInterval(reconnectBackoff);
         reconnectAttemptCount = 0;
+        lastStaError = "";
     } else {
         // Exponential backoff: 5s -> 10s -> 20s -> 30s (capped)
         reconnectBackoff = min(reconnectBackoff * 2, static_cast<unsigned long>(WIFI_MAX_RECONNECT_BACKOFF));
         setInterval(reconnectBackoff);
         LOG("WIFI", "Reconnect failed (status=%d), next attempt in %lu ms", WiFi.status(), reconnectBackoff);
+        lastStaError = wifiStatusReason(WiFi.status());
 
         dataLogger.logWifi("reconnect_fail", {{"ssid", ssid, FIELD_STRING},
                                               {"status", String(WiFi.status()), FIELD_INT},
@@ -414,6 +481,180 @@ bool WiFiManager::loadCredentials(String& ssid, String& password) {
     return ssid.length() > 0;
 }
 
+bool WiFiManager::hasSavedCredentials() {
+    String ssid, password;
+    return loadCredentials(ssid, password);
+}
+
 bool WiFiManager::isConnected() const {
     return WiFi.status() == WL_CONNECTED;
 }
+
+// -- Fallback AP -------------------------------------------------------------
+
+String WiFiManager::apSsidName() const {
+    return hostname + AP_SSID_SUFFIX;
+}
+
+void WiFiManager::startAccessPoint() {
+    if (apActive)
+        return;
+
+    String ssid = apSsidName();
+    LOG("WIFI", "Starting fallback AP: %s", ssid.c_str());
+
+    // Combined AP+STA so the device can keep trying STA reconnects while the
+    // AP is up. Pure-AP mode would block reconnect attempts entirely.
+    WiFi.mode(WIFI_AP_STA);
+    WiFi.softAPConfig(AP_DEFAULT_IP, AP_GATEWAY, AP_SUBNET);
+    bool ok = WiFi.softAP(ssid.c_str(), nullptr, AP_CHANNEL, /*ssid_hidden=*/0, AP_MAX_CONNECTIONS);
+    if (!ok) {
+        LOG("WIFI", "softAP() failed");
+        dataLogger.logWifi("ap_start_fail", {{"ssid", ssid, FIELD_STRING}});
+        return;
+    }
+
+    apActive = true;
+    LOG("WIFI", "AP active: SSID=%s IP=%s", ssid.c_str(), WiFi.softAPIP().toString().c_str());
+    dataLogger.logWifi("ap_start", {{"ssid", ssid, FIELD_STRING}, {"ip", WiFi.softAPIP().toString(), FIELD_STRING}});
+}
+
+void WiFiManager::stopAccessPoint() {
+    if (!apActive)
+        return;
+
+    LOG("WIFI", "Stopping fallback AP");
+    WiFi.softAPdisconnect(true);
+    // If STA is still wanted, keep STA mode active; otherwise drop to STA-only
+    // so the radio doesn't sit in AP+STA with no AP.
+    WiFi.mode(WIFI_STA);
+    apActive = false;
+    dataLogger.logWifi("ap_stop");
+}
+
+void WiFiManager::reevaluateFallbackAp() {
+    // Three policies, derived from the issue scope:
+    //   1. No saved credentials -> AP always on (only way to provision).
+    //   2. STA connected -> AP off.
+    //   3. Saved credentials but STA disconnected -> AP on iff
+    //      apFallbackOnDisconnect is true.
+    bool credsSaved = hasSavedCredentials();
+    bool staConnected = WiFi.status() == WL_CONNECTED;
+
+    bool wantAp;
+    if (!credsSaved) {
+        wantAp = true;
+    } else if (staConnected) {
+        wantAp = false;
+    } else {
+        wantAp = apFallbackOnDisconnect;
+    }
+
+    if (wantAp && !apActive) {
+        startAccessPoint();
+    } else if (!wantAp && apActive) {
+        stopAccessPoint();
+    }
+}
+
+// -- API surface -------------------------------------------------------------
+
+void WiFiManager::getStatus(std::function<void(bool, const WiFiStatus&)> cb) {
+    WiFiStatus s;
+    s.staConnected = isConnected();
+    if (s.staConnected) {
+        s.ssid = WiFi.SSID();
+        s.ip = WiFi.localIP().toString();
+        s.rssi = WiFi.RSSI();
+    } else {
+        // Fall back to saved SSID so the UI can show "trying to reconnect to X"
+        String savedPass;
+        loadCredentials(s.ssid, savedPass);
+    }
+    s.apActive = apActive;
+    if (apActive) {
+        s.apSsid = apSsidName();
+        s.apIp = WiFi.softAPIP().toString();
+        s.apClients = WiFi.softAPgetStationNum();
+    }
+    s.apFallbackOnDisconnect = apFallbackOnDisconnect;
+    s.lastError = lastStaError;
+    cb(true, s);
+}
+
+void WiFiManager::scanNetworks(std::function<void(bool, const WiFiScanResult&)> cb) {
+    WiFiScanResult result;
+
+    // Use synchronous scan with watchdog feeding so a slow scan doesn't
+    // trigger a TWDT reset. Returns the network count or a negative error.
+    int n = WiFi.scanNetworks(/*async=*/false, /*show_hidden=*/false);
+    esp_task_wdt_reset();
+
+    if (n < 0) {
+        LOG("WIFI", "Scan failed: %d", n);
+        cb(false, result);
+        return;
+    }
+
+    // Cap at 30 entries , anything more than that on an ESP32-C3 is noise
+    // and would just bloat the JSON response.
+    int max = n < 30 ? n : 30;
+    result.networks.reserve(max);
+    for (int i = 0; i < max; ++i) {
+        WiFiNetwork net;
+        net.ssid = WiFi.SSID(i);
+        net.rssi = WiFi.RSSI(i);
+        net.open = WiFi.encryptionType(i) == WIFI_AUTH_OPEN;
+        result.networks.push_back(net);
+    }
+    WiFi.scanDelete();
+
+    cb(true, result);
+}
+
+bool WiFiManager::connect(const String& ssid, const String& password, std::function<void(bool)> cb) {
+    if (ssid.isEmpty()) {
+        cb(false);
+        return true; // Handler ran (returned an error) , don't return 503
+    }
+
+    LOG("WIFI", "API connect request: %s", ssid.c_str());
+    dataLogger.logWifi("api_connect", {{"ssid", ssid, FIELD_STRING}});
+
+    // Save first so a successful connection leads to a normal reboot path
+    // and a failure can be inspected via the AP afterwards.
+    saveCredentials(ssid, password);
+
+    bool ok = connectToWiFi(ssid, password);
+    if (ok) {
+        // Schedule a reboot so the regular boot flow brings up the web server,
+        // mDNS, etc. with the freshly connected STA. Give the response time
+        // to flush first.
+        cb(true);
+        delay(500);
+        ESP.restart();
+        return true;
+    }
+
+    // Connection failed , keep AP up so the user can try again.
+    reevaluateFallbackAp();
+    cb(false);
+    return true;
+}
+
+bool WiFiManager::disconnect(std::function<void(bool)> cb) {
+    LOG("WIFI", "API disconnect request");
+    dataLogger.logWifi("api_disconnect");
+
+    prefs.remove(NVS_KEY_WIFI_SSID);
+    prefs.remove(NVS_KEY_WIFI_PASS);
+    WiFi.disconnect(true, true);
+    wasConnected = false;
+    lastStaError = "";
+
+    // No credentials -> AP must be up regardless of policy
+    reevaluateFallbackAp();
+
+    cb(true);
+    return true;
+}
diff --git a/firmware/src/wifi_manager.h b/firmware/src/wifi_manager.h
index 17de563..f8497fe 100644
--- a/firmware/src/wifi_manager.h
+++ b/firmware/src/wifi_manager.h
@@ -3,12 +3,48 @@
 
 #include <WiFi.h>
 #include <Preferences.h>
+#include <functional>
+#include <vector>
 #include "config.h"
+#include "json_fields.h"
 #include "loop_task.h"
 #include "serial_menu.h"
 
 class DataLogger;
 
+// Status of an STA connection attempt initiated via the API.
+struct WiFiStatus : public JsonSerializable {
+    bool staConnected = false;
+    String ssid;
+    String ip;
+    int rssi = 0;
+    bool apActive = false;
+    String apSsid;
+    String apIp;
+    int apClients = 0;
+    bool apFallbackOnDisconnect = true;
+    String lastError; // Empty when no error; otherwise human-readable failure reason
+
+    std::vector<Field> toFields() const override;
+};
+
+// Single network result from a scan.
+struct WiFiNetwork : public JsonSerializable {
+    String ssid;
+    int rssi = 0;
+    bool open = false;
+
+    std::vector<Field> toFields() const override;
+};
+
+// Scan result list , wraps a vector of networks for JSON serialization.
+struct WiFiScanResult : public JsonSerializable {
+    std::vector<WiFiNetwork> networks;
+
+    std::vector<Field> toFields() const override { return {}; } // Unused , toJson is overridden
+    String toJson() const;
+};
+
 class WiFiManager : public LoopTask {
 public:
     WiFiManager(Preferences& prefs, DataLogger& logger);
@@ -21,12 +57,38 @@ class WiFiManager : public LoopTask {
 
     bool isConnected() const;
 
+    // True when the fallback AP is currently broadcasting. Used by main.cpp
+    // to decide whether the web server should come up even without STA.
+    bool isApActive() const { return apActive; }
+
     // Set hostname for WiFi/mDNS. Must be called before begin() or takes effect on next reboot.
     void setHostname(const String& name) { hostname = name; }
 
     // Apply TX power setting (0.25 dBm units). Safe to call at any time.
     void setTxPower(int quarterDbm);
 
+    // Update the fallback-on-disconnect policy and re-evaluate AP state.
+    void setApFallbackOnDisconnect(bool enabled);
+
+    // -- API-driven WiFi management ------------------------------------------
+    // These methods follow the registerGetRoute / registerPostRoute callback
+    // shape so they can be wired directly from the web server.
+
+    // Snapshot current STA + AP state. Always succeeds.
+    void getStatus(std::function<void(bool, const WiFiStatus&)> cb);
+
+    // Trigger a synchronous WiFi.scanNetworks() and report results.
+    // Blocks the calling task for ~2s; only invoked from API handlers.
+    void scanNetworks(std::function<void(bool, const WiFiScanResult&)> cb);
+
+    // Save credentials, attempt connection. Reboots on success so the
+    // new STA setup goes through the regular boot path.
+    bool connect(const String& ssid, const String& password, std::function<void(bool)> cb);
+
+    // Clear saved credentials and disconnect the STA. AP comes up
+    // automatically after the disconnect (no credentials saved).
+    bool disconnect(std::function<void(bool)> cb);
+
 private:
     Preferences& prefs;
     DataLogger& dataLogger;
@@ -38,6 +100,11 @@ class WiFiManager : public LoopTask {
     String selectedSSID = "";
     int scannedNetworkCount = 0;
 
+    // Fallback AP state
+    bool apActive = false;
+    bool apFallbackOnDisconnect = true; // Mirrors setting; updated via setApFallbackOnDisconnect
+    String lastStaError; // Last STA failure reason (cleared on successful connect)
+
     void tick() override; // Called by LoopTask::loop() at WIFI_RECONNECT_INTERVAL cadence
 
     // Apply TX power from NVS (called after WiFi.begin and after reconnect)
@@ -54,8 +121,18 @@ class WiFiManager : public LoopTask {
 
     bool loadCredentials(String& ssid, String& password);
 
+    bool hasSavedCredentials();
+
+    // Fallback AP lifecycle
+    String apSsidName() const; // Returns "<hostname>-ap"
+    void startAccessPoint();
+    void stopAccessPoint();
+    // Decide whether the AP should be on and bring it up / down accordingly.
+    // Called whenever STA state, credentials, or apFallbackOnDisconnect change.
+    void reevaluateFallbackAp();
+
     // Menu actions
-    void scanNetworks();
+    void scanNetworksMenu();
     void manualSSID();
     void showStatus();
     void resetCredentials();
diff --git a/frontend/api/openapi.yaml b/frontend/api/openapi.yaml
index 2b0c3a2..a462a30 100644
--- a/frontend/api/openapi.yaml
+++ b/frontend/api/openapi.yaml
@@ -18,6 +18,8 @@ tags:
     description: Manual cleaning mode (joystick, motors)
   - name: Logs
     description: Diagnostic log files stored in flash
+  - name: WiFi
+    description: WiFi station status and provisioning over the fallback AP
   - name: System
     description: ESP32 system health and lifecycle
   - name: Settings
@@ -533,6 +535,70 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /api/wifi/status:
+    get:
+      tags:
+        - WiFi
+      summary: Get current WiFi STA + fallback AP status snapshot
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WiFiStatus"
+  /api/wifi/scan:
+    get:
+      tags:
+        - WiFi
+      summary: Scan for nearby WiFi networks (synchronous, capped at 30 entries)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WiFiScanResult"
+        "500":
+          description: scan failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/wifi/connect:
+    post:
+      tags:
+        - WiFi
+      summary: Save credentials and connect to a WiFi network (reboots on success)
+      parameters:
+        - name: ssid
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: password
+          in: query
+          required: true
+          description: Empty string for open networks
+          schema:
+            type: string
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "400":
+          description: missing ssid or connection failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/wifi/disconnect:
+    post:
+      tags:
+        - WiFi
+      summary: Clear saved credentials and drop the STA connection
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
   /api/system:
     get:
       tags:
@@ -1177,6 +1243,9 @@ components:
         logLevel:
           type: number
           description: 0=off, 1=info, 2=debug
+        apFallbackOnDisconnect:
+          type: boolean
+          description: Bring up the fallback AP automatically when STA drops
         syslogEnabled:
           type: boolean
           description: When on, logs go to UDP syslog instead of flash
@@ -1321,6 +1390,7 @@ components:
       required:
         - tz
         - logLevel
+        - apFallbackOnDisconnect
         - syslogEnabled
         - syslogIp
         - wifiTxPower
@@ -1520,6 +1590,74 @@ components:
         - totalRotation
         - areaCovered
         - errorsDuringClean
+    WiFiStatus:
+      type: object
+      properties:
+        staConnected:
+          type: boolean
+          description: Station mode connected to an upstream AP
+        ssid:
+          type: string
+          description: Connected SSID, or last saved SSID when disconnected
+        ip:
+          type: string
+          description: STA IPv4 address (empty when disconnected)
+        rssi:
+          type: integer
+          description: STA signal strength in dBm (0 when disconnected)
+        apActive:
+          type: boolean
+          description: Fallback AP currently broadcasting
+        apSsid:
+          type: string
+          description: Fallback AP SSID (empty when AP is down)
+        apIp:
+          type: string
+          description: Fallback AP IPv4 address (empty when AP is down)
+        apClients:
+          type: integer
+          description: Number of clients connected to the fallback AP
+        apFallbackOnDisconnect:
+          type: boolean
+          description: Whether the AP is brought up automatically when STA drops
+        lastError:
+          type: string
+          description: Human-readable description of the most recent STA failure
+      required:
+        - staConnected
+        - ssid
+        - ip
+        - rssi
+        - apActive
+        - apSsid
+        - apIp
+        - apClients
+        - apFallbackOnDisconnect
+        - lastError
+    WiFiNetwork:
+      type: object
+      properties:
+        ssid:
+          type: string
+        rssi:
+          type: integer
+          description: Signal strength in dBm
+        open:
+          type: boolean
+          description: True for open networks (no encryption)
+      required:
+        - ssid
+        - rssi
+        - open
+    WiFiScanResult:
+      type: object
+      properties:
+        networks:
+          type: array
+          items:
+            $ref: "#/components/schemas/WiFiNetwork"
+      required:
+        - networks
   responses:
     Ok:
       description: Success acknowledgement
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index f2c57d0..28bf171 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -105,6 +105,15 @@ const _randf = (min, max, decimals = 2) => parseFloat((Math.random() * (max - mi
 //   fp   — All polling faults (state + charger + error)
 //   fhc  — History corruption (inject corrupted pose lines in session data)
 //   fhl  — History list corruption (malformed JSON in /api/history response, triggers recovery panel)
+//
+// WiFi:
+//   wap  , Fallback AP active (STA disconnected, fallback enabled)
+//   wnc  , No saved credentials (first boot, AP always on)
+//   wfo  , Fallback AP setting off (combine with wap to test off + disconnected)
+//   fws  , Scan fault: /api/wifi/scan returns 500
+//   fwn  , Empty scan: /api/wifi/scan returns no networks
+//   fwc  , Connect fault: /api/wifi/connect rejects with auth error
+//
 //   fal  — All faults combined
 const SCENARIO = "ok";
 
@@ -166,6 +175,12 @@ const SCENARIOS = {
     fp: { faults: { pollState: true, pollCharger: true, pollError: true } },
     fhc: { faults: { historyCorrupt: true } },
     fhl: { faults: { historyListCorrupt: true } },
+    wap: { wifiDisconnected: true },
+    wnc: { wifiDisconnected: true, wifiNoCredentials: true },
+    wfo: { apFallbackOnDisconnect: false },
+    fws: { faults: { wifiScan: true } },
+    fwn: { faults: { wifiScanEmpty: true } },
+    fwc: { faults: { wifiConnect: true } },
     fal: {
         faults: {
             actions: true,
@@ -177,6 +192,8 @@ const SCENARIOS = {
             pollError: true,
             historyCorrupt: true,
             historyListCorrupt: true,
+            wifiScan: true,
+            wifiConnect: true,
         },
     },
 };
@@ -202,6 +219,9 @@ const faults = {
     pollCharger: false,
     pollError: false,
     historyCorrupt: false,
+    wifiScan: false,
+    wifiScanEmpty: false,
+    wifiConnect: false,
     ...(merged.faults || {}),
 };
 
@@ -246,6 +266,12 @@ const state = {
     lidarSlowRotation: false,
     tz: "UTC0",
     logLevel: 0,
+    apFallbackOnDisconnect: true,
+    // WiFi mock state , `wifiDisconnected` flips STA to disconnected and
+    // brings up the fallback AP; `wifiNoCredentials` clears saved SSID so
+    // the UI shows the "first boot" path (no current network, no forget).
+    wifiDisconnected: false,
+    wifiNoCredentials: false,
     syslogEnabled: false,
     syslogIp: "",
     wifiTxPower: 60, // 15 dBm in 0.25 dBm units
@@ -743,6 +769,7 @@ const routes = {
         const keys = [
             "tz",
             "logLevel",
+            "apFallbackOnDisconnect",
             "syslogEnabled",
             "syslogIp",
             "wifiTxPower",
@@ -775,6 +802,59 @@ const routes = {
         jsonResponse(res, s);
     },
 
+    "GET /api/wifi/status": (_req, res) => {
+        // No saved credentials: STA never reports a "last SSID" and the
+        // fallback AP is always up regardless of the toggle.
+        const hasCreds = !state.wifiNoCredentials;
+        const apOn = !!state.wifiDisconnected || !hasCreds;
+        jsonResponse(res, {
+            staConnected: !state.wifiDisconnected && hasCreds,
+            ssid: hasCreds ? "HomeWiFi" : "",
+            ip: state.wifiDisconnected || !hasCreds ? "" : "192.168.1.42",
+            rssi: state.wifiDisconnected || !hasCreds ? 0 : -52,
+            apActive: apOn,
+            apSsid: apOn ? `${state.hostname}-ap` : "",
+            apIp: apOn ? "192.168.4.1" : "",
+            apClients: apOn ? (hasCreds ? 1 : 0) : 0,
+            apFallbackOnDisconnect: state.apFallbackOnDisconnect,
+            lastError: state.wifiDisconnected && hasCreds ? "wrong password or authentication rejected" : "",
+        });
+    },
+
+    "GET /api/wifi/scan": async (_req, res) => {
+        // Simulate scan latency
+        await new Promise((r) => setTimeout(r, rand(800, 1500)));
+        if (faults.wifiScan) return sendError(res, "WiFi scan failed: radio busy", 500);
+        if (faults.wifiScanEmpty) return jsonResponse(res, { networks: [] });
+        jsonResponse(res, {
+            networks: [
+                { ssid: "HomeWiFi", rssi: -52, open: false },
+                { ssid: "Neighbour-5G", rssi: -68, open: false },
+                { ssid: "GuestNet", rssi: -71, open: true },
+                { ssid: "FritzBox-2", rssi: -78, open: false },
+                { ssid: "TP-Link-Guest", rssi: -82, open: true },
+            ],
+        });
+    },
+
+    "POST /api/wifi/connect": async (_req, res, query) => {
+        if (!query.ssid) return sendError(res, "missing ssid", 400);
+        await new Promise((r) => setTimeout(r, rand(500, 1500)));
+        if (faults.wifiConnect) {
+            return sendError(res, "wrong password or authentication rejected", 500);
+        }
+        // Simulate reboot path on success , caller will see the AP go away
+        state.wifiDisconnected = false;
+        state.wifiNoCredentials = false;
+        sendOk(res);
+    },
+
+    "POST /api/wifi/disconnect": (_req, res) => {
+        state.wifiDisconnected = true;
+        state.wifiNoCredentials = true;
+        sendOk(res);
+    },
+
     "POST /api/notifications/test": (_req, res, query) => {
         if (!query.topic) return sendError(res, "missing topic", 400);
         sendOk(res);
@@ -1075,6 +1155,7 @@ const handleRequest = async (req, res) => {
             await new Promise((r) => setTimeout(r, rand(300, 600)));
             if (data.tz !== undefined) state.tz = data.tz;
             if (data.logLevel !== undefined) state.logLevel = data.logLevel;
+            if (data.apFallbackOnDisconnect !== undefined) state.apFallbackOnDisconnect = data.apFallbackOnDisconnect;
             if (data.syslogEnabled !== undefined) state.syslogEnabled = data.syslogEnabled;
             if (data.syslogIp !== undefined) state.syslogIp = data.syslogIp;
             if (data.wifiTxPower !== undefined) state.wifiTxPower = data.wifiTxPower;
@@ -1115,6 +1196,7 @@ const handleRequest = async (req, res) => {
             const keys = [
                 "tz",
                 "logLevel",
+                "apFallbackOnDisconnect",
                 "syslogEnabled",
                 "syslogIp",
                 "wifiTxPower",
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 25cd70a..f85a0e3 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -12,6 +12,8 @@ import type {
     StateData,
     SystemData,
     UserSettingsData,
+    WiFiScanResult,
+    WiFiStatus,
 } from "./types";
 
 async function parseError(res: Response): Promise<string> {
@@ -184,4 +186,10 @@ export const api = {
     setUserSetting: (key: string, value: string) =>
         post(`/api/user-settings?key=${encodeURIComponent(key)}&value=${encodeURIComponent(value)}`),
     sendSerial: (cmd: string) => sendSerial(cmd),
+
+    getWifiStatus: () => get<WiFiStatus>("/api/wifi/status"),
+    scanWifi: () => get<WiFiScanResult>("/api/wifi/scan"),
+    connectWifi: (ssid: string, password: string) =>
+        post(`/api/wifi/connect?ssid=${encodeURIComponent(ssid)}&password=${encodeURIComponent(password)}`),
+    disconnectWifi: () => post("/api/wifi/disconnect"),
 };
diff --git a/frontend/src/assets/icons/globe.svg b/frontend/src/assets/icons/globe.svg
new file mode 100644
index 0000000..89982b4
--- /dev/null
+++ b/frontend/src/assets/icons/globe.svg
@@ -0,0 +1,5 @@
+<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="12" cy="12" r="10"/>
+  <line x1="2" y1="12" x2="22" y2="12"/>
+  <path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/>
+</svg>
diff --git a/frontend/src/components/confirm-dialog.tsx b/frontend/src/components/confirm-dialog.tsx
index ffd189f..fba13c9 100644
--- a/frontend/src/components/confirm-dialog.tsx
+++ b/frontend/src/components/confirm-dialog.tsx
@@ -3,29 +3,51 @@ import { useState } from "preact/hooks";
 interface ConfirmDialogProps {
     message: string;
     confirmLabel?: string;
-    confirmText?: string; // When set, user must type this exact text to enable confirm
+    // When true (default), the confirm button is rendered as a destructive
+    // (red) action. Set to false for benign confirmations like Connect.
+    destructive?: boolean;
+    // When set, user must type this exact text to enable confirm. Useful for
+    // destructive actions (e.g. "Type RESET to confirm").
+    confirmText?: string;
+    // Prompts the user for a free-form value (text or password). The entered
+    // value is passed to `onConfirm`. When `inputRequired` is true the
+    // confirm button is disabled until the field is non-empty.
+    inputType?: "text" | "password";
+    inputPlaceholder?: string;
+    inputLabel?: string;
+    inputRequired?: boolean;
     disabled?: boolean;
-    onConfirm: () => void;
+    onConfirm: (value?: string) => void;
     onCancel: () => void;
 }
 
 export function ConfirmDialog({
     message,
     confirmLabel = "Delete",
+    destructive = true,
     confirmText,
+    inputType,
+    inputPlaceholder,
+    inputLabel,
+    inputRequired = false,
     disabled = false,
     onConfirm,
     onCancel,
 }: ConfirmDialogProps) {
     const [typed, setTyped] = useState("");
+    const [value, setValue] = useState("");
     const textMatch = !confirmText || typed === confirmText;
+    const valueOk = !inputType || !inputRequired || value.length > 0;
 
     return (
         // biome-ignore lint/a11y/useKeyWithClickEvents: overlay dismiss is supplementary to Cancel button
         <div class="confirm-overlay" role="dialog" aria-modal="true" onClick={disabled ? undefined : onCancel}>
             {/* biome-ignore lint/a11y/useKeyWithClickEvents: stopPropagation only, not interactive */}
             {/* biome-ignore lint/a11y/noStaticElementInteractions: dialog container */}
-            <div class="confirm-dialog" onClick={(e) => e.stopPropagation()}>
+            <div
+                class={`confirm-dialog ${destructive ? "destructive" : "primary"}`}
+                onClick={(e) => e.stopPropagation()}
+            >
                 <div class="confirm-message">{message}</div>
                 {confirmText && (
                     <div class="confirm-text-input-wrap">
@@ -44,15 +66,35 @@ export function ConfirmDialog({
                         />
                     </div>
                 )}
+                {inputType && (
+                    <div class="confirm-text-input-wrap">
+                        {inputLabel && (
+                            <label class="confirm-text-label" htmlFor="confirm-input-value">
+                                {inputLabel}
+                            </label>
+                        )}
+                        <input
+                            id="confirm-input-value"
+                            type={inputType}
+                            class="confirm-text-input"
+                            value={value}
+                            onInput={(e) => setValue((e.target as HTMLInputElement).value)}
+                            placeholder={inputPlaceholder}
+                            autocomplete={inputType === "password" ? "current-password" : "off"}
+                            spellcheck={false}
+                            disabled={disabled}
+                        />
+                    </div>
+                )}
                 <div class="confirm-actions">
                     <button type="button" class="confirm-btn cancel" onClick={onCancel} disabled={disabled}>
                         Cancel
                     </button>
                     <button
                         type="button"
-                        class="confirm-btn destructive"
-                        onClick={onConfirm}
-                        disabled={disabled || !textMatch}
+                        class={`confirm-btn ${destructive ? "destructive" : "primary"}`}
+                        onClick={() => onConfirm(inputType ? value : undefined)}
+                        disabled={disabled || !textMatch || !valueOk}
                     >
                         {confirmLabel}
                     </button>
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 357a8f4..d9c8c90 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -494,10 +494,6 @@ body {
     transition: opacity 0.15s;
 }
 
-.update-banner:active {
-    opacity: 0.7;
-}
-
 .update-banner svg {
     width: 16px;
     height: 16px;
@@ -552,11 +548,14 @@ body {
 
 .action-btn:disabled {
     opacity: 0.3;
-    cursor: default;
     transform: none;
 }
 
-.action-btn.pending {
+/* -- Shared cross-cutting utilities --------------------------------------- */
+
+/* Pulse for any in-flight button or input. Components opt in by adding the
+   `pending` class while a request is running. */
+.pending {
     animation: btn-pulse 1s ease-in-out infinite;
 }
 
@@ -570,6 +569,33 @@ body {
     }
 }
 
+/* Default cursor on disabled controls , replaces per-element copies. */
+button:disabled,
+select:disabled,
+input:disabled {
+    cursor: default;
+}
+
+/* Press feedback for tappable elements. Listed explicitly because some
+   buttons have custom :active styles (transform-based scales) that we
+   don't want to dim. */
+.update-banner:active,
+.settings-category-header:active,
+.settings-nav-row:active,
+.settings-ntfy-test-btn:not(:disabled):active,
+.settings-wifi-scan-btn:not(:disabled):active,
+.fw-upload-btn:active,
+.settings-save-btn:active,
+.settings-device-btn:active,
+.confirm-btn:active,
+.logs-delete-all-btn:active,
+.logs-file-info:active,
+.history-recovery-link:active,
+.history-session-card:active,
+.history-delete-all-btn:active {
+    opacity: 0.7;
+}
+
 .action-btn.primary {
     background: var(--surface-raised);
     color: var(--btn-color);
@@ -624,7 +650,6 @@ body {
 
 .header-back-btn:disabled {
     opacity: 0.3;
-    cursor: default;
     transform: none;
 }
 
@@ -691,10 +716,6 @@ body {
     letter-spacing: 0.01em;
 }
 
-.settings-category-header:active {
-    opacity: 0.7;
-}
-
 .settings-category-title {
     display: flex;
     align-items: center;
@@ -828,14 +849,6 @@ body {
     border-color: var(--accent);
 }
 
-.settings-tz-select:disabled {
-    cursor: default;
-}
-
-.settings-tz-select.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .settings-robot-time {
     display: flex;
     align-items: center;
@@ -876,10 +889,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.settings-nav-row:active {
-    opacity: 0.7;
-}
-
 .settings-nav-row-left {
     display: flex;
     align-items: center;
@@ -919,6 +928,13 @@ body {
     margin-bottom: 10px;
 }
 
+/* Drop the trailing gap when the toggle is the last thing in its container,
+   so single-toggle sections don't show extra padding before the section
+   divider. Stacked toggles still get the 10px breathing room above. */
+.settings-toggle-row:last-child {
+    margin-bottom: 0;
+}
+
 .settings-toggle-label {
     display: flex;
     flex-direction: column;
@@ -967,10 +983,6 @@ body {
         background 0.2s;
 }
 
-.settings-toggle.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .settings-toggle.on {
     border-color: var(--text);
 }
@@ -1069,11 +1081,44 @@ body {
 
 .settings-ntfy-test-btn:disabled {
     opacity: 0.4;
-    cursor: default;
 }
 
-.settings-ntfy-test-btn:not(:disabled):active {
-    opacity: 0.7;
+/* WiFi management section */
+
+.settings-wifi-pick-row {
+    display: flex;
+    gap: 8px;
+    align-items: stretch;
+}
+
+.settings-wifi-select {
+    flex: 1;
+    min-width: 0;
+}
+
+.settings-wifi-scan-btn {
+    padding: 8px 16px;
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    background: var(--surface);
+    color: var(--text);
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    white-space: nowrap;
+    transition: opacity 0.15s;
+}
+
+.settings-wifi-scan-btn:disabled {
+    opacity: 0.4;
+}
+
+.settings-wifi-password {
+    margin-top: 10px;
+}
+
+.settings-wifi-connect-btn {
+    margin-top: 10px;
 }
 
 /* Firmware update section */
@@ -1185,10 +1230,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.fw-upload-btn:active {
-    opacity: 0.7;
-}
-
 .fw-progress-wrap {
     display: flex;
     flex-direction: column;
@@ -1248,17 +1289,8 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.settings-save-btn:active {
-    opacity: 0.7;
-}
-
 .settings-save-btn:disabled {
     opacity: 0.3;
-    cursor: default;
-}
-
-.settings-save-btn.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
 }
 
 /* Device action buttons */
@@ -1285,10 +1317,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.settings-device-btn:active {
-    opacity: 0.7;
-}
-
 .settings-device-btn span {
     display: flex;
 }
@@ -1362,8 +1390,23 @@ body {
     outline: none;
 }
 
-.confirm-text-input:focus {
-    border-color: var(--red);
+/* Per-variant tone , drives the confirm button color. */
+.confirm-dialog.destructive {
+    --tone: var(--red);
+    --tone-bg: rgba(255, 69, 58, 0.12);
+    --tone-border: rgba(255, 69, 58, 0.2);
+}
+
+.confirm-dialog.primary {
+    --tone: var(--accent);
+    --tone-bg: rgba(249, 235, 178, 0.08);
+    --tone-border: var(--border-accent);
+}
+
+/* Tint the input focus on destructive dialogs to reinforce the "type X to
+   confirm" gate. Plain dialogs (Connect, password entry) use the default. */
+.confirm-dialog.destructive .confirm-text-input:focus {
+    border-color: var(--tone);
 }
 
 .confirm-actions {
@@ -1383,13 +1426,8 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.confirm-btn:active {
-    opacity: 0.7;
-}
-
 .confirm-btn:disabled {
     opacity: 0.3;
-    cursor: default;
 }
 
 .confirm-btn.cancel {
@@ -1397,15 +1435,20 @@ body {
     color: var(--text);
 }
 
-.confirm-btn.destructive {
-    background: rgba(255, 69, 58, 0.12);
-    border-color: rgba(255, 69, 58, 0.2);
-    color: var(--red);
+.confirm-btn.destructive,
+.confirm-btn.primary {
+    background: var(--tone-bg);
+    border-color: var(--tone-border);
+    color: var(--tone);
+}
+
+.confirm-btn.primary {
+    font-weight: 700;
 }
 
-/* Reboot overlay */
+/* Full-screen loading overlay (reboot, WiFi connect, etc.) */
 
-.reboot-overlay {
+.loading-overlay {
     position: fixed;
     inset: 0;
     z-index: 200;
@@ -1418,7 +1461,7 @@ body {
     backdrop-filter: blur(4px);
 }
 
-.reboot-dialog {
+.loading-dialog {
     display: flex;
     flex-direction: column;
     align-items: center;
@@ -1431,28 +1474,30 @@ body {
     max-width: 260px;
 }
 
-.reboot-spinner {
+.loading-spinner {
     width: 36px;
     height: 36px;
     border: 3px solid var(--border);
     border-top-color: var(--accent);
     border-radius: 50%;
-    animation: reboot-spin 0.8s linear infinite;
+    animation: loading-spin 0.8s linear infinite;
 }
 
-@keyframes reboot-spin {
+@keyframes loading-spin {
     to {
         transform: rotate(360deg);
     }
 }
 
-.reboot-text {
+.loading-text {
     font-size: 16px;
     font-weight: 600;
     color: var(--text);
+    text-align: center;
+    word-break: break-word;
 }
 
-.reboot-subtext {
+.loading-subtext {
     font-size: 12px;
     font-weight: 500;
     color: var(--text-muted);
@@ -1491,18 +1536,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.logs-delete-all-btn:active {
-    opacity: 0.7;
-}
-
-.logs-delete-all-btn:disabled {
-    cursor: default;
-}
-
-.logs-delete-all-btn.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .logs-empty {
     display: flex;
     flex-direction: column;
@@ -1554,10 +1587,6 @@ body {
     min-width: 0;
 }
 
-.logs-file-info:active {
-    opacity: 0.7;
-}
-
 .logs-file-name {
     font-size: 13px;
     font-weight: 600;
@@ -1625,14 +1654,6 @@ body {
     opacity: 1;
 }
 
-.logs-file-delete:disabled {
-    cursor: default;
-}
-
-.logs-file-delete.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .logs-file-delete span {
     display: flex;
 }
@@ -1924,10 +1945,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.history-recovery-link:active {
-    opacity: 0.7;
-}
-
 .history-session-row {
     display: flex;
     align-items: center;
@@ -2002,10 +2019,6 @@ body {
     min-width: 0;
 }
 
-.history-session-card:active {
-    opacity: 0.7;
-}
-
 .history-session-download {
     flex-shrink: 0;
     width: 40px;
@@ -2165,18 +2178,6 @@ body {
     -webkit-tap-highlight-color: transparent;
 }
 
-.history-delete-all-btn:active {
-    opacity: 0.7;
-}
-
-.history-delete-all-btn:disabled {
-    cursor: default;
-}
-
-.history-delete-all-btn.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .history-summary-actions {
     display: flex;
     gap: 8px;
@@ -2209,10 +2210,6 @@ body {
     opacity: 0.7;
 }
 
-.history-import-btn.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .history-detail-stats {
     display: flex;
     justify-content: space-around;
@@ -2435,7 +2432,6 @@ body {
 
 .history-player-btn:disabled {
     opacity: 0.4;
-    cursor: default;
 }
 
 .history-player-btn span {
@@ -2668,7 +2664,6 @@ body {
 
 .sched-add-btn:disabled {
     opacity: 0.3;
-    cursor: default;
 }
 
 .sched-remove-btn {
@@ -2695,10 +2690,6 @@ body {
     opacity: 1;
 }
 
-.sched-remove-btn:disabled {
-    cursor: default;
-}
-
 .schedule-day-left {
     display: flex;
     align-items: center;
@@ -2923,10 +2914,6 @@ body {
     border-color: var(--blue);
 }
 
-.manual-motor-btn.pending {
-    animation: btn-pulse 1s ease-in-out infinite;
-}
-
 .manual-motor-btn:active {
     transform: scale(0.95);
 }
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 57ca141..a23be6e 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -18,6 +18,9 @@ export type {
     SystemData,
     UserSettingsData,
     VersionData,
+    WiFiNetwork,
+    WiFiScanResult,
+    WiFiStatus,
 } from "./types.generated";
 
 // -- Frontend-only types (not part of the HTTP API) --------------------------
@@ -44,7 +47,7 @@ export interface MapRechargePoint {
     // Session-relative timestamp when the robot returned to base to charge,
     // derived from the last pose snapshot before collection paused.
     ts: number;
-    // Session-relative timestamp when cleaning resumed after the charge —
+    // Session-relative timestamp when cleaning resumed after the charge -
     // taken from the first pose snapshot written once collection restarted.
     // Falls back to `ts` when the session ended before resuming.
     endTs: number;
diff --git a/frontend/src/views/settings.tsx b/frontend/src/views/settings.tsx
index ba17aa7..64317d3 100644
--- a/frontend/src/views/settings.tsx
+++ b/frontend/src/views/settings.tsx
@@ -39,6 +39,7 @@ import { SettingsCategory } from "./settings/settings-category";
 import { useFirmwareUpload } from "./settings/use-firmware-upload";
 import { useReboot } from "./settings/use-reboot";
 import { useSettingsForm } from "./settings/use-settings-form";
+import { WiFiSection } from "./settings/wifi-section";
 
 type Theme = "system" | "dark" | "light";
 
@@ -85,6 +86,8 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
         setSyslogIp,
         wifiTxPower,
         setWifiTxPower,
+        apFallbackOnDisconnect,
+        setApFallbackOnDisconnect,
         uartTxPin,
         setUartTxPin,
         uartRxPin,
@@ -493,6 +496,15 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
                     </div>
                 </SettingsCategory>
 
+                <SettingsCategory title="WiFi" icon={wifiSvg} lazy>
+                    <WiFiSection
+                        apFallbackOnDisconnect={apFallbackOnDisconnect}
+                        onApFallbackChange={setApFallbackOnDisconnect}
+                        saving={saving}
+                        errorStack={errorStack}
+                    />
+                </SettingsCategory>
+
                 <SettingsCategory title="Notifications" icon={bellSvg}>
                     <div class="settings-section">
                         <div class="settings-toggle-row">
@@ -1158,11 +1170,11 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
             )}
 
             {(rebooting || robotRestarting) && (
-                <div class="reboot-overlay">
-                    <div class="reboot-dialog">
-                        <div class="reboot-spinner" />
-                        <div class="reboot-text">{robotRestarting ? "Restarting robot..." : "Rebooting..."}</div>
-                        <div class="reboot-subtext">
+                <div class="loading-overlay">
+                    <div class="loading-dialog">
+                        <div class="loading-spinner" />
+                        <div class="loading-text">{robotRestarting ? "Restarting robot..." : "Rebooting..."}</div>
+                        <div class="loading-subtext">
                             {robotRestarting
                                 ? "Waiting for robot to come back online"
                                 : "Waiting for device to come back online"}
diff --git a/frontend/src/views/settings/constants.ts b/frontend/src/views/settings/constants.ts
index 7fe1a4e..26ed254 100644
--- a/frontend/src/views/settings/constants.ts
+++ b/frontend/src/views/settings/constants.ts
@@ -115,6 +115,7 @@ export const SIDE_BRUSH_PRESETS: SideBrushPreset[] = [
 export const DEFAULT_SERVER = {
     tz: "UTC0",
     logLevel: 0,
+    apFallbackOnDisconnect: true,
     syslogEnabled: false,
     syslogIp: "",
     wifiTxPower: 60,
diff --git a/frontend/src/views/settings/settings-category.tsx b/frontend/src/views/settings/settings-category.tsx
index 603744d..eea5df4 100644
--- a/frontend/src/views/settings/settings-category.tsx
+++ b/frontend/src/views/settings/settings-category.tsx
@@ -7,17 +7,34 @@ interface SettingsCategoryProps {
     icon: string;
     defaultOpen?: boolean;
     disabled?: boolean;
+    // When true, children are only mounted after the section has been opened
+    // at least once. Useful for sections that poll the device or run expensive
+    // work the user shouldn't pay for unless they're looking at them.
+    lazy?: boolean;
     children: ComponentChildren;
 }
 
-export function SettingsCategory({ title, icon, defaultOpen = false, disabled, children }: SettingsCategoryProps) {
+export function SettingsCategory({
+    title,
+    icon,
+    defaultOpen = false,
+    disabled,
+    lazy = false,
+    children,
+}: SettingsCategoryProps) {
     const [open, setOpen] = useState(defaultOpen);
+    const [hasOpened, setHasOpened] = useState(defaultOpen);
+    const showChildren = lazy ? hasOpened : true;
     return (
         <div class={`settings-category${open && !disabled ? " open" : ""}${disabled ? " disabled" : ""}`}>
             <button
                 type="button"
                 class="settings-category-header"
-                onClick={() => !disabled && setOpen(!open)}
+                onClick={() => {
+                    if (disabled) return;
+                    setOpen(!open);
+                    if (!open) setHasOpened(true);
+                }}
                 disabled={disabled}
             >
                 <div class="settings-category-title">
@@ -27,7 +44,7 @@ export function SettingsCategory({ title, icon, defaultOpen = false, disabled, c
                 {!disabled && <span class="settings-category-chevron">&rsaquo;</span>}
             </button>
             <div class="settings-category-body">
-                <div class="settings-category-inner">{children}</div>
+                <div class="settings-category-inner">{showChildren && children}</div>
             </div>
         </div>
     );
diff --git a/frontend/src/views/settings/use-settings-form.ts b/frontend/src/views/settings/use-settings-form.ts
index 72a96b4..583a7a4 100644
--- a/frontend/src/views/settings/use-settings-form.ts
+++ b/frontend/src/views/settings/use-settings-form.ts
@@ -10,6 +10,7 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
     // Local form state
     const [tz, setTz] = useState<string>("UTC0");
     const [logLevel, setLogLevel] = useState(0);
+    const [apFallbackOnDisconnect, setApFallbackOnDisconnect] = useState(true);
     const [syslogEnabled, setSyslogEnabled] = useState(false);
     const [syslogIp, setSyslogIp] = useState("");
     const [wifiTxPower, setWifiTxPower] = useState(60);
@@ -45,6 +46,7 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
             server.current = { ...fetched };
             setTz(fetched.tz);
             setLogLevel(fetched.logLevel);
+            setApFallbackOnDisconnect(fetched.apFallbackOnDisconnect ?? true);
             setSyslogEnabled(fetched.syslogEnabled ?? false);
             setSyslogIp(fetched.syslogIp ?? "");
             setWifiTxPower(fetched.wifiTxPower);
@@ -73,6 +75,7 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
         settingsLoaded &&
         (tz !== server.current.tz ||
             logLevel !== server.current.logLevel ||
+            apFallbackOnDisconnect !== (server.current.apFallbackOnDisconnect ?? true) ||
             syslogEnabled !== (server.current.syslogEnabled ?? false) ||
             syslogIp !== (server.current.syslogIp ?? "") ||
             wifiTxPower !== server.current.wifiTxPower ||
@@ -130,6 +133,8 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
         const patch: Partial<SettingsData> = {};
         if (tz !== server.current.tz) patch.tz = tz;
         if (logLevel !== server.current.logLevel) patch.logLevel = logLevel;
+        if (apFallbackOnDisconnect !== (server.current.apFallbackOnDisconnect ?? true))
+            patch.apFallbackOnDisconnect = apFallbackOnDisconnect;
         if (syslogEnabled !== (server.current.syslogEnabled ?? false)) patch.syslogEnabled = syslogEnabled;
         if (syslogIp !== (server.current.syslogIp ?? "")) patch.syslogIp = syslogIp;
         if (wifiTxPower !== server.current.wifiTxPower) patch.wifiTxPower = wifiTxPower;
@@ -151,6 +156,7 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
     }, [
         tz,
         logLevel,
+        apFallbackOnDisconnect,
         syslogEnabled,
         syslogIp,
         wifiTxPower,
@@ -209,6 +215,8 @@ export function useSettingsForm(errorStack: ErrorStackHandle, startRebootFlow: (
         setTz,
         logLevel,
         setLogLevel,
+        apFallbackOnDisconnect,
+        setApFallbackOnDisconnect,
         syslogEnabled,
         setSyslogEnabled,
         syslogIp,
diff --git a/frontend/src/views/settings/wifi-section.tsx b/frontend/src/views/settings/wifi-section.tsx
new file mode 100644
index 0000000..7e472c9
--- /dev/null
+++ b/frontend/src/views/settings/wifi-section.tsx
@@ -0,0 +1,278 @@
+import { useCallback, useState } from "preact/hooks";
+import { api } from "../../api";
+import alertSvg from "../../assets/icons/alert.svg?raw";
+import bolt from "../../assets/icons/bolt.svg?raw";
+import globeSvg from "../../assets/icons/globe.svg?raw";
+import wifiSvg from "../../assets/icons/wifi.svg?raw";
+import wifiOffSvg from "../../assets/icons/wifi-off.svg?raw";
+import { ConfirmDialog } from "../../components/confirm-dialog";
+import type { ErrorStackHandle } from "../../components/error-banner";
+import { Icon } from "../../components/icon";
+import { usePolling } from "../../hooks/use-polling";
+import type { WiFiNetwork, WiFiStatus } from "../../types";
+import { normalizeError } from "../../utils";
+
+interface WiFiSectionProps {
+    apFallbackOnDisconnect: boolean;
+    onApFallbackChange: (value: boolean) => void;
+    saving: boolean;
+    errorStack: ErrorStackHandle;
+}
+
+// Map dBm to a coarse 1-4 bar count, mirroring desktop OS conventions.
+function rssiBars(rssi: number): number {
+    if (rssi >= -55) return 4;
+    if (rssi >= -65) return 3;
+    if (rssi >= -75) return 2;
+    return 1;
+}
+
+export function WiFiSection({ apFallbackOnDisconnect, onApFallbackChange, saving, errorStack }: WiFiSectionProps) {
+    const statusPoll = usePolling<WiFiStatus>(api.getWifiStatus, 5000);
+    const status = statusPoll.data;
+
+    const [scanning, setScanning] = useState(false);
+    const [networks, setNetworks] = useState<WiFiNetwork[] | null>(null);
+    const [selectedSsid, setSelectedSsid] = useState("");
+    const [pendingNetwork, setPendingNetwork] = useState<WiFiNetwork | null>(null);
+    const [connecting, setConnecting] = useState(false);
+    const [disconnecting, setDisconnecting] = useState(false);
+    const [showForgetConfirm, setShowForgetConfirm] = useState(false);
+
+    const handleScan = useCallback(() => {
+        setScanning(true);
+        api.scanWifi()
+            .then((res) => {
+                // Sort strongest first; deduplicate by SSID (keep best RSSI per name)
+                const best = new Map<string, WiFiNetwork>();
+                for (const n of res.networks) {
+                    if (!n.ssid) continue;
+                    const existing = best.get(n.ssid);
+                    if (!existing || n.rssi > existing.rssi) best.set(n.ssid, n);
+                }
+                setNetworks([...best.values()].sort((a, b) => b.rssi - a.rssi));
+            })
+            .catch((e: unknown) => errorStack.push(normalizeError(e, "WiFi scan failed")))
+            .finally(() => setScanning(false));
+    }, [errorStack]);
+
+    const startConnect = useCallback(
+        (ssid: string) => {
+            const network = networks?.find((n) => n.ssid === ssid);
+            if (!network) return;
+            setPendingNetwork(network);
+        },
+        [networks],
+    );
+
+    // Drop the connect dialog and reset the dropdown back to "Choose a
+    // network". Used on cancel and on connect failure so the UI is in the
+    // same clean state either way.
+    const resetConnectFlow = useCallback(() => {
+        setPendingNetwork(null);
+        setSelectedSsid("");
+    }, []);
+
+    const handleConnectConfirm = useCallback(
+        (password?: string) => {
+            const network = pendingNetwork;
+            if (!network) return;
+            setConnecting(true);
+            api.connectWifi(network.ssid, password ?? "")
+                .then(() => {
+                    // Reload so the settings page picks up the new STA state
+                    // and the connecting overlay clears. On real hardware the
+                    // device reboots and the browser was on the AP, so the
+                    // reload also forces a fresh navigation to the new IP.
+                    window.location.reload();
+                })
+                .catch((e: unknown) => {
+                    errorStack.push(normalizeError(e, "Failed to connect"));
+                    resetConnectFlow();
+                    setConnecting(false);
+                });
+        },
+        [pendingNetwork, errorStack, resetConnectFlow],
+    );
+
+    const handleForget = useCallback(() => {
+        setShowForgetConfirm(false);
+        setDisconnecting(true);
+        api.disconnectWifi()
+            .then(() => {
+                // Reload so the page reflects the post-disconnect state
+                // (no current network, fallback AP active) without keeping
+                // stale local UI state around.
+                window.location.reload();
+            })
+            .catch((e: unknown) => {
+                errorStack.push(normalizeError(e, "Failed to forget network"));
+                setDisconnecting(false);
+            });
+    }, [errorStack]);
+
+    const busy = scanning || connecting || disconnecting;
+
+    return (
+        <>
+            <div class="settings-section">
+                <div class="settings-section-title">Status</div>
+                <div class="fw-info-row">
+                    <div class="fw-info-item">
+                        <Icon svg={status?.staConnected ? wifiSvg : wifiOffSvg} />
+                        <span>
+                            {status
+                                ? status.staConnected
+                                    ? `${status.ssid || "Connected"}`
+                                    : status.ssid
+                                      ? `Disconnected (${status.ssid})`
+                                      : "Not configured"
+                                : "..."}
+                        </span>
+                    </div>
+                    {status?.staConnected && (
+                        <>
+                            <div class="fw-info-item">
+                                <Icon svg={globeSvg} />
+                                <span>{status.ip}</span>
+                            </div>
+                            <div class="fw-info-item">
+                                <Icon svg={bolt} />
+                                <span>
+                                    {status.rssi} dBm ({rssiBars(status.rssi)}/4)
+                                </span>
+                            </div>
+                        </>
+                    )}
+                    {status?.apActive && (
+                        <div class="fw-info-item">
+                            <Icon svg={wifiSvg} />
+                            <span>
+                                AP: {status.apSsid} @ {status.apIp}
+                                {status.apClients > 0 && ` (${status.apClients})`}
+                            </span>
+                        </div>
+                    )}
+                </div>
+                {status && !status.staConnected && status.lastError && (
+                    <div class="settings-field-error">{status.lastError}</div>
+                )}
+            </div>
+
+            <div class="settings-section">
+                <div class="settings-toggle-row">
+                    <div class="settings-toggle-label">
+                        <span class="settings-toggle-title">Fallback AP on disconnect</span>
+                        <span class="settings-toggle-desc">
+                            Expose <code>{`<hostname>-ap`}</code> when the saved network is unreachable so you can
+                            recover from a browser. Always on when no credentials are saved.
+                        </span>
+                    </div>
+                    <button
+                        type="button"
+                        class={`settings-toggle${apFallbackOnDisconnect ? " on" : ""}`}
+                        onClick={() => onApFallbackChange(!apFallbackOnDisconnect)}
+                        disabled={saving}
+                        aria-label="Toggle fallback AP"
+                    />
+                </div>
+            </div>
+
+            <div class="settings-section">
+                <div class="settings-section-title">Connect to a network</div>
+                <div class="settings-wifi-pick-row">
+                    <div class="settings-tz-select-wrap settings-wifi-select">
+                        <select
+                            class="settings-tz-select"
+                            value={selectedSsid}
+                            onChange={(e) => {
+                                const value = (e.target as HTMLSelectElement).value;
+                                setSelectedSsid(value);
+                                if (value) startConnect(value);
+                            }}
+                            disabled={busy || !networks || networks.length === 0}
+                        >
+                            <option value="">
+                                {scanning
+                                    ? "Scanning..."
+                                    : networks
+                                      ? networks.length === 0
+                                          ? "No networks found"
+                                          : "Choose a network"
+                                      : "Scan to choose a network"}
+                            </option>
+                            {networks?.map((n) => (
+                                <option key={n.ssid} value={n.ssid}>
+                                    {n.ssid} ({n.rssi} dBm{n.open ? ", open" : ""})
+                                </option>
+                            ))}
+                        </select>
+                    </div>
+                    <button
+                        type="button"
+                        class={`settings-wifi-scan-btn${scanning ? " pending" : ""}`}
+                        onClick={handleScan}
+                        disabled={busy}
+                        aria-label="Scan for networks"
+                    >
+                        Scan
+                    </button>
+                </div>
+            </div>
+
+            {status?.staConnected && (
+                <div class="settings-section">
+                    <button
+                        type="button"
+                        class={`settings-nav-row danger${disconnecting ? " pending" : ""}`}
+                        onClick={() => setShowForgetConfirm(true)}
+                        disabled={busy}
+                    >
+                        <div class="settings-nav-row-left">
+                            <Icon svg={alertSvg} />
+                            {disconnecting ? "Forgetting..." : "Forget current network"}
+                        </div>
+                    </button>
+                </div>
+            )}
+
+            {pendingNetwork && !connecting && (
+                <ConfirmDialog
+                    message={
+                        pendingNetwork.open
+                            ? `Connect to ${pendingNetwork.ssid}? It is an open network.`
+                            : `Enter the password for ${pendingNetwork.ssid}.`
+                    }
+                    confirmLabel="Connect"
+                    destructive={false}
+                    inputType={pendingNetwork.open ? undefined : "password"}
+                    inputPlaceholder="Network password"
+                    inputRequired={!pendingNetwork.open}
+                    onConfirm={handleConnectConfirm}
+                    onCancel={resetConnectFlow}
+                />
+            )}
+
+            {connecting && pendingNetwork && (
+                <div class="loading-overlay">
+                    <div class="loading-dialog">
+                        <div class="loading-spinner" />
+                        <div class="loading-text">Connecting to {pendingNetwork.ssid}...</div>
+                        <div class="loading-subtext">
+                            The device will reboot after joining the network. You may need to reconnect your browser.
+                        </div>
+                    </div>
+                </div>
+            )}
+
+            {showForgetConfirm && (
+                <ConfirmDialog
+                    message={`Forget "${status?.ssid ?? "current network"}"? Saved credentials will be erased and the device will drop to the fallback AP.`}
+                    confirmLabel="Forget"
+                    onConfirm={() => handleForget()}
+                    onCancel={() => setShowForgetConfirm(false)}
+                />
+            )}
+        </>
+    );
+}

From 20272a0ab554e1f8eddc0df4fdb1a69fd7986685 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Tue, 28 Apr 2026 00:32:44 +0300
Subject: [PATCH 11/44] docs: add manual esptool flashing guide (#111)

---
 docs/user-guide.md | 103 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/docs/user-guide.md b/docs/user-guide.md
index 374e0d7..2c6f034 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -13,6 +13,7 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
     - [Basic Usage](#basic-usage)
     - [What Happens Under the Hood](#what-happens-under-the-hood)
     - [Command Reference](#command-reference)
+    - [Manual Flashing with esptool](#manual-flashing-with-esptool)
     - [Troubleshooting Flash Issues](#troubleshooting-flash-issues)
 - [First-Time WiFi Setup](#first-time-wifi-setup)
     - [Option A: Fallback Access Point (no serial cable)](#option-a-fallback-access-point-no-serial-cable)
@@ -215,6 +216,108 @@ tool refuses to flash.
 > directory as the `.tar.gz` file. The tool verifies SHA-256 before extracting and will
 > refuse to flash if the checksums file is missing or the hash doesn't match.
 
+### Manual Flashing with esptool
+
+If `openneato-flash` does not run on your system, you can flash the same firmware pack manually
+with Espressif's prebuilt `esptool` binary. This path does not require Python and uses the same
+files, offsets, baud rate, compression, and reset behavior as `openneato-flash`.
+
+1. Download the matching prebuilt `esptool` binary for your platform from
+   [Espressif's esptool releases](https://github.com/espressif/esptool/releases), then extract
+   it. To use the same version as `openneato-flash`, check `ESPTOOL_VERSION` in
+   [`.goreleaser.yml`](../.goreleaser.yml).
+
+2. Plug in the ESP32. If only one ESP device is connected, you can let `esptool` find the serial
+   port automatically by omitting `-p`.
+
+   If you have multiple serial devices connected, pass the port explicitly with `-p`. Common port
+   names are `/dev/cu.usbmodem*` on macOS, `/dev/ttyUSB*` or `/dev/ttyACM*` on Linux, and `COM3`
+   or similar on Windows.
+
+3. Detect the chip name:
+
+   ```bash
+   ./esptool chip-id
+   ```
+
+   Look for a line like `Detecting chip type... ESP32-C3`, then use the lowercase chip name in
+   the firmware filename: `esp32-c3`, `esp32-s3`, or `esp32`.
+
+4. Download the full firmware pack and `checksums.txt` from the
+   [OpenNeato Releases](https://github.com/renjfk/OpenNeato/releases) page.
+
+   For example, for an ESP32-C3 on the latest release:
+
+   ```bash
+   curl -LO https://github.com/renjfk/OpenNeato/releases/latest/download/openneato-esp32-c3-full.tar.gz
+   curl -LO https://github.com/renjfk/OpenNeato/releases/latest/download/checksums.txt
+   ```
+
+5. Verify the firmware pack checksum before extracting it.
+
+   macOS:
+
+   ```bash
+   shasum -a 256 -c checksums.txt --ignore-missing
+   ```
+
+   Linux:
+
+   ```bash
+   sha256sum -c checksums.txt --ignore-missing
+   ```
+
+   Windows PowerShell:
+
+   ```powershell
+   Select-String "openneato-esp32-c3-full.tar.gz" checksums.txt
+   Get-FileHash .\openneato-esp32-c3-full.tar.gz -Algorithm SHA256
+   ```
+
+   The hash printed by PowerShell must match the hash from `checksums.txt`.
+
+6. Extract the firmware pack and open `offsets.json`.
+
+   macOS/Linux:
+
+   ```bash
+   tar -xzf openneato-esp32-c3-full.tar.gz
+   ```
+
+   Windows PowerShell:
+
+   ```powershell
+   tar -xzf .\openneato-esp32-c3-full.tar.gz
+   ```
+
+7. Flash all images using the offsets from `offsets.json`.
+
+   macOS/Linux:
+
+   ```bash
+   ./esptool -b 921600 --before default-reset --after hard-reset write-flash -z \
+     BOOTLOADER_OFFSET bootloader.bin \
+     PARTITIONS_OFFSET partitions.bin \
+     OTADATA_OFFSET boot_app0.bin \
+     APP_OFFSET firmware.bin
+   ```
+
+   Windows PowerShell:
+
+   ```powershell
+   .\esptool.exe -b 921600 --before default-reset --after hard-reset write-flash -z `
+     BOOTLOADER_OFFSET .\bootloader.bin `
+     PARTITIONS_OFFSET .\partitions.bin `
+     OTADATA_OFFSET .\boot_app0.bin `
+     APP_OFFSET .\firmware.bin
+   ```
+
+   Replace the `*_OFFSET` placeholders with the values from `offsets.json`, and replace the
+   firmware pack name to match your chip. If auto-detection picks the wrong serial device or you
+   have multiple ESP devices connected, add `-p <port>` before `-b 921600`. Do not hard-code the
+   flash offsets from another source; `offsets.json` is generated with the release and is the
+   source of truth for the manual command.
+
 ### Troubleshooting Flash Issues
 
 **"No USB serial ports found"** — Make sure the ESP32 is plugged in and your OS recognizes

From e582d0bd6fc8bb6ec0e64f6f3a18ec750daf949d Mon Sep 17 00:00:00 2001
From: Jonny <Jonnyvb@users.noreply.github.com>
Date: Wed, 29 Apr 2026 23:10:28 +0100
Subject: [PATCH 12/44] Fix docs regarding GPIO config (#113)

---
 docs/user-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user-guide.md b/docs/user-guide.md
index 2c6f034..f6c21b8 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -98,7 +98,7 @@ These are the **robot's** RX/TX labels, so you cross-connect to the ESP32:
 
 The default TX/RX GPIOs depend on the chip (ESP32-C3: GPIO 3/4, ESP32-S3: GPIO 17/18,
 original ESP32: GPIO 17/16) but are fully configurable from the web UI in
-**Settings -> Robot -> UART Pins** — so wire whichever GPIOs are convenient and update the
+**Settings -> Device -> UART Pins** — so wire whichever GPIOs are convenient and update the
 setting to match.
 
 ### Wiring

From 559c0edd669e511d7fd1943a8a9ec62ca99e14e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Sun, 3 May 2026 15:49:15 +0300
Subject: [PATCH 13/44] fix S3 flash size (#116)

---
 platformio.ini | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/platformio.ini b/platformio.ini
index 335371f..540841a 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -77,6 +77,8 @@ build_flags =
 
 [board_s3]
 board = esp32-s3-devkitc-1
+board_build.flash_size = 4MB
+board_upload.flash_size = 4MB
 build_flags =
     -DARDUINO_USB_MODE=1
     -DARDUINO_USB_CDC_ON_BOOT=1

From dfdd98f2e4b3da256dc2afd4bcf253ac05ca5ff2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Thu, 7 May 2026 09:41:35 +0300
Subject: [PATCH 14/44] ci: fix workflow lint issues

---
 .github/workflows/prerelease.yml | 18 ++++++++++--------
 .github/workflows/release.yml    |  6 +++---
 .gitignore                       |  1 +
 AGENTS.md                        |  3 +++
 4 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index b5b7a78..53adb21 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -51,15 +51,17 @@ jobs:
           if [ -n "$PR_NUMBER" ]; then
             TAG="v${BASE}-pr${PR_NUMBER}.${SHORT_SHA}"
           else
-            SAFE_REF=$(echo "$HEAD_REF" | sed 's/[^a-zA-Z0-9._-]/-/g')
+            SAFE_REF="${HEAD_REF//[^a-zA-Z0-9._-]/-}"
             TAG="v${BASE}-${SAFE_REF}.${SHORT_SHA}"
           fi
 
-          echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
-          echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
-          echo "head_ref=$HEAD_REF" >> "$GITHUB_OUTPUT"
-          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          {
+            echo "pr_number=$PR_NUMBER"
+            echo "head_sha=$HEAD_SHA"
+            echo "head_ref=$HEAD_REF"
+            echo "tag=$TAG"
+            echo "version=${TAG#v}"
+          } >> "$GITHUB_OUTPUT"
           echo "Release: $TAG ($HEAD_REF @ $SHORT_SHA)"
 
   prerelease:
@@ -120,10 +122,10 @@ jobs:
         env:
           FIRMWARE_VERSION: ${{ needs.resolve.outputs.version }}
         run: |
-          for env in $(grep -oE '^\[env:([a-zA-Z0-9_-]+-release)\]' platformio.ini | sed 's/\[env:\(.*\)\]/\1/'); do
+          while IFS= read -r env; do
             echo "Building $env..."
             pio run -e "$env"
-          done
+          done < <(grep -oE '^\[env:([a-zA-Z0-9_-]+-release)\]' platformio.ini | sed 's/\[env:\(.*\)\]/\1/')
 
       # --- Flash tool + GitHub Release ---
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7e6f668..e847bba 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -58,7 +58,7 @@ jobs:
         run: |
           RELEASE_TAG="${{ github.event.inputs.release_tag }}"
           VERSION=${RELEASE_TAG#v}
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Setting version to: $VERSION"
 
       - name: Save release notes
@@ -126,10 +126,10 @@ jobs:
         run: |
           # Build all *-release environments; post-build hook packages
           # firmware artifacts into each env's build dir for GoReleaser
-          for env in $(grep -oE '^\[env:([a-zA-Z0-9_-]+-release)\]' platformio.ini | sed 's/\[env:\(.*\)\]/\1/'); do
+          while IFS= read -r env; do
             echo "Building $env..."
             pio run -e "$env"
-          done
+          done < <(grep -oE '^\[env:([a-zA-Z0-9_-]+-release)\]' platformio.ini | sed 's/\[env:\(.*\)\]/\1/')
 
       # --- Flash tool + GitHub Release ---
 
diff --git a/.gitignore b/.gitignore
index 579f249..fd037b4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .pio
 .cache
+compile_commands.json
 firmware/compile_commands.json
 firmware/src/web_assets.h
 frontend/node_modules
diff --git a/AGENTS.md b/AGENTS.md
index e0ba1dd..b175d41 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,6 +77,9 @@ Verify frontend changes: `npm run check` + `npm run build` in `frontend/`.
 
 Verify flash tool changes: `golangci-lint run ./...` + `go build` in `flash/`.
 
+Verify GitHub Actions workflow changes: install `actionlint` if missing, then run
+`actionlint` from the repository root.
+
 ### Frontend
 
 ```bash

From 181fa4fc12e1e33c0d283a859e218cd92cdd221f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Thu, 7 May 2026 13:40:18 +0300
Subject: [PATCH 15/44] ci: support prerelease dispatch for fork PRs

---
 .github/workflows/prerelease.yml    | 6 +++++-
 .github/workflows/slash-command.yml | 3 +--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 53adb21..53b7d5c 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -22,6 +22,7 @@ jobs:
       pr_number: ${{ steps.resolve.outputs.pr_number }}
       head_sha: ${{ steps.resolve.outputs.head_sha }}
       head_ref: ${{ steps.resolve.outputs.head_ref }}
+      checkout_ref: ${{ steps.resolve.outputs.checkout_ref }}
       release_tag: ${{ steps.resolve.outputs.tag }}
       version: ${{ steps.resolve.outputs.version }}
 
@@ -37,9 +38,11 @@ jobs:
             PR_JSON=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid,headRefName)
             HEAD_SHA=$(echo "$PR_JSON" | jq -r '.headRefOid')
             HEAD_REF=$(echo "$PR_JSON" | jq -r '.headRefName')
+            CHECKOUT_REF="refs/pull/$PR_NUMBER/head"
           else
             HEAD_SHA="$GITHUB_SHA"
             HEAD_REF="$GITHUB_REF_NAME"
+            CHECKOUT_REF="$GITHUB_SHA"
           fi
 
           LATEST_TAG=$(gh release list --repo "$GITHUB_REPOSITORY" \
@@ -59,6 +62,7 @@ jobs:
             echo "pr_number=$PR_NUMBER"
             echo "head_sha=$HEAD_SHA"
             echo "head_ref=$HEAD_REF"
+            echo "checkout_ref=$CHECKOUT_REF"
             echo "tag=$TAG"
             echo "version=${TAG#v}"
           } >> "$GITHUB_OUTPUT"
@@ -73,7 +77,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          ref: ${{ needs.resolve.outputs.head_sha }}
+          ref: ${{ needs.resolve.outputs.checkout_ref }}
           fetch-depth: 0
 
       - name: Create release tag
diff --git a/.github/workflows/slash-command.yml b/.github/workflows/slash-command.yml
index 95398d1..94952da 100644
--- a/.github/workflows/slash-command.yml
+++ b/.github/workflows/slash-command.yml
@@ -28,8 +28,7 @@ jobs:
             -f content='rocket' --silent
 
           PR_NUMBER="${{ github.event.issue.number }}"
-          HEAD_REF=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefName --jq '.headRefName')
 
-          gh workflow run prerelease.yml --repo "$GITHUB_REPOSITORY" --ref "$HEAD_REF" \
+          gh workflow run prerelease.yml --repo "$GITHUB_REPOSITORY" --ref "${{ github.event.repository.default_branch }}" \
             -f pr_number="$PR_NUMBER" \
             -f comment_id="${{ github.event.comment.id }}"

From 0379c26a361d12c7b0b86c5a11f4e41ce8f86165 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Thu, 14 May 2026 20:17:32 +0300
Subject: [PATCH 16/44] feat: detailed battery information in settings (#121)

---
 README.md                                     |   4 +-
 docs/user-guide.md                            |   9 +-
 firmware/src/neato_commands.cpp               | 105 +++++++++-
 firmware/src/neato_commands.h                 |  29 +++
 firmware/src/neato_serial.cpp                 |  61 ++++++
 firmware/src/neato_serial.h                   |   7 +
 firmware/src/web_server.cpp                   |   4 +-
 frontend/api/openapi.yaml                     | 142 ++++++++++---
 frontend/mock/server.js                       |  49 ++++-
 frontend/package-lock.json                    |  10 +-
 frontend/package.json                         |   4 +-
 frontend/src/api.ts                           |  14 +-
 frontend/src/app.tsx                          |   4 +
 frontend/src/assets/icons/battery.svg         |   5 -
 frontend/src/style.css                        |  98 +++++++++
 frontend/src/types.ts                         |   2 +
 frontend/src/views/battery.tsx                |  30 +++
 frontend/src/views/settings.tsx               |  12 +-
 .../settings/battery-diagnostics-section.tsx  | 198 ++++++++++++++++++
 19 files changed, 721 insertions(+), 66 deletions(-)
 delete mode 100644 frontend/src/assets/icons/battery.svg
 create mode 100644 frontend/src/views/battery.tsx
 create mode 100644 frontend/src/views/settings/battery-diagnostics-section.tsx

diff --git a/README.md b/README.md
index e0f4186..19eccb7 100644
--- a/README.md
+++ b/README.md
@@ -55,8 +55,8 @@ port, giving you a local web interface that works without any external dependenc
 - **OTA firmware updates** from the browser with SHA-256 download verification (against published `checksums.txt`), MD5
   transfer integrity, dual-partition layout with auto-rollback, and automatic new version notifications when a release
   is available on GitHub
-- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto), and
-  more
+- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto),
+  battery diagnostics (cycle count, voltage, temperature, and a "New Battery" calibration trigger), and more
 - **Event logging** with configurable log levels (off/info/debug), compressed JSONL files on SPIFFS, browsable and
   downloadable from the UI; optional remote syslog (UDP) for long-running diagnostics without flash wear; logging is
   off by default
diff --git a/docs/user-guide.md b/docs/user-guide.md
index f6c21b8..90c2e18 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -471,6 +471,11 @@ Go to **Settings -> Diagnostics** and set **Log Level**:
 - **Debug** — everything in Info plus all serial commands with raw responses. Auto-reverts to
   off after 10 minutes.
 
+The Diagnostics section also shows a **Battery diagnostics** card with live readings from the
+robot: charge percentage, voltage, current, temperature, cycle count, and chemistry details.
+If you replace the battery, use the **New Battery** button to reset the fuel gauge calibration
+(only after physically installing the new pack).
+
 For long-running diagnostics (e.g. catching an intermittent error that only appears after
 hours of idling), enable **Remote Syslog** in the same section. This sends all log output
 over UDP (port 514) to a syslog receiver on your network instead of writing to flash. The
@@ -653,9 +658,9 @@ A few typical maintenance tasks:
 
 ```bash
 # New battery installed (resets fuel gauge calibration, requires TestMode)
-curl -X POST 'http://neato.local/api/testmode?enable=1'
+curl -X POST 'http://neato.local/api/serial?cmd=TestMode%20On'
 curl -X POST 'http://neato.local/api/serial?cmd=NewBattery'
-curl -X POST 'http://neato.local/api/testmode?enable=0'
+curl -X POST 'http://neato.local/api/serial?cmd=TestMode%20Off'
 
 # Reset robot user settings to factory defaults
 curl -X POST 'http://neato.local/api/serial?cmd=SetUserSettings%20Reset'
diff --git a/firmware/src/neato_commands.cpp b/firmware/src/neato_commands.cpp
index 42c124e..e63a532 100644
--- a/firmware/src/neato_commands.cpp
+++ b/firmware/src/neato_commands.cpp
@@ -168,8 +168,9 @@ static bool findCsvValue(const String& raw, const String& label, String& value)
             if (key == label) {
                 value = line.substring(comma + 1);
                 value.trim();
-                // Strip trailing comma if present (GetAnalogSensors format)
-                if (value.endsWith(",")) {
+                // Strip trailing commas (GetAnalogSensors and GetVersion formats
+                // may have one or more trailing commas for empty fields)
+                while (value.endsWith(",")) {
                     value = value.substring(0, value.length() - 1);
                 }
                 return true;
@@ -190,6 +191,14 @@ std::vector<Field> VersionData::toFields() const {
             {"ldsVersion", ldsVersion, FIELD_STRING},
             {"ldsSerial", ldsSerial, FIELD_STRING},
             {"mainBoardVersion", mainBoardVersion, FIELD_STRING},
+            {"smartBatteryAuthorization", String(smartBatteryAuthorization), FIELD_INT},
+            {"smartBatteryDataVersion", String(smartBatteryDataVersion), FIELD_INT},
+            {"smartBatteryChemistry", smartBatteryChemistry, FIELD_STRING},
+            {"smartBatteryDeviceName", smartBatteryDeviceName, FIELD_STRING},
+            {"smartBatteryManufacturerName", smartBatteryManufacturerName, FIELD_STRING},
+            {"smartBatteryMfgDate", smartBatteryMfgDate, FIELD_STRING},
+            {"smartBatterySerialNumber", smartBatterySerialNumber, FIELD_STRING},
+            {"smartBatterySoftwareVersion", smartBatterySoftwareVersion, FIELD_STRING},
     };
 }
 
@@ -211,6 +220,23 @@ std::vector<Field> ChargerData::toFields() const {
     };
 }
 
+std::vector<Field> BatteryAnalogData::toFields() const {
+    return {
+            {"batteryVoltageV", String(batteryVoltageV, 3), FIELD_FLOAT},
+            {"batteryCurrentMA", String(batteryCurrentMA), FIELD_INT},
+            {"batteryTemperatureC", String(batteryTemperatureC, 2), FIELD_FLOAT},
+            {"externalVoltageV", String(externalVoltageV, 3), FIELD_FLOAT},
+    };
+}
+
+std::vector<Field> BatteryWarrantyData::toFields() const {
+    return {
+            {"cumulativeCleaningTimeSeconds", String(cumulativeCleaningTimeSeconds), FIELD_INT},
+            {"cumulativeBatteryCycles", String(cumulativeBatteryCycles), FIELD_INT},
+            {"validationCode", validationCode, FIELD_STRING},
+    };
+}
+
 std::vector<Field> DigitalSensorData::toFields() const {
     return {
             {"dcJackIn", dcJackIn ? "true" : "false", FIELD_BOOL},
@@ -324,6 +350,24 @@ bool parseVersionData(const String& raw, VersionData& out) {
         out.mainBoardVersion = val;
         out.mainBoardVersion.replace(",", ".");
     }
+    if (findCsvValue(raw, "SmartBatt Authorization", val))
+        out.smartBatteryAuthorization = val.toInt();
+    if (findCsvValue(raw, "SmartBatt Data Version", val))
+        out.smartBatteryDataVersion = val.toInt();
+    if (findCsvValue(raw, "SmartBatt Device Chemistry", val))
+        out.smartBatteryChemistry = val;
+    if (findCsvValue(raw, "SmartBatt Device Name", val))
+        out.smartBatteryDeviceName = val;
+    if (findCsvValue(raw, "SmartBatt Manufacturer Name", val))
+        out.smartBatteryManufacturerName = val;
+    if (findCsvValue(raw, "SmartBatt Mfg Year/Month/Day", val)) {
+        val.replace(",", "-");
+        out.smartBatteryMfgDate = val;
+    }
+    if (findCsvValue(raw, "SmartBatt Serial Number", val))
+        out.smartBatterySerialNumber = val;
+    if (findCsvValue(raw, "SmartBatt Software Version", val))
+        out.smartBatterySoftwareVersion = val;
     // Parse "Time UTC" field, format: "Sat Apr 11 19:26:13 2026"
     if (findCsvValue(raw, "Time UTC", val)) {
         val.trim();
@@ -360,6 +404,63 @@ bool parseVersionData(const String& raw, VersionData& out) {
     return out.modelName.length() > 0 || out.softwareVersion.length() > 0;
 }
 
+static int parseHexValue(const String& value) {
+    char *end = nullptr;
+    long out = strtol(value.c_str(), &end, 16);
+    if (end == value.c_str())
+        return 0;
+    return static_cast<int>(out);
+}
+
+static String csvLastField(const String& value) {
+    int comma = value.lastIndexOf(',');
+    if (comma < 0)
+        return value;
+    String last = value.substring(comma + 1);
+    last.trim();
+    return last;
+}
+
+bool parseBatteryAnalogData(const String& raw, BatteryAnalogData& out) {
+    String val;
+    bool found = false;
+    if (findCsvValue(raw, "BatteryVoltage", val)) {
+        out.batteryVoltageV = csvLastField(val).toFloat() / 1000.0f;
+        found = true;
+    }
+    if (findCsvValue(raw, "BatteryCurrent", val)) {
+        out.batteryCurrentMA = csvLastField(val).toInt();
+        found = true;
+    }
+    if (findCsvValue(raw, "BatteryTemperature", val)) {
+        out.batteryTemperatureC = csvLastField(val).toFloat() / 1000.0f;
+        found = true;
+    }
+    if (findCsvValue(raw, "ExternalVoltage", val)) {
+        out.externalVoltageV = csvLastField(val).toFloat() / 1000.0f;
+        found = true;
+    }
+    return found;
+}
+
+bool parseBatteryWarrantyData(const String& raw, BatteryWarrantyData& out) {
+    String val;
+    bool found = false;
+    if (findCsvValue(raw, "CumulativeCleaningTimeInSecs", val)) {
+        out.cumulativeCleaningTimeSeconds = parseHexValue(val);
+        found = true;
+    }
+    if (findCsvValue(raw, "CumulativeBatteryCycles", val)) {
+        out.cumulativeBatteryCycles = parseHexValue(val);
+        found = true;
+    }
+    if (findCsvValue(raw, "ValidationCode", val)) {
+        out.validationCode = val;
+        found = true;
+    }
+    return found;
+}
+
 bool parseChargerData(const String& raw, ChargerData& out) {
     String val;
     if (findCsvValue(raw, "FuelPercent", val))
diff --git a/firmware/src/neato_commands.h b/firmware/src/neato_commands.h
index 79a1e37..472210d 100644
--- a/firmware/src/neato_commands.h
+++ b/firmware/src/neato_commands.h
@@ -9,6 +9,7 @@
 
 #define CMD_GET_VERSION "GetVersion"
 #define CMD_GET_CHARGER "GetCharger"
+#define CMD_GET_ANALOG_SENSORS "GetAnalogSensors"
 #define CMD_GET_DIGITAL_SENSORS "GetDigitalSensors"
 #define CMD_GET_MOTORS "GetMotors"
 #define CMD_GET_STATE "GetState"
@@ -46,6 +47,7 @@
 #define CMD_GET_USER_SETTINGS "GetUserSettings"
 #define CMD_SET_USER_SETTINGS "SetUserSettings"
 #define CMD_SET_NAVIGATION_MODE "SetNavigationMode"
+#define CMD_NEW_BATTERY "NewBattery"
 
 // -- Sound IDs ---------------------------------------------------------------
 
@@ -83,6 +85,14 @@ struct VersionData : public JsonSerializable {
     String ldsSerial;
     String mainBoardVersion;
     time_t timeUtc = 0; // Parsed from "Time UTC" field (0 = not available)
+    int smartBatteryAuthorization = 0;
+    int smartBatteryDataVersion = 0;
+    String smartBatteryChemistry;
+    String smartBatteryDeviceName;
+    String smartBatteryManufacturerName;
+    String smartBatteryMfgDate;
+    String smartBatterySerialNumber;
+    String smartBatterySoftwareVersion;
 
     std::vector<Field> toFields() const override;
 };
@@ -105,6 +115,23 @@ struct ChargerData : public JsonSerializable {
     std::vector<Field> toFields() const override;
 };
 
+struct BatteryAnalogData : public JsonSerializable {
+    float batteryVoltageV = 0.0f;
+    int batteryCurrentMA = 0;
+    float batteryTemperatureC = 0.0f;
+    float externalVoltageV = 0.0f;
+
+    std::vector<Field> toFields() const override;
+};
+
+struct BatteryWarrantyData : public JsonSerializable {
+    int cumulativeCleaningTimeSeconds = 0;
+    int cumulativeBatteryCycles = 0;
+    String validationCode;
+
+    std::vector<Field> toFields() const override;
+};
+
 struct DigitalSensorData : public JsonSerializable {
     bool dcJackIn = false;
     bool dustbinIn = false;
@@ -210,6 +237,8 @@ struct RobotPosData : public JsonSerializable {
 
 bool parseVersionData(const String& raw, VersionData& out);
 bool parseChargerData(const String& raw, ChargerData& out);
+bool parseBatteryAnalogData(const String& raw, BatteryAnalogData& out);
+bool parseBatteryWarrantyData(const String& raw, BatteryWarrantyData& out);
 bool parseDigitalSensorData(const String& raw, DigitalSensorData& out);
 bool parseMotorData(const String& raw, MotorData& out);
 bool parseRobotState(const String& raw, RobotState& out);
diff --git a/firmware/src/neato_serial.cpp b/firmware/src/neato_serial.cpp
index 9244c45..96fb3e0 100644
--- a/firmware/src/neato_serial.cpp
+++ b/firmware/src/neato_serial.cpp
@@ -18,6 +18,12 @@ NeatoSerial::NeatoSerial() :
     chargerCache(
             CACHE_TTL_CHARGER, [this](AsyncCache<ChargerData>::Callback cb) { fetchCharger(cb); },
             CACHE_HIT(CMD_GET_CHARGER)),
+    analogCache(
+            CACHE_TTL_SENSORS, [this](AsyncCache<BatteryAnalogData>::Callback cb) { fetchBatteryAnalog(cb); },
+            CACHE_HIT(CMD_GET_ANALOG_SENSORS)),
+    warrantyCache(
+            CACHE_TTL_VERSION, [this](AsyncCache<BatteryWarrantyData>::Callback cb) { fetchBatteryWarranty(cb); },
+            CACHE_HIT(CMD_GET_WARRANTY)),
     digitalCache(
             CACHE_TTL_SENSORS, [this](AsyncCache<DigitalSensorData>::Callback cb) { fetchDigitalSensors(cb); },
             CACHE_HIT(CMD_GET_DIGITAL_SENSORS)),
@@ -291,6 +297,14 @@ void NeatoSerial::getCharger(std::function<void(bool, const ChargerData&)> callb
     chargerCache.get(callback);
 }
 
+void NeatoSerial::getBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
+    analogCache.get(callback);
+}
+
+void NeatoSerial::getBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
+    warrantyCache.get(callback);
+}
+
 void NeatoSerial::getUserSettings(std::function<void(bool, const UserSettingsData&)> callback) {
     userSettingsCache.get(callback);
 }
@@ -383,6 +397,26 @@ void NeatoSerial::fetchCharger(std::function<void(bool, const ChargerData&)> cal
     });
 }
 
+void NeatoSerial::fetchBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
+    enqueue(CMD_GET_ANALOG_SENSORS, [callback](bool ok, const String& raw) {
+        BatteryAnalogData data;
+        if (ok)
+            ok = parseBatteryAnalogData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
+    enqueue(CMD_GET_WARRANTY, [callback](bool ok, const String& raw) {
+        BatteryWarrantyData data;
+        if (ok)
+            ok = parseBatteryWarrantyData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
 void NeatoSerial::fetchDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
                                       CommandPriority priority) {
     enqueue(
@@ -480,6 +514,8 @@ void NeatoSerial::invalidateState() {
 void NeatoSerial::invalidateAll() {
     versionCache.invalidate();
     chargerCache.invalidate();
+    analogCache.invalidate();
+    warrantyCache.invalidate();
     digitalCache.invalidate();
     motorCache.invalidate();
     stateCache.invalidate();
@@ -696,6 +732,31 @@ bool NeatoSerial::clearErrors(std::function<void(bool)> callback) {
     return enqueue(CMD_SET_UI_ERROR_CLEAR_ALL, wrapAction(callback));
 }
 
+bool NeatoSerial::newBattery(std::function<void(bool)> callback) {
+    invalidateState();
+    return testMode(true, [this, callback](bool ok) {
+        if (!ok) {
+            if (callback)
+                callback(false);
+            return;
+        }
+
+        enqueue(
+                CMD_NEW_BATTERY,
+                [this, callback](bool okCmd, const String&) {
+                    if (!okCmd) {
+                        // Best-effort return robot to normal mode even if NewBattery failed
+                        testMode(false, nullptr);
+                        if (callback)
+                            callback(false);
+                        return;
+                    }
+                    testMode(false, callback);
+                },
+                PRIORITY_HIGH);
+    });
+}
+
 bool NeatoSerial::sendRaw(const String& cmd, std::function<void(bool, const String&)> callback) {
     if (cmd.isEmpty())
         return false;
diff --git a/firmware/src/neato_serial.h b/firmware/src/neato_serial.h
index 31546c4..2d6346f 100644
--- a/firmware/src/neato_serial.h
+++ b/firmware/src/neato_serial.h
@@ -49,6 +49,8 @@ class NeatoSerial : public LoopTask {
 
     void getVersion(std::function<void(bool, const VersionData&)> callback);
     void getCharger(std::function<void(bool, const ChargerData&)> callback);
+    void getBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback);
+    void getBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback);
     void getUserSettings(std::function<void(bool, const UserSettingsData&)> callback);
     void getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback);
     void getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback, CommandPriority priority);
@@ -85,6 +87,7 @@ class NeatoSerial : public LoopTask {
 
     // Clear all UI errors/warnings via "SetUIError clearall".
     bool clearErrors(std::function<void(bool)> callback = nullptr);
+    bool newBattery(std::function<void(bool)> callback = nullptr);
 
     // -- Raw command (temporary debug endpoint) --------------------------------
     bool sendRaw(const String& cmd, std::function<void(bool, const String&)> callback);
@@ -188,6 +191,8 @@ class NeatoSerial : public LoopTask {
 
     AsyncCache<VersionData> versionCache;
     AsyncCache<ChargerData> chargerCache;
+    AsyncCache<BatteryAnalogData> analogCache;
+    AsyncCache<BatteryWarrantyData> warrantyCache;
     AsyncCache<DigitalSensorData> digitalCache;
     AsyncCache<MotorData> motorCache;
     AsyncCache<RobotState> stateCache;
@@ -200,6 +205,8 @@ class NeatoSerial : public LoopTask {
     // Raw (uncached) fetch methods — enqueue the command and parse response
     void fetchVersion(std::function<void(bool, const VersionData&)> callback);
     void fetchCharger(std::function<void(bool, const ChargerData&)> callback);
+    void fetchBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback);
+    void fetchBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback);
     void fetchDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
                              CommandPriority priority = PRIORITY_NORMAL);
     void fetchMotors(std::function<void(bool, const MotorData&)> callback, CommandPriority priority = PRIORITY_NORMAL);
diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index 17411e6..6c8c8b1 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -82,6 +82,8 @@ void WebServer::registerApiRoutes() {
 
     registerGetRoute("/api/version", neato, &NeatoSerial::getVersion, {});
     registerGetRoute("/api/charger", neato, &NeatoSerial::getCharger, {});
+    registerGetRoute("/api/analog", neato, &NeatoSerial::getBatteryAnalog, {});
+    registerGetRoute("/api/warranty", neato, &NeatoSerial::getBatteryWarranty, {});
     registerGetRoute(
             "/api/motors", neato,
             static_cast<void (NeatoSerial::*)(std::function<void(bool, const MotorData&)>)>(&NeatoSerial::getMotors),
@@ -97,11 +99,11 @@ void WebServer::registerApiRoutes() {
 
     registerPostRoute("/api/clean", neato, &NeatoSerial::clean, {"action"});
     registerPostRoute("/api/sound", neato, &NeatoSerial::playSound, {"id"});
-    registerPostRoute("/api/testmode", neato, &NeatoSerial::testMode, {"enable"});
     registerPostRoute("/api/power", neato, &NeatoSerial::powerControl, {"action"});
     registerPostRoute("/api/lidar/rotate", neato, &NeatoSerial::setLdsRotation, {"enable"});
     registerPostRoute("/api/user-settings", neato, &NeatoSerial::setUserSetting, {"key", "value"});
     registerPostRoute("/api/clear-errors", neato, &NeatoSerial::clearErrors, {});
+    registerPostRoute("/api/battery/new", neato, &NeatoSerial::newBattery, {});
 
     // Serial endpoint — send arbitrary serial command, returns raw response.
     // Always available (no debug gate — useful for diagnostics without enabling verbose logging).
diff --git a/frontend/api/openapi.yaml b/frontend/api/openapi.yaml
index a462a30..dfa7fdc 100644
--- a/frontend/api/openapi.yaml
+++ b/frontend/api/openapi.yaml
@@ -65,6 +65,60 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /api/analog:
+    get:
+      tags:
+        - Sensors
+      summary: Get battery-related analog readings
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatteryAnalogData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/warranty:
+    get:
+      tags:
+        - Sensors
+      summary: Get battery cycle and lifetime counters
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatteryWarrantyData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/battery/new:
+    post:
+      tags:
+        - Actions
+      summary: Tell the robot a new battery has been installed (handles TestMode sequence internally)
+      responses:
+        "200":
+          description: Success acknowledgement
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ok"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
   /api/motors:
     get:
       tags:
@@ -245,34 +299,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-  /api/testmode:
-    post:
-      tags:
-        - Actions
-      summary: Enter or exit test mode (required for manual control)
-      parameters:
-        - name: enable
-          in: query
-          required: true
-          schema:
-            type: boolean
-            minimum: 0
-            maximum: 1
-      responses:
-        "200":
-          $ref: "#/components/responses/Ok"
-        "503":
-          description: robot busy
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-        "504":
-          description: robot timeout
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
   /api/power:
     post:
       tags:
@@ -866,6 +892,30 @@ components:
         mainBoardVersion:
           type: string
           description: Main board hardware version
+        smartBatteryAuthorization:
+          type: number
+          description: Smart battery authorization status reported by the robot
+        smartBatteryDataVersion:
+          type: number
+          description: Smart battery data block version
+        smartBatteryChemistry:
+          type: string
+          description: Battery chemistry, e.g. LION1
+        smartBatteryDeviceName:
+          type: string
+          description: Smart battery device name
+        smartBatteryManufacturerName:
+          type: string
+          description: Smart battery manufacturer name
+        smartBatteryMfgDate:
+          type: string
+          description: Smart battery manufacturing date as reported by the robot
+        smartBatterySerialNumber:
+          type: string
+          description: Smart battery serial number
+        smartBatterySoftwareVersion:
+          type: string
+          description: Smart battery controller software version
       required:
         - modelName
         - serialNumber
@@ -929,6 +979,42 @@ components:
         - vExtV
         - chargerMAH
         - dischargeMAH
+    BatteryAnalogData:
+      type: object
+      properties:
+        batteryVoltageV:
+          type: number
+          description: Battery pack voltage in volts from GetAnalogSensors
+        batteryCurrentMA:
+          type: number
+          description: Live battery current in mA from GetAnalogSensors
+        batteryTemperatureC:
+          type: number
+          description: Battery temperature in Celsius from GetAnalogSensors
+        externalVoltageV:
+          type: number
+          description: External supply voltage in volts from GetAnalogSensors
+      required:
+        - batteryVoltageV
+        - batteryCurrentMA
+        - batteryTemperatureC
+        - externalVoltageV
+    BatteryWarrantyData:
+      type: object
+      properties:
+        cumulativeBatteryCycles:
+          type: number
+          description: Lifetime battery cycles decoded from GetWarranty
+        cumulativeCleaningTimeSeconds:
+          type: number
+          description: Lifetime cleaning time decoded from GetWarranty
+        validationCode:
+          type: string
+          description: Validation code reported by GetWarranty
+      required:
+        - cumulativeBatteryCycles
+        - cumulativeCleaningTimeSeconds
+        - validationCode
     MotorData:
       type: object
       properties:
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index 28bf171..4631301 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -241,7 +241,6 @@ const state = {
     errorCode: 200,
     errorMessage: "",
     displayMessage: "",
-    testMode: false,
     manualClean: false,
     // Manual clean motor + safety state
     manualBrush: false,
@@ -459,9 +458,6 @@ const deriveStates = () => {
     if (state.manualClean) {
         state.uiState = "UIMGR_STATE_MANUALCLEANING";
         state.robotState = "ST_C_ManualCleaning";
-    } else if (state.testMode) {
-        state.uiState = "UIMGR_STATE_TESTMODE";
-        state.robotState = "ST_C_TestMode";
     } else if (state.midCleanRecharge) {
         state.uiState = "UIMGR_STATE_CLEANINGSUSPENDED";
         state.robotState = "ST_M1_Charging_Cleaning";
@@ -498,6 +494,14 @@ const routes = {
             ldsVersion: "V2.6.15295",
             ldsSerial: "KSH-V5F4",
             mainBoardVersion: "15.0",
+            smartBatteryAuthorization: 1,
+            smartBatteryDataVersion: 512,
+            smartBatteryChemistry: "LION1",
+            smartBatteryDeviceName: "F164A10288",
+            smartBatteryManufacturerName: "Panasonic",
+            smartBatteryMfgDate: "2089-02-18",
+            smartBatterySerialNumber: "34832",
+            smartBatterySoftwareVersion: "2048",
         });
     },
 
@@ -521,6 +525,36 @@ const routes = {
         });
     },
 
+    "GET /api/analog": (_req, res) => {
+        if (faults.pollCharger) return sendError(res, "UART timeout reading battery diagnostics", 500);
+        const fuel = Math.round(state.fuelPercent);
+        const batteryCurrentMA = state.chargingActive
+            ? rand(180, 720)
+            : state.extPwrPresent
+              ? rand(-20, 20)
+              : -rand(80, 420);
+        const batteryTemperatureC = parseFloat((24 + (state.chargingActive ? 1.8 : 0) + Math.random()).toFixed(1));
+
+        jsonResponse(res, {
+            batteryVoltageV: vBattFromFuel(fuel),
+            batteryCurrentMA,
+            batteryTemperatureC,
+            externalVoltageV: state.extPwrPresent ? 18.66 : 0.0,
+        });
+    },
+
+    "GET /api/warranty": (_req, res) => {
+        jsonResponse(res, {
+            cumulativeBatteryCycles: 728,
+            cumulativeCleaningTimeSeconds: 885884,
+            validationCode: "b40b2e9a",
+        });
+    },
+
+    "POST /api/battery/new": (_req, res) => {
+        jsonResponse(res, { ok: true });
+    },
+
     "GET /api/motors": (_req, res) => {
         const cleaning = state.cleaning || state.spotCleaning;
         jsonResponse(res, {
@@ -671,13 +705,6 @@ const routes = {
         sendOk(res);
     },
 
-    "POST /api/testmode": (_req, res, query) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        state.testMode = query.enable === "1";
-        deriveStates();
-        sendOk(res);
-    },
-
     "POST /api/manual": (_req, res, query) => {
         if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
         const enable = query.enable === "1";
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 27221fd..5341bbf 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,10 +13,10 @@
             "devDependencies": {
                 "@biomejs/biome": "2.4.13",
                 "@preact/preset-vite": "2.10.5",
-                "openapi-typescript": "^7.13.0",
+                "openapi-typescript": "7.13.0",
                 "typescript": "6.0.3",
                 "vite": "8.0.10",
-                "yaml": "^2.8.3"
+                "yaml": "2.8.3"
             }
         },
         "node_modules/@babel/code-frame": {
@@ -1977,9 +1977,9 @@
             }
         },
         "node_modules/postcss": {
-            "version": "8.5.12",
-            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
-            "integrity": "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==",
+            "version": "8.5.14",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
+            "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
             "dev": true,
             "funding": [
                 {
diff --git a/frontend/package.json b/frontend/package.json
index b55f8c5..34a2905 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -18,9 +18,9 @@
     "devDependencies": {
         "@biomejs/biome": "2.4.13",
         "@preact/preset-vite": "2.10.5",
-        "openapi-typescript": "^7.13.0",
+        "openapi-typescript": "7.13.0",
         "typescript": "6.0.3",
         "vite": "8.0.10",
-        "yaml": "^2.8.3"
+        "yaml": "2.8.3"
     }
 }
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index f85a0e3..e19621f 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,5 +1,7 @@
 import { parseMapData } from "./history-data";
 import type {
+    BatteryAnalogData,
+    BatteryWarrantyData,
     ChargerData,
     ErrorData,
     FirmwareVersion,
@@ -12,6 +14,7 @@ import type {
     StateData,
     SystemData,
     UserSettingsData,
+    VersionData,
     WiFiScanResult,
     WiFiStatus,
 } from "./types";
@@ -66,12 +69,6 @@ async function put<T>(url: string, body: unknown): Promise<T> {
     return res.json();
 }
 
-async function sendSerial(cmd: string): Promise<string> {
-    const res = await fetch(`/api/serial?cmd=${encodeURIComponent(cmd)}`, { method: "POST" });
-    if (!res.ok) throw new Error(await parseError(res));
-    return res.text();
-}
-
 async function fetchLogText(name: string): Promise<string> {
     const res = await fetch(`/api/logs/${name}`);
     if (!res.ok) throw new Error(await parseError(res));
@@ -141,8 +138,11 @@ function uploadFirmware(file: File, md5: string, onProgress: (pct: number) => vo
 }
 
 export const api = {
+    getVersion: () => get<VersionData>("/api/version"),
     getState: () => get<StateData>("/api/state"),
     getCharger: () => get<ChargerData>("/api/charger"),
+    getBatteryAnalog: () => get<BatteryAnalogData>("/api/analog"),
+    getBatteryWarranty: () => get<BatteryWarrantyData>("/api/warranty"),
     getError: () => get<ErrorData>("/api/error"),
     getSystem: () => get<SystemData>("/api/system"),
     getFirmwareVersion: () => get<FirmwareVersion>("/api/firmware/version"),
@@ -166,6 +166,7 @@ export const api = {
     clearErrors: () => post("/api/clear-errors"),
     robotRestart: () => post("/api/power?action=restart"),
     robotShutdown: () => post("/api/power?action=shutdown"),
+    newBattery: () => post("/api/battery/new"),
     restart: () => post("/api/system/restart"),
     formatFs: () => post("/api/system/format-fs"),
     factoryReset: () => post("/api/system/reset"),
@@ -185,7 +186,6 @@ export const api = {
     getUserSettings: () => get<UserSettingsData>("/api/user-settings"),
     setUserSetting: (key: string, value: string) =>
         post(`/api/user-settings?key=${encodeURIComponent(key)}&value=${encodeURIComponent(value)}`),
-    sendSerial: (cmd: string) => sendSerial(cmd),
 
     getWifiStatus: () => get<WiFiStatus>("/api/wifi/status"),
     scanWifi: () => get<WiFiScanResult>("/api/wifi/scan"),
diff --git a/frontend/src/app.tsx b/frontend/src/app.tsx
index 957ed80..9348222 100644
--- a/frontend/src/app.tsx
+++ b/frontend/src/app.tsx
@@ -4,6 +4,7 @@ import { Route, Router } from "./components/router";
 import { usePolling } from "./hooks/use-polling";
 import type { FirmwareVersion, ManualStatus, StateData } from "./types";
 import { checkForUpdate, getAvailableUpdate, type UpdateInfo } from "./update";
+import { BatteryView } from "./views/battery";
 import { DashboardView } from "./views/dashboard";
 import { HistoryView } from "./views/history";
 import { LogsView } from "./views/logs";
@@ -172,6 +173,9 @@ export function App() {
             <Route path="/schedule">
                 <ScheduleView />
             </Route>
+            <Route path="/battery">
+                <BatteryView firmwareSupported={firmware.data?.supported !== false} />
+            </Route>
             <Route path="/logs" prefix>
                 <LogsView />
             </Route>
diff --git a/frontend/src/assets/icons/battery.svg b/frontend/src/assets/icons/battery.svg
deleted file mode 100644
index aa42163..0000000
--- a/frontend/src/assets/icons/battery.svg
+++ /dev/null
@@ -1,5 +0,0 @@
-<svg viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
-  <polygon fill="#F9EBB2" points="56,36 48,36 48,44 8,44 8,20 48,20 48,28 56,28"/>
-  <polygon fill="#394240" points="12,40 32,40 40,24 12,24"/>
-  <path fill="#394240" d="M60,20h-4v-4c0-2.211-1.789-4-4-4H4c-2.211,0-4,1.789-4,4v32c0,2.211,1.789,4,4,4h48c2.211,0,4-1.789,4-4v-4h4c2.211,0,4-1.789,4-4V24C64,21.789,62.211,20,60,20z M56,36h-8v8H8V20h40v8h8V36z"/>
-</svg>
diff --git a/frontend/src/style.css b/frontend/src/style.css
index d9c8c90..cdabd8d 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -992,6 +992,104 @@ input:disabled {
     background: var(--text);
 }
 
+/* Battery diagnostics */
+
+.settings-battery-card {
+    padding: 14px;
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    background: var(--surface);
+}
+
+.settings-battery-header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 14px;
+}
+
+.settings-battery-title {
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--text);
+}
+
+.settings-battery-desc {
+    margin-top: 2px;
+    font-size: 12px;
+    color: var(--text);
+    opacity: 0.55;
+}
+
+.settings-battery-grid {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 8px;
+    margin-bottom: 10px;
+}
+
+.settings-battery-stat {
+    min-width: 0;
+    padding: 10px 12px;
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    background: var(--card-bg);
+}
+
+.settings-battery-stat span,
+.settings-battery-advanced span {
+    display: block;
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--text-dim);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+}
+
+.settings-battery-stat strong,
+.settings-battery-advanced strong {
+    display: block;
+    overflow: hidden;
+    margin-top: 2px;
+    color: var(--text);
+    font-size: 14px;
+    font-weight: 700;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.settings-battery-advanced {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 8px;
+    margin-bottom: 10px;
+}
+
+.settings-battery-advanced > div {
+    min-width: 0;
+    padding: 9px 10px;
+    border-radius: 10px;
+    background: rgba(255, 255, 255, 0.03);
+}
+
+.settings-battery-note {
+    display: block;
+    margin-top: 4px;
+    color: var(--text-dim);
+    font-size: 11px;
+    line-height: 1.3;
+}
+
+.settings-battery-empty {
+    padding: 12px;
+    border-radius: 12px;
+    background: var(--card-bg);
+    color: var(--text-dim);
+    font-size: 13px;
+    font-weight: 500;
+}
+
 /* Settings pin configuration */
 
 .settings-pin-row {
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index a23be6e..3dc80de 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -2,6 +2,8 @@
 // not this file. The build pipeline runs `openapi-typescript` to refresh
 // types.generated.ts before tsc.
 export type {
+    BatteryAnalogData,
+    BatteryWarrantyData,
     ChargerData,
     ErrorData,
     FirmwareVersion,
diff --git a/frontend/src/views/battery.tsx b/frontend/src/views/battery.tsx
new file mode 100644
index 0000000..f9cba9f
--- /dev/null
+++ b/frontend/src/views/battery.tsx
@@ -0,0 +1,30 @@
+import backSvg from "../assets/icons/back.svg?raw";
+import { ErrorBannerStack, useErrorStack } from "../components/error-banner";
+import { Icon } from "../components/icon";
+import { BatteryDiagnosticsSection } from "./settings/battery-diagnostics-section";
+
+interface BatteryViewProps {
+    firmwareSupported: boolean;
+}
+
+export function BatteryView({ firmwareSupported }: BatteryViewProps) {
+    const [errors, errorStack] = useErrorStack();
+
+    return (
+        <>
+            <div class="header">
+                <a href="#/settings" class="header-back-btn" aria-label="Back">
+                    <Icon svg={backSvg} />
+                </a>
+                <h1>Battery</h1>
+                <div class="header-right-spacer" />
+            </div>
+
+            <ErrorBannerStack errors={errors} />
+
+            <div class="schedule-page">
+                <BatteryDiagnosticsSection firmwareSupported={firmwareSupported} errorStack={errorStack} />
+            </div>
+        </>
+    );
+}
diff --git a/frontend/src/views/settings.tsx b/frontend/src/views/settings.tsx
index 64317d3..24b0e46 100644
--- a/frontend/src/views/settings.tsx
+++ b/frontend/src/views/settings.tsx
@@ -3,6 +3,7 @@ import { api } from "../api";
 import alertSvg from "../assets/icons/alert.svg?raw";
 import backSvg from "../assets/icons/back.svg?raw";
 import bellSvg from "../assets/icons/bell.svg?raw";
+import boltSvg from "../assets/icons/bolt.svg?raw";
 import calendarSvg from "../assets/icons/calendar.svg?raw";
 import chipSvg from "../assets/icons/chip.svg?raw";
 import databaseSvg from "../assets/icons/database.svg?raw";
@@ -815,7 +816,7 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
                     </div>
                 </SettingsCategory>
 
-                <SettingsCategory title="Diagnostics" icon={stethoscopeSvg}>
+                <SettingsCategory title="Diagnostics" icon={stethoscopeSvg} lazy>
                     <div class="settings-section">
                         <div class="settings-section-title">Log Level</div>
                         <div class="settings-tz-select-wrap">
@@ -866,6 +867,15 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
                             </>
                         )}
                     </div>
+                    <div class="settings-section">
+                        <button type="button" class="settings-nav-row" onClick={() => guardedNavigate("/battery")}>
+                            <div class="settings-nav-row-left">
+                                <Icon svg={boltSvg} />
+                                Battery Diagnostics
+                            </div>
+                            <span class="settings-nav-chevron">&rsaquo;</span>
+                        </button>
+                    </div>
                     <div class="settings-section">
                         <button type="button" class="settings-nav-row" onClick={() => guardedNavigate("/logs")}>
                             <div class="settings-nav-row-left">
diff --git a/frontend/src/views/settings/battery-diagnostics-section.tsx b/frontend/src/views/settings/battery-diagnostics-section.tsx
new file mode 100644
index 0000000..a7eed44
--- /dev/null
+++ b/frontend/src/views/settings/battery-diagnostics-section.tsx
@@ -0,0 +1,198 @@
+import { useCallback, useState } from "preact/hooks";
+import { api } from "../../api";
+import alertSvg from "../../assets/icons/alert.svg?raw";
+import { ConfirmDialog } from "../../components/confirm-dialog";
+import type { ErrorStackHandle } from "../../components/error-banner";
+import { Icon } from "../../components/icon";
+import { usePolling } from "../../hooks/use-polling";
+import type { BatteryAnalogData, BatteryWarrantyData, ChargerData, VersionData } from "../../types";
+import { normalizeError } from "../../utils";
+
+interface BatteryDiagnosticsSectionProps {
+    firmwareSupported: boolean;
+    errorStack: ErrorStackHandle;
+}
+
+function batteryStateLabel(charger: ChargerData): string {
+    if (charger.chargingActive) return "Charging";
+    if (charger.extPwrPresent) return "Docked";
+    return "On battery";
+}
+
+function formatHours(seconds: number): string {
+    return `${Math.round(seconds / 3600)} h`;
+}
+
+function mfgDateLooksUnreliable(version: VersionData | null | undefined): boolean {
+    if (!version?.smartBatteryMfgDate) return false;
+
+    const parts = version.smartBatteryMfgDate.split("-");
+    const year = Number(parts[0]);
+    if (!Number.isFinite(year)) return false;
+
+    const currentYear = new Date().getFullYear();
+    if (year <= currentYear) return false;
+
+    return true;
+}
+
+export function BatteryDiagnosticsSection({ firmwareSupported, errorStack }: BatteryDiagnosticsSectionProps) {
+    const chargerPoll = usePolling<ChargerData>(api.getCharger, 30000);
+    const analogPoll = usePolling<BatteryAnalogData>(api.getBatteryAnalog, 30000);
+    const warrantyPoll = usePolling<BatteryWarrantyData>(api.getBatteryWarranty, 60000);
+    const versionPoll = usePolling<VersionData>(api.getVersion, 60000);
+
+    const [showNewBatteryConfirm, setShowNewBatteryConfirm] = useState(false);
+    const [settingNewBattery, setSettingNewBattery] = useState(false);
+
+    const charger = chargerPoll.data;
+    const analog = analogPoll.data;
+    const warranty = warrantyPoll.data;
+    const version = versionPoll.data;
+    const showMfgDateNotice = mfgDateLooksUnreliable(version);
+
+    const handleNewBattery = useCallback(() => {
+        setShowNewBatteryConfirm(false);
+        setSettingNewBattery(true);
+        api.newBattery()
+            .catch((e: unknown) => {
+                errorStack.push(normalizeError(e, "Failed to set new battery"));
+            })
+            .finally(() => setSettingNewBattery(false));
+    }, [errorStack]);
+
+    const errorMessage = chargerPoll.error ?? analogPoll.error ?? warrantyPoll.error ?? versionPoll.error;
+
+    return (
+        <>
+            <div class="settings-section">
+                <div class="settings-battery-card">
+                    <div class="settings-battery-header">
+                        <div>
+                            <div class="settings-battery-title">Battery diagnostics</div>
+                            <div class="settings-battery-desc">
+                                Maintenance signals from charger, analog sensors, warranty data, and version metadata
+                            </div>
+                        </div>
+                    </div>
+
+                    {charger && analog && warranty ? (
+                        <>
+                            <div class="settings-battery-grid">
+                                <div class="settings-battery-stat">
+                                    <span>Charge</span>
+                                    <strong>{charger.fuelPercent}%</strong>
+                                </div>
+                                <div class="settings-battery-stat">
+                                    <span>State</span>
+                                    <strong>{batteryStateLabel(charger)}</strong>
+                                </div>
+                                <div class="settings-battery-stat">
+                                    <span>Voltage</span>
+                                    <strong>{charger.vBattV.toFixed(2)} V</strong>
+                                </div>
+                                <div class="settings-battery-stat">
+                                    <span>Temp</span>
+                                    <strong>{analog.batteryTemperatureC.toFixed(1)} C</strong>
+                                </div>
+                                <div class="settings-battery-stat">
+                                    <span>Cycles</span>
+                                    <strong>{warranty.cumulativeBatteryCycles}</strong>
+                                </div>
+                                <div class="settings-battery-stat">
+                                    <span>Pack</span>
+                                    <strong>{version?.smartBatteryManufacturerName || "Unknown"}</strong>
+                                </div>
+                            </div>
+
+                            <div class="settings-battery-advanced">
+                                <div>
+                                    <span>Current</span>
+                                    <strong>{analog.batteryCurrentMA} mA</strong>
+                                </div>
+                                <div>
+                                    <span>External voltage</span>
+                                    <strong>{analog.externalVoltageV.toFixed(2)} V</strong>
+                                </div>
+                                <div>
+                                    <span>Charging enabled</span>
+                                    <strong>{charger.chargingEnabled ? "Yes" : "No"}</strong>
+                                </div>
+                                <div>
+                                    <span>Fuel confidence</span>
+                                    <strong>{charger.confidOnFuel ? "Yes" : "No"}</strong>
+                                </div>
+                                <div>
+                                    <span>Reserved fuel</span>
+                                    <strong>{charger.onReservedFuel ? "Yes" : "No"}</strong>
+                                </div>
+                                <div>
+                                    <span>Charged</span>
+                                    <strong>{charger.chargerMAH} mAh</strong>
+                                </div>
+                                <div>
+                                    <span>Discharged</span>
+                                    <strong>{charger.dischargeMAH} mAh</strong>
+                                </div>
+                                <div>
+                                    <span>Cleaning time</span>
+                                    <strong>{formatHours(warranty.cumulativeCleaningTimeSeconds)}</strong>
+                                </div>
+                                <div>
+                                    <span>Chemistry</span>
+                                    <strong>{version?.smartBatteryChemistry || "Unknown"}</strong>
+                                </div>
+                                <div>
+                                    <span>Device</span>
+                                    <strong>{version?.smartBatteryDeviceName || "Unknown"}</strong>
+                                </div>
+                                <div>
+                                    <span>Serial</span>
+                                    <strong>{version?.smartBatterySerialNumber || "Unknown"}</strong>
+                                </div>
+                                <div>
+                                    <span>Mfg date</span>
+                                    <strong>{version?.smartBatteryMfgDate || "Unknown"}</strong>
+                                    {showMfgDateNotice && (
+                                        <small class="settings-battery-note">
+                                            Reported by robot firmware, may be unreliable.
+                                        </small>
+                                    )}
+                                </div>
+                            </div>
+
+                            <button
+                                type="button"
+                                class={`settings-nav-row${settingNewBattery ? " pending" : ""}`}
+                                onClick={() => setShowNewBatteryConfirm(true)}
+                                disabled={settingNewBattery || !firmwareSupported}
+                            >
+                                <div class="settings-nav-row-left">
+                                    <Icon svg={alertSvg} />
+                                    {settingNewBattery ? "Applying..." : "New Battery"}
+                                </div>
+                            </button>
+                            <div class="settings-robot-time">
+                                Use only after physically installing a replacement battery.
+                            </div>
+                        </>
+                    ) : (
+                        <div class="settings-battery-empty">{errorMessage ?? "Loading battery diagnostics..."}</div>
+                    )}
+                </div>
+            </div>
+
+            {showNewBatteryConfirm && (
+                <ConfirmDialog
+                    message="This resets the battery fuel gauge and calibration data. Only use this after physically replacing the battery. The charge percentage may be inaccurate for a few cycles until the system relearns the battery capacity."
+                    confirmLabel="New Battery"
+                    confirmText="NEW BATTERY"
+                    destructive
+                    disabled={settingNewBattery}
+                    onConfirm={handleNewBattery}
+                    onCancel={() => setShowNewBatteryConfirm(false)}
+                />
+            )}
+        </>
+    );
+}

From 09e90b0b02dcfec3d4793ddd2b24e7ac60820764 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Thu, 14 May 2026 21:37:42 +0300
Subject: [PATCH 17/44] chore: bump pinned dependencies across frontend,
 firmware, and flash

---
 flash/go.mod               |   4 +-
 flash/go.sum               |   8 +-
 frontend/biome.json        |   2 +-
 frontend/package-lock.json | 250 ++++++++++++++++++-------------------
 frontend/package.json      |  14 +--
 platformio.ini             |   7 +-
 6 files changed, 144 insertions(+), 141 deletions(-)

diff --git a/flash/go.mod b/flash/go.mod
index d807f71..b8aee35 100644
--- a/flash/go.mod
+++ b/flash/go.mod
@@ -4,10 +4,10 @@ go 1.26.2
 
 require (
 	go.bug.st/serial v1.6.4
-	golang.org/x/term v0.42.0
+	golang.org/x/term v0.43.0
 )
 
 require (
 	github.com/creack/goselect v0.1.3 // indirect
-	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
 )
diff --git a/flash/go.sum b/flash/go.sum
index d483e31..e98a5b8 100644
--- a/flash/go.sum
+++ b/flash/go.sum
@@ -8,9 +8,9 @@ github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcU
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 go.bug.st/serial v1.6.4 h1:7FmqNPgVp3pu2Jz5PoPtbZ9jJO5gnEnZIvnI1lzve8A=
 go.bug.st/serial v1.6.4/go.mod h1:nofMJxTeNVny/m6+KaafC6vJGj3miwQZ6vW4BZUGJPI=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/frontend/biome.json b/frontend/biome.json
index 1f69473..348d0f8 100644
--- a/frontend/biome.json
+++ b/frontend/biome.json
@@ -1,5 +1,5 @@
 {
-    "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
 
     "files": {
         "includes": [
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 5341bbf..1c0b36f 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,15 +8,15 @@
             "name": "neato-web",
             "version": "0.0.1",
             "dependencies": {
-                "preact": "10.29.1"
+                "preact": "^10.29.1"
             },
             "devDependencies": {
-                "@biomejs/biome": "2.4.13",
-                "@preact/preset-vite": "2.10.5",
-                "openapi-typescript": "7.13.0",
-                "typescript": "6.0.3",
-                "vite": "8.0.10",
-                "yaml": "2.8.3"
+                "@biomejs/biome": "^2.4.15",
+                "@preact/preset-vite": "^2.10.5",
+                "openapi-typescript": "^7.13.0",
+                "typescript": "^6.0.3",
+                "vite": "^8.0.13",
+                "yaml": "^2.9.0"
             }
         },
         "node_modules/@babel/code-frame": {
@@ -335,9 +335,9 @@
             }
         },
         "node_modules/@biomejs/biome": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.13.tgz",
-            "integrity": "sha512-gLXOwkOBBg0tr7bDsqlkIh4uFeKuMjxvqsrb1Tukww1iDmHcfr4Uu8MoQxp0Rcte+69+osRNWXwHsu/zxT6XqA==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.15.tgz",
+            "integrity": "sha512-j5VH3a/h/HXTKBM50MDMxRCzkeLv9S2XJcW2WgnZT1+xyisi+0bISrXR82gCX+8S9lvK0skEvHJRN+3Ktr2hlw==",
             "dev": true,
             "license": "MIT OR Apache-2.0",
             "bin": {
@@ -351,20 +351,20 @@
                 "url": "https://opencollective.com/biome"
             },
             "optionalDependencies": {
-                "@biomejs/cli-darwin-arm64": "2.4.13",
-                "@biomejs/cli-darwin-x64": "2.4.13",
-                "@biomejs/cli-linux-arm64": "2.4.13",
-                "@biomejs/cli-linux-arm64-musl": "2.4.13",
-                "@biomejs/cli-linux-x64": "2.4.13",
-                "@biomejs/cli-linux-x64-musl": "2.4.13",
-                "@biomejs/cli-win32-arm64": "2.4.13",
-                "@biomejs/cli-win32-x64": "2.4.13"
+                "@biomejs/cli-darwin-arm64": "2.4.15",
+                "@biomejs/cli-darwin-x64": "2.4.15",
+                "@biomejs/cli-linux-arm64": "2.4.15",
+                "@biomejs/cli-linux-arm64-musl": "2.4.15",
+                "@biomejs/cli-linux-x64": "2.4.15",
+                "@biomejs/cli-linux-x64-musl": "2.4.15",
+                "@biomejs/cli-win32-arm64": "2.4.15",
+                "@biomejs/cli-win32-x64": "2.4.15"
             }
         },
         "node_modules/@biomejs/cli-darwin-arm64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.13.tgz",
-            "integrity": "sha512-2KImO1jhNFBa2oWConyr0x6flxbQpGKv6902uGXpYM62Xyem8U80j441SyUJ8KyngsmKbQjeIv1q2CQfDkNnYg==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.15.tgz",
+            "integrity": "sha512-rF3PPqLq1yoST79zaQbDjVJwsuIeci/O+9bgNmC5QpgOqz6aqYuzA4abyAGx+mgyiDXn4A049xAN8gijbuR1Qg==",
             "cpu": [
                 "arm64"
             ],
@@ -379,9 +379,9 @@
             }
         },
         "node_modules/@biomejs/cli-darwin-x64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.13.tgz",
-            "integrity": "sha512-BKrJklbaFN4p1Ts4kPBczo+PkbsHQg57kmJ+vON9u2t6uN5okYHaSr7h/MutPCWQgg2lglaWoSmm+zhYW+oOkg==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.15.tgz",
+            "integrity": "sha512-/5KHXYMfSJs1fNXiX30xFtI8JcCFV6zaVVLxOa0M2sfqBKHkpQhRTv94yxQWxeTY2lzo2OuTlNvPC+hDQt2wcQ==",
             "cpu": [
                 "x64"
             ],
@@ -396,9 +396,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.13.tgz",
-            "integrity": "sha512-NzkUDSqfvMBrPplKgVr3aXLHZ2NEELvvF4vZxXulEylKWIGqlvNEcwUcj9OLrn75TD3lJ/GIqCVlBwd1MZCuYQ==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.15.tgz",
+            "integrity": "sha512-owaAMZD/T4LrD0ELNCk0Km3qrRHuM0X6EAyVE1FSqGY0rbLoiDLrO4Us2tllm6cAeB2Ioa9C2C08NZPdr8+0Ug==",
             "cpu": [
                 "arm64"
             ],
@@ -416,9 +416,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64-musl": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.13.tgz",
-            "integrity": "sha512-U5MsuBQW25dXaYtqWWSPM3P96H6Y+fHuja3TQpMNnylocHW0tEbtFTDlUj6oM+YJLntvEkQy4grBvQNUD4+RCg==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.15.tgz",
+            "integrity": "sha512-ZPcxznxm0pogHBLZhYntyR3sR+MrZjqJIKEr7ZqVen0Rl+P/4upVmfYXjftizi9RoqZntg33fv/1fbdhbYXpEQ==",
             "cpu": [
                 "arm64"
             ],
@@ -436,9 +436,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.13.tgz",
-            "integrity": "sha512-Az3ZZedYRBo9EQzNnD9SxFcR1G5QsGo6VEc2hIyVPZ1rdKwee/7E9oeBBZFpE8Z44ekxsDQBqbiWGW5ShOhUSQ==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.15.tgz",
+            "integrity": "sha512-0jj7THz12GbUOLmMibktK6DZjqz2zV64KFxyBtcFTKPiiOIY0a7vns1elpO1dERvxpsZ5ik0oFfz0oGwFde1+g==",
             "cpu": [
                 "x64"
             ],
@@ -456,9 +456,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64-musl": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.13.tgz",
-            "integrity": "sha512-Z601MienRgTBDza/+u2CH3RSrWoXo9rtr8NK6A4KJzqGgfxx+H3VlyLgTJ4sRo40T3pIsqpTmiOQEvYzQvBRvQ==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.15.tgz",
+            "integrity": "sha512-CNq/9W38SYSH023lfcQ4KKU8K0YX8T//FZUhcgtMMRABDojx5XsMV7jlweAvGSl389wJQB29Qo6Zb/a+jdvt+w==",
             "cpu": [
                 "x64"
             ],
@@ -476,9 +476,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-arm64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.13.tgz",
-            "integrity": "sha512-Px9PS2B5/Q183bUwy/5VHqp3J2lzdOCeVGzMpphYfl8oSa7VDCqenBdqWpy6DCy/en4Rbf/Y1RieZF6dJPcc9A==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.15.tgz",
+            "integrity": "sha512-ouhkYdlhp/1GghEJPdWwD/Vi3gQ1nFxuSpMolWsbq3Lsq3QUR4jl6UdhhscdCugKU5vOEuMiJhvKj66O0OCq+w==",
             "cpu": [
                 "arm64"
             ],
@@ -493,9 +493,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-x64": {
-            "version": "2.4.13",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.13.tgz",
-            "integrity": "sha512-tTcMkXyBrmHi9BfrD2VNHs/5rYIUKETqsBlYOvSAABwBkJhSDVb5e7wPukftsQbO3WzQkXe6kaztC6WtUOXSoQ==",
+            "version": "2.4.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.15.tgz",
+            "integrity": "sha512-zBrGq5mx5wwpnow4+2BxUvleDM+GNd4sLbPaMapsSLQLD0NGRCquqPBTgN+7XkUteHvj7M+BstuI8tmnV7+HgQ==",
             "cpu": [
                 "x64"
             ],
@@ -613,9 +613,9 @@
             }
         },
         "node_modules/@oxc-project/types": {
-            "version": "0.127.0",
-            "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz",
-            "integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==",
+            "version": "0.130.0",
+            "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.130.0.tgz",
+            "integrity": "sha512-ibD2usx9JRu7f5pu2tMKMI4cpA4NgXJQoYRP4pQ7Pxmn1l6k/53qWtQWZayhYy3X4QZkt90Ot+mJEaeXouio6Q==",
             "dev": true,
             "license": "MIT",
             "funding": {
@@ -761,9 +761,9 @@
             }
         },
         "node_modules/@rolldown/binding-android-arm64": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
-            "integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.1.tgz",
+            "integrity": "sha512-fJI3I0r3C3Oj/zdBCpaCmBRZYf07xpaq4yCfDDoSFm+beWNzbIl26puW8RraUdugoJw/95zerNOn6jasAhzSmg==",
             "cpu": [
                 "arm64"
             ],
@@ -778,9 +778,9 @@
             }
         },
         "node_modules/@rolldown/binding-darwin-arm64": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
-            "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.1.tgz",
+            "integrity": "sha512-cKnAhWEsV7TPcA/5EAteDp6KcJZBQ2G+BqE7zayMMi7kMvwRsbv7WT9aOnn0WNl4SKEIf43vjS31iUPu80nzXg==",
             "cpu": [
                 "arm64"
             ],
@@ -795,9 +795,9 @@
             }
         },
         "node_modules/@rolldown/binding-darwin-x64": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
-            "integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.1.tgz",
+            "integrity": "sha512-YKrVwQjIRBPo+5G/u03wGjbdy4q7pyzCe93DK9VJ7zkVmeg8LJ7GbgsiHWdR4xSoe4CAXRD7Bcjgbtr64bkXNg==",
             "cpu": [
                 "x64"
             ],
@@ -812,9 +812,9 @@
             }
         },
         "node_modules/@rolldown/binding-freebsd-x64": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz",
-            "integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.1.tgz",
+            "integrity": "sha512-z/oBsREo46SsFqBwYtFe0kpJeBijAT48O/WXLI4suiCLBkr03RTtTJMCzSdDd2znlh8VJizL09XVkQgk8IZonw==",
             "cpu": [
                 "x64"
             ],
@@ -829,9 +829,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz",
-            "integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.1.tgz",
+            "integrity": "sha512-ik8q7GM11zxvYxFc2PeDcT6TBvhCQMaUxfph/M5l9sKuTs/Sjg3L+Byw0F7w0ZVLBZmx30P+gG0ECzzN+MFcmQ==",
             "cpu": [
                 "arm"
             ],
@@ -846,9 +846,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-arm64-gnu": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz",
-            "integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.1.tgz",
+            "integrity": "sha512-QoSx2EkyrrdZ6kcyE8stqZ62t0Yra8Fs5ia9lOxJrh6TMQJK7gQKmscdTHf7pOXKREKrVwOtJcQG3qVSfc866A==",
             "cpu": [
                 "arm64"
             ],
@@ -866,9 +866,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-arm64-musl": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz",
-            "integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.1.tgz",
+            "integrity": "sha512-uwNwFpwKeNiZawfAWBgg0VIztPTV3ihhh1vV334h9ivnNLorxnQMU6Fz8wG1Zb4Qh9LC1/MkcyT3YlDXG3Rsgg==",
             "cpu": [
                 "arm64"
             ],
@@ -886,9 +886,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz",
-            "integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.1.tgz",
+            "integrity": "sha512-zY1bul7OWr7DFBiJ++wofXvnr8B45ce3QsQUhKrIhXsygAh7bTkwyeM1bi1a2g5C/yC/N8TZyGDEoMfm/l9mpg==",
             "cpu": [
                 "ppc64"
             ],
@@ -906,9 +906,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-s390x-gnu": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz",
-            "integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.1.tgz",
+            "integrity": "sha512-0frlsT/f4Ft6I7SMESTKnF3cZsdicQn1dCMkF/jT9wDLE+gGoiQfv1nmT9e+s7s/fekvvy6tZM2jHvI2tkbJDQ==",
             "cpu": [
                 "s390x"
             ],
@@ -926,9 +926,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-x64-gnu": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz",
-            "integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.1.tgz",
+            "integrity": "sha512-XABVmGp9Tg0WspTVvwduTc4fpqy6JnAUrSQe6OuyqD/03nI7r0O9OWUkMIwFrjKAIqolvqoA4ZrJppgwE0Gxmw==",
             "cpu": [
                 "x64"
             ],
@@ -946,9 +946,9 @@
             }
         },
         "node_modules/@rolldown/binding-linux-x64-musl": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz",
-            "integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.1.tgz",
+            "integrity": "sha512-bV4fzswuzVcKD90o/VM6QqKxnxlDq0g2BISDLNVmxrnhpv1DDbyPhCIjYfvzYLV+MvkKKnQt2Q6AO86SEBULUQ==",
             "cpu": [
                 "x64"
             ],
@@ -966,9 +966,9 @@
             }
         },
         "node_modules/@rolldown/binding-openharmony-arm64": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz",
-            "integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.1.tgz",
+            "integrity": "sha512-/Mh0Zhq3OP7fVs0kcQHZP6lZEthMGTaSf8UBQYSFEZDWGXXlEC+nJ6EqenaK2t4LBXMe3A+K/G2BVXXdtOr4PQ==",
             "cpu": [
                 "arm64"
             ],
@@ -983,9 +983,9 @@
             }
         },
         "node_modules/@rolldown/binding-wasm32-wasi": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz",
-            "integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.1.tgz",
+            "integrity": "sha512-+1xc9X45l8ufsBAm6Gjvx2qDRIY9lTVt0cgWNcJ+1gdhXvkbxePA60yRTwSTuXL09CMhyJmjpV7E3NoyxbqFQQ==",
             "cpu": [
                 "wasm32"
             ],
@@ -1002,9 +1002,9 @@
             }
         },
         "node_modules/@rolldown/binding-win32-arm64-msvc": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz",
-            "integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.1.tgz",
+            "integrity": "sha512-1D+UqZdfnuR+Jy1GgMJwi85bD40H21uNmOPRWQhw4oRSuolZ/B5rixZ45DK2KXOTCvmVCecauWgEhbw8bI7tOw==",
             "cpu": [
                 "arm64"
             ],
@@ -1019,9 +1019,9 @@
             }
         },
         "node_modules/@rolldown/binding-win32-x64-msvc": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz",
-            "integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.1.tgz",
+            "integrity": "sha512-INAycaWuhlOK3wk4mRHGsdgwYWmd9cChdPdE9bwWmy6rn9VqVNYNFGhOdXrofXUxwHIncSiPNb8tNm8knDVIeQ==",
             "cpu": [
                 "x64"
             ],
@@ -1036,9 +1036,9 @@
             }
         },
         "node_modules/@rolldown/pluginutils": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
-            "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
+            "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
             "dev": true,
             "license": "MIT"
         },
@@ -1066,9 +1066,9 @@
             }
         },
         "node_modules/@tybys/wasm-util": {
-            "version": "0.10.1",
-            "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
-            "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+            "version": "0.10.2",
+            "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
+            "integrity": "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==",
             "dev": true,
             "license": "MIT",
             "optional": true,
@@ -2026,14 +2026,14 @@
             }
         },
         "node_modules/rolldown": {
-            "version": "1.0.0-rc.17",
-            "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
-            "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.1.tgz",
+            "integrity": "sha512-X0KQHljNnEkWNqqiz9zJrGunh1B0HgOxLXvnFpCOcadzcy5qohZ3tqMEUg00vncoRovXuK3ZqCT9KnnKzoInFQ==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
-                "@oxc-project/types": "=0.127.0",
-                "@rolldown/pluginutils": "1.0.0-rc.17"
+                "@oxc-project/types": "=0.130.0",
+                "@rolldown/pluginutils": "^1.0.0"
             },
             "bin": {
                 "rolldown": "bin/cli.mjs"
@@ -2042,21 +2042,21 @@
                 "node": "^20.19.0 || >=22.12.0"
             },
             "optionalDependencies": {
-                "@rolldown/binding-android-arm64": "1.0.0-rc.17",
-                "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
-                "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
-                "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
-                "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
-                "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
-                "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
-                "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
-                "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
-                "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
-                "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
-                "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
-                "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
-                "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
-                "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
+                "@rolldown/binding-android-arm64": "1.0.1",
+                "@rolldown/binding-darwin-arm64": "1.0.1",
+                "@rolldown/binding-darwin-x64": "1.0.1",
+                "@rolldown/binding-freebsd-x64": "1.0.1",
+                "@rolldown/binding-linux-arm-gnueabihf": "1.0.1",
+                "@rolldown/binding-linux-arm64-gnu": "1.0.1",
+                "@rolldown/binding-linux-arm64-musl": "1.0.1",
+                "@rolldown/binding-linux-ppc64-gnu": "1.0.1",
+                "@rolldown/binding-linux-s390x-gnu": "1.0.1",
+                "@rolldown/binding-linux-x64-gnu": "1.0.1",
+                "@rolldown/binding-linux-x64-musl": "1.0.1",
+                "@rolldown/binding-openharmony-arm64": "1.0.1",
+                "@rolldown/binding-wasm32-wasi": "1.0.1",
+                "@rolldown/binding-win32-arm64-msvc": "1.0.1",
+                "@rolldown/binding-win32-x64-msvc": "1.0.1"
             }
         },
         "node_modules/semver": {
@@ -2213,16 +2213,16 @@
             "license": "MIT"
         },
         "node_modules/vite": {
-            "version": "8.0.10",
-            "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
-            "integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==",
+            "version": "8.0.13",
+            "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.13.tgz",
+            "integrity": "sha512-MFtjBYgzmSxmgA4RAfjIyXWpGe1oALnjgUTzzV7QLx/TKxCzjtMH6Fd9/eVK+5Fg1qNoz5VAwsmMs/NofrmJvw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
                 "lightningcss": "^1.32.0",
                 "picomatch": "^4.0.4",
-                "postcss": "^8.5.10",
-                "rolldown": "1.0.0-rc.17",
+                "postcss": "^8.5.14",
+                "rolldown": "1.0.1",
                 "tinyglobby": "^0.2.16"
             },
             "bin": {
@@ -2239,7 +2239,7 @@
             },
             "peerDependencies": {
                 "@types/node": "^20.19.0 || >=22.12.0",
-                "@vitejs/devtools": "^0.1.0",
+                "@vitejs/devtools": "^0.1.18",
                 "esbuild": "^0.27.0 || ^0.28.0",
                 "jiti": ">=1.21.0",
                 "less": "^4.0.0",
@@ -2316,9 +2316,9 @@
             "license": "ISC"
         },
         "node_modules/yaml": {
-            "version": "2.8.3",
-            "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
-            "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+            "version": "2.9.0",
+            "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+            "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
             "dev": true,
             "license": "ISC",
             "bin": {
diff --git a/frontend/package.json b/frontend/package.json
index 34a2905..ec0bd27 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -13,14 +13,14 @@
         "fix:unsafe": "biome check --write --unsafe"
     },
     "dependencies": {
-        "preact": "10.29.1"
+        "preact": "^10.29.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.4.13",
-        "@preact/preset-vite": "2.10.5",
-        "openapi-typescript": "7.13.0",
-        "typescript": "6.0.3",
-        "vite": "8.0.10",
-        "yaml": "2.8.3"
+        "@biomejs/biome": "^2.4.15",
+        "@preact/preset-vite": "^2.10.5",
+        "openapi-typescript": "^7.13.0",
+        "typescript": "^6.0.3",
+        "vite": "^8.0.13",
+        "yaml": "^2.9.0"
     }
 }
diff --git a/platformio.ini b/platformio.ini
index 540841a..5989d5d 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -23,7 +23,7 @@ lib_dir = firmware/lib
 ; --- Shared across all boards and modes ---------------------------------------
 
 [env]
-platform = espressif32 @ 6.13.0
+platform = espressif32 @ 7.0.1
 framework = arduino
 extra_scripts = pre:scripts/env_config.py
 board_build.partitions = firmware/partition.csv
@@ -38,7 +38,7 @@ lib_compat_mode = strict
 lib_ldf_mode = chain
 lib_deps =
     ESP32Async/AsyncTCP @ 3.4.10
-    ESP32Async/ESPAsyncWebServer @ 3.10.3
+    ESP32Async/ESPAsyncWebServer @ 3.11.0
 
 ; --- Build modes --------------------------------------------------------------
 
@@ -51,6 +51,7 @@ upload_command = bash -c 'HASH=$$(md5sum "$SOURCE" | cut -d" " -f1) && curl -f -
 [board_c3]
 board = esp32-c3-devkitm-1
 build_flags =
+    -Wno-attributes
     -DARDUINO_USB_MODE=1
     -DARDUINO_USB_CDC_ON_BOOT=1
     -DCHIP_MODEL=\"ESP32-C3\"
@@ -80,6 +81,7 @@ board = esp32-s3-devkitc-1
 board_build.flash_size = 4MB
 board_upload.flash_size = 4MB
 build_flags =
+    -Wno-attributes
     -DARDUINO_USB_MODE=1
     -DARDUINO_USB_CDC_ON_BOOT=1
     -DCHIP_MODEL=\"ESP32-S3\"
@@ -107,6 +109,7 @@ build_flags =
 [board_esp32]
 board = esp32dev
 build_flags =
+    -Wno-attributes
     -DCHIP_MODEL=\"ESP32\"
     -std=gnu++17
 

From 6a1eb276f30eb3bb2b75ae936b3ebed8c31d698d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Thu, 14 May 2026 21:39:18 +0300
Subject: [PATCH 18/44] chore: pin frontend dependency versions

---
 frontend/package-lock.json | 14 +++++++-------
 frontend/package.json      | 14 +++++++-------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 1c0b36f..6c90e34 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,15 +8,15 @@
             "name": "neato-web",
             "version": "0.0.1",
             "dependencies": {
-                "preact": "^10.29.1"
+                "preact": "10.29.1"
             },
             "devDependencies": {
-                "@biomejs/biome": "^2.4.15",
-                "@preact/preset-vite": "^2.10.5",
-                "openapi-typescript": "^7.13.0",
-                "typescript": "^6.0.3",
-                "vite": "^8.0.13",
-                "yaml": "^2.9.0"
+                "@biomejs/biome": "2.4.15",
+                "@preact/preset-vite": "2.10.5",
+                "openapi-typescript": "7.13.0",
+                "typescript": "6.0.3",
+                "vite": "8.0.13",
+                "yaml": "2.9.0"
             }
         },
         "node_modules/@babel/code-frame": {
diff --git a/frontend/package.json b/frontend/package.json
index ec0bd27..d931af4 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -13,14 +13,14 @@
         "fix:unsafe": "biome check --write --unsafe"
     },
     "dependencies": {
-        "preact": "^10.29.1"
+        "preact": "10.29.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.4.15",
-        "@preact/preset-vite": "^2.10.5",
-        "openapi-typescript": "^7.13.0",
-        "typescript": "^6.0.3",
-        "vite": "^8.0.13",
-        "yaml": "^2.9.0"
+        "@biomejs/biome": "2.4.15",
+        "@preact/preset-vite": "2.10.5",
+        "openapi-typescript": "7.13.0",
+        "typescript": "6.0.3",
+        "vite": "8.0.13",
+        "yaml": "2.9.0"
     }
 }

From 50a7a9ed84c59efb49b4b9cfa74109bfd1896102 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?= <sonerkoksal@gmail.com>
Date: Fri, 15 May 2026 00:23:54 +0300
Subject: [PATCH 19/44] refactor: simplify battery diagnostics card grid

---
 frontend/src/style.css                        | 22 +++----------------
 frontend/src/views/battery.tsx                |  4 ++--
 ...cs-section.tsx => battery-diagnostics.tsx} | 19 +++++++---------
 3 files changed, 13 insertions(+), 32 deletions(-)
 rename frontend/src/views/settings/{battery-diagnostics-section.tsx => battery-diagnostics.tsx} (93%)

diff --git a/frontend/src/style.css b/frontend/src/style.css
index cdabd8d..2efa92d 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -1029,7 +1029,7 @@ input:disabled {
     margin-bottom: 10px;
 }
 
-.settings-battery-stat {
+.settings-battery-grid > div {
     min-width: 0;
     padding: 10px 12px;
     border: 1px solid var(--border);
@@ -1037,8 +1037,7 @@ input:disabled {
     background: var(--card-bg);
 }
 
-.settings-battery-stat span,
-.settings-battery-advanced span {
+.settings-battery-grid > div span {
     display: block;
     font-size: 11px;
     font-weight: 600;
@@ -1047,8 +1046,7 @@ input:disabled {
     letter-spacing: 0.04em;
 }
 
-.settings-battery-stat strong,
-.settings-battery-advanced strong {
+.settings-battery-grid > div strong {
     display: block;
     overflow: hidden;
     margin-top: 2px;
@@ -1059,20 +1057,6 @@ input:disabled {
     white-space: nowrap;
 }
 
-.settings-battery-advanced {
-    display: grid;
-    grid-template-columns: repeat(2, 1fr);
-    gap: 8px;
-    margin-bottom: 10px;
-}
-
-.settings-battery-advanced > div {
-    min-width: 0;
-    padding: 9px 10px;
-    border-radius: 10px;
-    background: rgba(255, 255, 255, 0.03);
-}
-
 .settings-battery-note {
     display: block;
     margin-top: 4px;
diff --git a/frontend/src/views/battery.tsx b/frontend/src/views/battery.tsx
index f9cba9f..f5e2a41 100644
--- a/frontend/src/views/battery.tsx
+++ b/frontend/src/views/battery.tsx
@@ -1,7 +1,7 @@
 import backSvg from "../assets/icons/back.svg?raw";
 import { ErrorBannerStack, useErrorStack } from "../components/error-banner";
 import { Icon } from "../components/icon";
-import { BatteryDiagnosticsSection } from "./settings/battery-diagnostics-section";
+import { BatteryDiagnostics } from "./settings/battery-diagnostics";
 
 interface BatteryViewProps {
     firmwareSupported: boolean;
@@ -23,7 +23,7 @@ export function BatteryView({ firmwareSupported }: BatteryViewProps) {
             <ErrorBannerStack errors={errors} />
 
             <div class="schedule-page">
-                <BatteryDiagnosticsSection firmwareSupported={firmwareSupported} errorStack={errorStack} />
+                <BatteryDiagnostics firmwareSupported={firmwareSupported} errorStack={errorStack} />
             </div>
         </>
     );
diff --git a/frontend/src/views/settings/battery-diagnostics-section.tsx b/frontend/src/views/settings/battery-diagnostics.tsx
similarity index 93%
rename from frontend/src/views/settings/battery-diagnostics-section.tsx
rename to frontend/src/views/settings/battery-diagnostics.tsx
index a7eed44..14b7709 100644
--- a/frontend/src/views/settings/battery-diagnostics-section.tsx
+++ b/frontend/src/views/settings/battery-diagnostics.tsx
@@ -8,7 +8,7 @@ import { usePolling } from "../../hooks/use-polling";
 import type { BatteryAnalogData, BatteryWarrantyData, ChargerData, VersionData } from "../../types";
 import { normalizeError } from "../../utils";
 
-interface BatteryDiagnosticsSectionProps {
+interface BatteryDiagnosticsProps {
     firmwareSupported: boolean;
     errorStack: ErrorStackHandle;
 }
@@ -36,7 +36,7 @@ function mfgDateLooksUnreliable(version: VersionData | null | undefined): boolea
     return true;
 }
 
-export function BatteryDiagnosticsSection({ firmwareSupported, errorStack }: BatteryDiagnosticsSectionProps) {
+export function BatteryDiagnostics({ firmwareSupported, errorStack }: BatteryDiagnosticsProps) {
     const chargerPoll = usePolling<ChargerData>(api.getCharger, 30000);
     const analogPoll = usePolling<BatteryAnalogData>(api.getBatteryAnalog, 30000);
     const warrantyPoll = usePolling<BatteryWarrantyData>(api.getBatteryWarranty, 60000);
@@ -79,33 +79,30 @@ export function BatteryDiagnosticsSection({ firmwareSupported, errorStack }: Bat
                     {charger && analog && warranty ? (
                         <>
                             <div class="settings-battery-grid">
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>Charge</span>
                                     <strong>{charger.fuelPercent}%</strong>
                                 </div>
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>State</span>
                                     <strong>{batteryStateLabel(charger)}</strong>
                                 </div>
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>Voltage</span>
                                     <strong>{charger.vBattV.toFixed(2)} V</strong>
                                 </div>
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>Temp</span>
                                     <strong>{analog.batteryTemperatureC.toFixed(1)} C</strong>
                                 </div>
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>Cycles</span>
                                     <strong>{warranty.cumulativeBatteryCycles}</strong>
                                 </div>
-                                <div class="settings-battery-stat">
+                                <div>
                                     <span>Pack</span>
                                     <strong>{version?.smartBatteryManufacturerName || "Unknown"}</strong>
                                 </div>
-                            </div>
-
-                            <div class="settings-battery-advanced">
                                 <div>
                                     <span>Current</span>
                                     <strong>{analog.batteryCurrentMA} mA</strong>

From d05b68225896e28b06736c06331478796b9a4e26 Mon Sep 17 00:00:00 2001
From: druby-luke <lukesmolders@proton.me>
Date: Fri, 15 May 2026 21:00:34 +0200
Subject: [PATCH 20/44] feat: integrate battery diagnostics and new battery
 calibration feature

- Added support for battery diagnostics including voltage, current, and warranty data.
- Implemented a new button to reset battery fuel-gauge calibration after a pack swap.
- Enhanced JSON response handling to tolerate non-UTF-8 bytes, preventing setup crashes.
- Updated changelog and version to 1.10.
---
 custom_components/openneato/CHANGELOG.md   | 24 ++++++++
 custom_components/openneato/api.py         | 32 ++++++++++-
 custom_components/openneato/button.py      | 11 ++++
 custom_components/openneato/coordinator.py |  3 +
 custom_components/openneato/manifest.json  |  2 +-
 custom_components/openneato/sensor.py      | 67 +++++++++++++++++++++-
 custom_components/openneato/strings.json   | 10 +++-
 7 files changed, 140 insertions(+), 9 deletions(-)

diff --git a/custom_components/openneato/CHANGELOG.md b/custom_components/openneato/CHANGELOG.md
index d20a60b..deeca28 100644
--- a/custom_components/openneato/CHANGELOG.md
+++ b/custom_components/openneato/CHANGELOG.md
@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.10
+
+### Fixed
+- **Setup crash with new firmware (`utf-8 codec can't decode byte 0xab`)** —
+  Upstream firmware PR #121 added `smartBattery*` string fields to
+  `/api/version` that pass raw bytes from the robot's smart-battery
+  memory through the firmware's `jsonEscape()` (it only escapes bytes
+  below 0x20). When the pack reports a non-UTF-8 byte, aiohttp's
+  `response.json()` raised `UnicodeDecodeError` and the config entry
+  failed setup. Responses are now decoded with `errors="replace"`
+  before being parsed as JSON so one bad glyph can't take the
+  integration down.
+
+### Added
+- **Battery diagnostics from firmware PR #121** — three new diagnostic
+  sensors backed by the new `/api/analog` endpoint (battery voltage,
+  current, external voltage) and two backed by `/api/warranty`
+  (battery cycles, cumulative cleaning time). The existing
+  `Battery temperature` sensor was repointed from the now-removed
+  `/api/charger#battTempC` to `/api/analog#batteryTemperatureC`
+  (a finer-grained float in °C). A `New battery` button (disabled by
+  default) calls `POST /api/battery/new` to reset the fuel-gauge
+  calibration after a pack swap.
+
 ## 1.9
 
 ### Fixed
diff --git a/custom_components/openneato/api.py b/custom_components/openneato/api.py
index 05cfbd9..e0bf9c8 100644
--- a/custom_components/openneato/api.py
+++ b/custom_components/openneato/api.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import re
 from typing import Any
@@ -28,6 +29,19 @@ class OpenNeatoApiError(HomeAssistantError):
     """Error to indicate a non-connection API failure."""
 
 
+async def _read_json(response: aiohttp.ClientResponse) -> Any:
+    """Read a response body and parse it as JSON, tolerating stray non-UTF-8 bytes.
+
+    The firmware's jsonEscape() passes bytes >= 0x20 through verbatim, so the
+    /api/version response can contain raw bytes from the robot's smart-battery
+    memory (manufacturer name, serial, etc.) that aren't valid UTF-8. Replace
+    those bytes rather than raising — losing one glyph is better than failing
+    the whole config-entry setup.
+    """
+    raw = await response.read()
+    return json.loads(raw.decode("utf-8", errors="replace"))
+
+
 class OpenNeatoApiClient:
     """Async HTTP client for OpenNeato."""
 
@@ -59,7 +73,7 @@ async def _get(self, path: str) -> dict[str, Any]:
                         path, response.status, response.content_type,
                     )
                     response.raise_for_status()
-                    return await response.json()
+                    return await _read_json(response)
         except aiohttp.ClientConnectionError as err:
             _LOGGER.warning("Connection error on GET %s: %s", path, err)
             raise OpenNeatoConnectionError(
@@ -92,7 +106,7 @@ async def _post(
                     response.raise_for_status()
                     content_type = response.content_type or ""
                     if "json" in content_type:
-                        return await response.json()
+                        return await _read_json(response)
                     return await response.text()
         except aiohttp.ClientConnectionError as err:
             _LOGGER.warning("Connection error on POST %s: %s", path, err)
@@ -122,7 +136,7 @@ async def _put(self, path: str, json_data: dict[str, Any]) -> dict[str, Any]:
                         path, response.status, response.content_type,
                     )
                     response.raise_for_status()
-                    return await response.json()
+                    return await _read_json(response)
         except aiohttp.ClientConnectionError as err:
             _LOGGER.warning("Connection error on PUT %s: %s", path, err)
             raise OpenNeatoConnectionError(
@@ -149,6 +163,14 @@ async def get_charger(self) -> dict[str, Any]:
         """Get charger / battery information."""
         return await self._get("/api/charger")
 
+    async def get_battery_analog(self) -> dict[str, Any]:
+        """Get analog battery readings (voltage, current, temperature)."""
+        return await self._get("/api/analog")
+
+    async def get_battery_warranty(self) -> dict[str, Any]:
+        """Get battery warranty data (cumulative cycles, runtime)."""
+        return await self._get("/api/warranty")
+
     async def get_error(self) -> dict[str, Any]:
         """Get current error information."""
         return await self._get("/api/error")
@@ -270,6 +292,10 @@ async def restart(self) -> dict[str, Any] | str:
         """Restart the robot controller."""
         return await self._post("/api/system/restart")
 
+    async def new_battery(self) -> dict[str, Any] | str:
+        """Reset battery fuel-gauge calibration after physically replacing the pack."""
+        return await self._post("/api/battery/new")
+
     async def format_fs(self) -> dict[str, Any] | str:
         """Format the filesystem."""
         return await self._post("/api/system/format-fs")
diff --git a/custom_components/openneato/button.py b/custom_components/openneato/button.py
index f3425b3..1baa60e 100644
--- a/custom_components/openneato/button.py
+++ b/custom_components/openneato/button.py
@@ -81,6 +81,17 @@ class OpenNeatoButtonEntityDescription(ButtonEntityDescription):
         entity_category=EntityCategory.DIAGNOSTIC,
         press_fn=lambda api: api.clear_errors(),
     ),
+    OpenNeatoButtonEntityDescription(
+        # Resets the battery fuel-gauge calibration after a pack swap.
+        # Disabled by default — user must opt in to avoid accidental resets.
+        key="new_battery",
+        translation_key="new_battery",
+        name="New battery",
+        icon="mdi:battery-sync-outline",
+        entity_category=EntityCategory.CONFIG,
+        entity_registry_enabled_default=False,
+        press_fn=lambda api: api.new_battery(),
+    ),
 )
 
 
diff --git a/custom_components/openneato/coordinator.py b/custom_components/openneato/coordinator.py
index fcf7e4a..bbf9ca7 100644
--- a/custom_components/openneato/coordinator.py
+++ b/custom_components/openneato/coordinator.py
@@ -41,12 +41,15 @@ async def _async_update_data(self) -> dict[str, Any]:
             self.api.get_motors(),
             self.api.get_history(),
             self.api.get_sensors(),
+            self.api.get_battery_analog(),
+            self.api.get_battery_warranty(),
             return_exceptions=True,
         )
 
         keys = (
             "state", "charger", "error", "user_settings",
             "system", "settings", "motors", "history", "sensors",
+            "analog", "warranty",
         )
         # Critical endpoints — if ALL of these fail we consider the robot
         # unreachable. Non-critical endpoints (like /api/error, which can hang
diff --git a/custom_components/openneato/manifest.json b/custom_components/openneato/manifest.json
index 6c67297..57ce71b 100644
--- a/custom_components/openneato/manifest.json
+++ b/custom_components/openneato/manifest.json
@@ -7,5 +7,5 @@
   "documentation": "https://github.com/renjfk/OpenNeato",
   "iot_class": "local_polling",
   "requirements": [],
-  "version": "1.9"
+  "version": "1.10"
 }
diff --git a/custom_components/openneato/sensor.py b/custom_components/openneato/sensor.py
index 03a81c4..f50a5e9 100644
--- a/custom_components/openneato/sensor.py
+++ b/custom_components/openneato/sensor.py
@@ -15,6 +15,7 @@
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import (
     EntityCategory,
+    UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfLength,
     UnitOfTemperature,
@@ -80,16 +81,17 @@ class OpenNeatoSensorEntityDescription(SensorEntityDescription):
         entity_category=EntityCategory.DIAGNOSTIC,
     ),
     OpenNeatoSensorEntityDescription(
+        # PR #121 moved battery temp out of /api/charger into the new
+        # /api/analog endpoint as a float in C (was an int with -1 sentinel).
         key="charger_batt_temp",
         translation_key="battery_temperature",
         name="Battery temperature",
-        section="charger",
-        field="battTempC",
+        section="analog",
+        field="batteryTemperatureC",
         device_class=SensorDeviceClass.TEMPERATURE,
         native_unit_of_measurement=UnitOfTemperature.CELSIUS,
         state_class=SensorStateClass.MEASUREMENT,
         entity_category=EntityCategory.DIAGNOSTIC,
-        value_fn=lambda v: v if v is not None and v >= 0 else None,
     ),
     OpenNeatoSensorEntityDescription(
         key="charger_discharge_mah",
@@ -113,6 +115,65 @@ class OpenNeatoSensorEntityDescription(SensorEntityDescription):
         state_class=SensorStateClass.MEASUREMENT,
         entity_category=EntityCategory.DIAGNOSTIC,
     ),
+    # ── Analog battery readings (PR #121, /api/analog) ──────────────────
+    OpenNeatoSensorEntityDescription(
+        key="analog_battery_voltage",
+        translation_key="analog_battery_voltage",
+        name="Battery voltage (analog)",
+        section="analog",
+        field="batteryVoltageV",
+        device_class=SensorDeviceClass.VOLTAGE,
+        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
+        state_class=SensorStateClass.MEASUREMENT,
+        entity_category=EntityCategory.DIAGNOSTIC,
+        entity_registry_enabled_default=False,
+    ),
+    OpenNeatoSensorEntityDescription(
+        key="analog_battery_current",
+        translation_key="analog_battery_current",
+        name="Battery current",
+        section="analog",
+        field="batteryCurrentMA",
+        device_class=SensorDeviceClass.CURRENT,
+        native_unit_of_measurement=UnitOfElectricCurrent.MILLIAMPERE,
+        state_class=SensorStateClass.MEASUREMENT,
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
+    OpenNeatoSensorEntityDescription(
+        key="analog_external_voltage",
+        translation_key="analog_external_voltage",
+        name="External voltage (analog)",
+        section="analog",
+        field="externalVoltageV",
+        device_class=SensorDeviceClass.VOLTAGE,
+        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
+        state_class=SensorStateClass.MEASUREMENT,
+        entity_category=EntityCategory.DIAGNOSTIC,
+        entity_registry_enabled_default=False,
+    ),
+    # ── Battery warranty (PR #121, /api/warranty) ───────────────────────
+    OpenNeatoSensorEntityDescription(
+        key="warranty_battery_cycles",
+        translation_key="battery_cycles",
+        name="Battery cycles",
+        section="warranty",
+        field="cumulativeBatteryCycles",
+        icon="mdi:battery-sync",
+        state_class=SensorStateClass.TOTAL_INCREASING,
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
+    OpenNeatoSensorEntityDescription(
+        key="warranty_cleaning_time",
+        translation_key="cumulative_cleaning_time",
+        name="Cumulative cleaning time",
+        section="warranty",
+        field="cumulativeCleaningTimeSeconds",
+        device_class=SensorDeviceClass.DURATION,
+        native_unit_of_measurement=UnitOfTime.SECONDS,
+        state_class=SensorStateClass.TOTAL_INCREASING,
+        icon="mdi:timer-sand",
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
     # ── Error ───────────────────────────────────────────────────────────
     OpenNeatoSensorEntityDescription(
         key="error_code",
diff --git a/custom_components/openneato/strings.json b/custom_components/openneato/strings.json
index 9f04d88..3858450 100644
--- a/custom_components/openneato/strings.json
+++ b/custom_components/openneato/strings.json
@@ -40,7 +40,12 @@
       "last_clean_distance": { "name": "Last clean distance" },
       "last_clean_battery_used": { "name": "Last clean battery used" },
       "last_clean_mode": { "name": "Last clean mode" },
-      "last_clean_ended": { "name": "Last clean ended" }
+      "last_clean_ended": { "name": "Last clean ended" },
+      "analog_battery_voltage": { "name": "Battery voltage (analog)" },
+      "analog_battery_current": { "name": "Battery current" },
+      "analog_external_voltage": { "name": "External voltage (analog)" },
+      "battery_cycles": { "name": "Battery cycles" },
+      "cumulative_cleaning_time": { "name": "Cumulative cleaning time" }
     },
     "binary_sensor": {
       "charging": { "name": "Charging" },
@@ -78,7 +83,8 @@
       "robot_restart": { "name": "Restart robot" },
       "robot_shutdown": { "name": "Shutdown robot" },
       "locate": { "name": "Locate robot" },
-      "clear_errors": { "name": "Clear errors" }
+      "clear_errors": { "name": "Clear errors" },
+      "new_battery": { "name": "New battery" }
     },
     "number": {
       "brush_rpm_setting": { "name": "Brush RPM" },

From 5bca4e16274ecbd934d66668782c221884997df3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Fri, 15 May 2026 22:19:31 +0300
Subject: [PATCH 21/44] docs: add troubleshooting steps for PM load fail stuck
 state (#122)

---
 docs/user-guide.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/user-guide.md b/docs/user-guide.md
index 90c2e18..b8d8d42 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -25,6 +25,7 @@ Everything you need to set up, configure, and troubleshoot OpenNeato.
 - [Troubleshooting](#troubleshooting)
     - [Enabling Logging](#enabling-logging)
     - [Collecting Logs](#collecting-logs)
+    - [Robot Stuck Starting a House Clean](#robot-stuck-starting-a-house-clean)
     - [Downloading Cleaning Maps](#downloading-cleaning-maps)
     - [Recovering Corrupted Cleaning History](#recovering-corrupted-cleaning-history)
     - [Factory Reset](#factory-reset)
@@ -503,6 +504,41 @@ To download all logs: use the individual download buttons for each file you need
 reporting an issue, include at least the `current.jsonl` and any archived log files from the
 time the problem occurred.
 
+### Robot Stuck Starting a House Clean
+
+Some Botvac D7 robots can get stuck while starting a house clean with a robot notice like
+"Failed to load persistent map". Debug logs usually show `UI_ALERT_PM_LOAD_FAIL` (`234`) and
+the robot remains in `UIMGR_STATE_STARTHOUSECLEANING` while the robot state stays
+`ST_C_Standby`. This appears to be a robot firmware-side state rather than an OpenNeato
+scheduler failure. See [issue #24](https://github.com/renjfk/OpenNeato/issues/24) for the
+original field reports that led to documenting this recovery path.
+
+Try the recovery steps in this order:
+
+1. Open **Settings -> Diagnostics** and use **Clear Robot Errors**, then try starting a clean
+   again.
+2. If it remains stuck, open **Settings -> Robot** and use **Restart Robot**. This is equivalent
+   to a robot power cycle and has been the most reliable software recovery in reports so far.
+3. If the issue keeps returning, enable **Debug** logging or **Remote Syslog** before the next
+   scheduled run and save the logs when it happens.
+4. As an advanced hardware recovery step, fully remove power from the robot by disconnecting the
+   battery for a few minutes, then reconnect it. Some users reported the issue stopped after
+   maintenance that included a battery disconnect, cleaning sensors, clearing robot logs, and
+   removing debris from the brush or motor area.
+
+> [!CAUTION]
+> Disconnecting the robot battery requires opening the robot. Only do this if you are comfortable
+> with hardware disassembly, and avoid pulling on wires or shorting the battery connector.
+
+When reporting this issue, include the robot software version from:
+
+```bash
+curl -X POST 'http://neato.local/api/serial?cmd=GetVersion'
+```
+
+In known reports, affected robots were running Neato software `4.5.3.189`, but this is not yet a
+confirmed root cause.
+
 ### Downloading Cleaning Maps
 
 If a cleaning session produced unexpected results (missed areas, strange paths, early

From 17887a464b2ccf05968e22ca8ac116652f26e050 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20K=C3=B6ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Fri, 15 May 2026 22:34:36 +0300
Subject: [PATCH 22/44] feat: add mDNS local discovery (#123)

---
 firmware/src/wifi_manager.cpp | 27 +++++++++++++++++++++++++++
 firmware/src/wifi_manager.h   |  6 ++++++
 2 files changed, 33 insertions(+)

diff --git a/firmware/src/wifi_manager.cpp b/firmware/src/wifi_manager.cpp
index 56312ea..bd71fce 100644
--- a/firmware/src/wifi_manager.cpp
+++ b/firmware/src/wifi_manager.cpp
@@ -1,5 +1,6 @@
 #include "wifi_manager.h"
 #include "data_logger.h"
+#include <ESPmDNS.h>
 #include <esp_task_wdt.h>
 #include <esp_wifi.h>
 
@@ -56,6 +57,7 @@ void WiFiManager::begin() {
             LOG("WIFI", "Connected successfully!");
             LOG("WIFI", "IP: %s", WiFi.localIP().toString().c_str());
             LOG("WIFI", "MAC: %s", WiFi.macAddress().c_str());
+            startMdns();
 
             // Log successful boot connection with diagnostics
             dataLogger.logWifi("boot_connect", {{"ssid", ssid, FIELD_STRING},
@@ -417,6 +419,7 @@ void WiFiManager::tick() {
 
     if (WiFi.status() == WL_CONNECTED) {
         applyTxPower();
+        startMdns();
         LOG("WIFI", "Reconnected! IP: %s, RSSI: %d, attempt: %lu", WiFi.localIP().toString().c_str(), WiFi.RSSI(),
             reconnectAttemptCount);
 
@@ -517,6 +520,7 @@ void WiFiManager::startAccessPoint() {
     apActive = true;
     LOG("WIFI", "AP active: SSID=%s IP=%s", ssid.c_str(), WiFi.softAPIP().toString().c_str());
     dataLogger.logWifi("ap_start", {{"ssid", ssid, FIELD_STRING}, {"ip", WiFi.softAPIP().toString(), FIELD_STRING}});
+    startMdns();
 }
 
 void WiFiManager::stopAccessPoint() {
@@ -532,6 +536,29 @@ void WiFiManager::stopAccessPoint() {
     dataLogger.logWifi("ap_stop");
 }
 
+void WiFiManager::startMdns() {
+    if (hostname.isEmpty()) {
+        LOG("WIFI", "mDNS init skipped: empty hostname");
+        return;
+    }
+
+    // Restart mDNS so service registration stays consistent when the active
+    // interface changes (STA<->AP) and this method is called repeatedly.
+    MDNS.end();
+
+    if (!MDNS.begin(hostname.c_str())) {
+        LOG("WIFI", "mDNS init failed for hostname: %s", hostname.c_str());
+        return;
+    }
+
+    if (!MDNS.addService("http", "tcp", 80)) {
+        LOG("WIFI", "mDNS HTTP service registration failed");
+        return;
+    }
+
+    LOG("WIFI", "mDNS responder up: %s.local", hostname.c_str());
+}
+
 void WiFiManager::reevaluateFallbackAp() {
     // Three policies, derived from the issue scope:
     //   1. No saved credentials -> AP always on (only way to provision).
diff --git a/firmware/src/wifi_manager.h b/firmware/src/wifi_manager.h
index f8497fe..a74e429 100644
--- a/firmware/src/wifi_manager.h
+++ b/firmware/src/wifi_manager.h
@@ -131,6 +131,12 @@ class WiFiManager : public LoopTask {
     // Called whenever STA state, credentials, or apFallbackOnDisconnect change.
     void reevaluateFallbackAp();
 
+    // Safe to call repeatedly: bring up the mDNS responder for
+    // <hostname>.local advertising
+    // the web UI on port 80. Called whenever a network interface (STA or AP)
+    // becomes available so clients can reach the device without knowing its IP.
+    void startMdns();
+
     // Menu actions
     void scanNetworksMenu();
     void manualSSID();

From bb7b541bb340e6399ce73ec6b5920190d68d2cbb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 00:11:34 +0300
Subject: [PATCH 23/44] feat: expose About metadata in firmware version API

---
 firmware/src/web_server.cpp     |  3 +++
 frontend/api/openapi.yaml       | 12 ++++++++++
 frontend/mock/server.js         |  4 ++++
 frontend/src/style.css          | 39 +++++++++++++++++++++++++++++++++
 frontend/src/views/settings.tsx | 30 +++++++++++++++++++++++++
 5 files changed, 88 insertions(+)

diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index 6c8c8b1..460a9d7 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -330,12 +330,15 @@ void WebServer::registerFirmwareRoutes() {
     // GET /api/firmware/version — current ESP32 firmware version + chip model + robot support status
     loggedRoute("/api/firmware/version", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
         std::vector<Field> fields = {
+                {"name", "OpenNeato", FIELD_STRING},
                 {"version", fwMgr.getFirmwareVersion(), FIELD_STRING},
                 {"chip", fwMgr.getChipModel(), FIELD_STRING},
                 {"model", neato.getModelName(), FIELD_STRING},
                 {"hostname", settingsMgr.get().hostname, FIELD_STRING},
                 {"supported", isSupportedModel(neato.getModelName()) ? "true" : "false", FIELD_BOOL},
                 {"identifying", neato.isIdentifying() ? "true" : "false", FIELD_BOOL},
+                {"repositoryUrl", "https://github.com/renjfk/OpenNeato", FIELD_STRING},
+                {"license", "MIT", FIELD_STRING},
         };
         request->send(200, "application/json", fieldsToJson(fields));
         return 200;
diff --git a/frontend/api/openapi.yaml b/frontend/api/openapi.yaml
index dfa7fdc..ef5cf30 100644
--- a/frontend/api/openapi.yaml
+++ b/frontend/api/openapi.yaml
@@ -1541,6 +1541,9 @@ components:
     FirmwareVersion:
       type: object
       properties:
+        name:
+          type: string
+          description: Product name
         version:
           type: string
           description: Bridge firmware semantic version
@@ -1559,13 +1562,22 @@ components:
         identifying:
           type: boolean
           description: True while the bridge is still probing the robot model
+        repositoryUrl:
+          type: string
+          description: Project repository URL
+        license:
+          type: string
+          description: Project license identifier
       required:
+        - name
         - version
         - chip
         - model
         - hostname
         - supported
         - identifying
+        - repositoryUrl
+        - license
     HistoryFileInfo:
       type: object
       properties:
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index 4631301..e996aae 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -938,11 +938,15 @@ const routes = {
 
     "GET /api/firmware/version": (_req, res) => {
         jsonResponse(res, {
+            name: "OpenNeato",
             version: state.firmwareVersion ?? getVersion(),
             chip: "ESP32-C3",
+            model: state.identifying ? "" : state.unsupported ? "Botvac Connected" : "Botvac D7",
             hostname: "neato-kitchen",
             supported: !state.unsupported && !state.identifying,
             identifying: state.identifying,
+            repositoryUrl: "https://github.com/renjfk/OpenNeato",
+            license: "MIT",
         });
     },
 };
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 2efa92d..82e1c97 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -911,12 +911,51 @@ input:disabled {
     color: var(--red);
 }
 
+.settings-link-row {
+    text-decoration: none;
+}
+
+.settings-link-row .settings-nav-row-left {
+    min-width: 0;
+}
+
+.settings-link-row .settings-nav-row-left {
+    overflow-wrap: anywhere;
+}
+
 .settings-nav-chevron {
     font-size: 20px;
     color: var(--text-muted);
     line-height: 1;
 }
 
+.settings-about-card {
+    padding: 16px;
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    background: var(--surface);
+}
+
+.settings-about-name {
+    font-size: 16px;
+    font-weight: 700;
+    color: var(--text);
+}
+
+.settings-about-description {
+    margin-top: 6px;
+    font-size: 14px;
+    line-height: 1.45;
+    color: var(--text-dim);
+}
+
+.settings-about-meta {
+    margin-top: 10px;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--text-muted);
+}
+
 .settings-toggle-row {
     display: flex;
     align-items: center;
diff --git a/frontend/src/views/settings.tsx b/frontend/src/views/settings.tsx
index 24b0e46..accfef5 100644
--- a/frontend/src/views/settings.tsx
+++ b/frontend/src/views/settings.tsx
@@ -8,6 +8,7 @@ import calendarSvg from "../assets/icons/calendar.svg?raw";
 import chipSvg from "../assets/icons/chip.svg?raw";
 import databaseSvg from "../assets/icons/database.svg?raw";
 import gearSvg from "../assets/icons/gear.svg?raw";
+import globeSvg from "../assets/icons/globe.svg?raw";
 import houseSvg from "../assets/icons/house.svg?raw";
 import manualSvg from "../assets/icons/manual.svg?raw";
 import moonSvg from "../assets/icons/moon.svg?raw";
@@ -1063,6 +1064,35 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
                     </div>
                 </SettingsCategory>
 
+                {firmware && (
+                    <SettingsCategory title="About" icon={globeSvg}>
+                        <div class="settings-section">
+                            <div class="settings-about-card">
+                                <div class="settings-about-name">{firmware.name}</div>
+                                <div class="settings-about-description">
+                                    Open-source replacement for Neato's discontinued cloud and mobile app.
+                                </div>
+                                <div class="settings-about-meta">Copyright © 2026 Soner Köksal</div>
+                                <div class="settings-about-meta">Licensed under {firmware.license} License</div>
+                            </div>
+                        </div>
+                        <div class="settings-section">
+                            <a
+                                class="settings-nav-row settings-link-row"
+                                href={firmware.repositoryUrl}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                            >
+                                <div class="settings-nav-row-left">
+                                    <Icon svg={globeSvg} />
+                                    View on GitHub
+                                </div>
+                                <span class="settings-nav-chevron">&rsaquo;</span>
+                            </a>
+                        </div>
+                    </SettingsCategory>
+                )}
+
                 <SettingsCategory title="Danger Zone" icon={alertSvg}>
                     <div class="settings-section">
                         <button

From 559d9deec831f5d59b6fb02d5235ffb8a0bfdaf0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:18:45 +0300
Subject: [PATCH 24/44] feat: add Cloudflare demo mock

---
 README.md                     |   10 +-
 docs/mock-scenarios.md        |  117 +++
 frontend/mock/server.js       | 1308 +++-------------------------
 frontend/mock/shared-api.js   |  729 ++++++++++++++++
 frontend/mock/shared-state.js |  251 ++++++
 frontend/mock/worker.js       |  174 ++++
 frontend/package-lock.json    | 1498 ++++++++++++++++++++++++++++++++-
 frontend/package.json         |    2 +
 frontend/src/analytics.ts     |   39 +
 frontend/src/main.tsx         |    6 +
 frontend/vite.config.ts       |    8 +-
 frontend/wrangler.toml        |   19 +
 12 files changed, 2928 insertions(+), 1233 deletions(-)
 create mode 100644 docs/mock-scenarios.md
 create mode 100644 frontend/mock/shared-api.js
 create mode 100644 frontend/mock/shared-state.js
 create mode 100644 frontend/mock/worker.js
 create mode 100644 frontend/src/analytics.ts
 create mode 100644 frontend/wrangler.toml

diff --git a/README.md b/README.md
index 19eccb7..3f694f5 100644
--- a/README.md
+++ b/README.md
@@ -18,12 +18,16 @@ Botvac robots (D3-D7) over UART and exposes a local web UI over WiFi — no clou
 > or [issue](https://github.com/renjfk/OpenNeato/issues) is always welcome.
 
 > [!IMPORTANT]
-> **Now in development:** 
+> **Now in development:**
 [Guided Clean - zone cleaning, no-go lines, and map-based navigation](https://github.com/renjfk/OpenNeato/issues/68).
 >
 > Select zones on a previously recorded map, draw no-go lines, and let the robot clean exactly where you want.
 > Follow the issue for progress updates and sub-task tracking.
 
+> [!TIP]
+> Want to get a feel for OpenNeato without hardware? Open the [live demo](https://openneato-demo.renjfk.com/).
+> Demo states can be selected with `?scenario=...`; see [mock scenarios](docs/mock-scenarios.md).
+
 |                Dashboard                 |                  Manual Drive                  |                    Cleaning History                    |
 |:----------------------------------------:|:----------------------------------------------:|:------------------------------------------------------:|
 | ![Dashboard](screenshots/dashboard.webp) | ![Manual Drive](screenshots/manual-drive.webp) | ![Cleaning History](screenshots/cleaning-history.webp) |
@@ -166,6 +170,10 @@ When creating issues, please follow our simple naming convention:
 
 ## Development
 
+For frontend development without hardware, use the mock API scenarios documented in
+[`docs/mock-scenarios.md`](docs/mock-scenarios.md). The same `?scenario=...` URLs work in local Vite dev and the
+Cloudflare demo.
+
 ### Release Process
 
 Manual releases via opencode; see [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
diff --git a/docs/mock-scenarios.md b/docs/mock-scenarios.md
new file mode 100644
index 0000000..4c985a6
--- /dev/null
+++ b/docs/mock-scenarios.md
@@ -0,0 +1,117 @@
+# Mock scenarios
+
+The frontend mock API supports scenario flags for testing robot states and failures without hardware. Scenarios are
+selected with the `scenario` query parameter and can be combined with `|`.
+
+Useful combinations:
+
+- `ok` - robot idle, online, battery 85%
+- `err|fa` - robot error, brush stuck, plus action faults
+- `low|fl|fs` - low battery plus log faults and settings fault
+- `man|llq` - manual clean plus low LIDAR quality
+
+When writing URLs, encode `|` as `%7C` if your browser or shell does not preserve it literally.
+
+## Local development
+
+Start the Vite dev server:
+
+```bash
+cd frontend
+npm run dev
+```
+
+Open the UI with a scenario:
+
+```text
+http://localhost:5173/?scenario=err%7Cfa
+http://localhost:5173/?scenario=low%7Cfl%7Cfs#/settings
+```
+
+The selected scenario is stored in the `openneato_scenario` cookie so later SPA API calls keep using it. Switch back to
+the normal state with:
+
+```text
+http://localhost:5173/?scenario=ok
+```
+
+## Demo site
+
+The Cloudflare demo uses the same mock API and the same query parameter:
+
+```text
+https://openneato-demo.renjfk.com/?scenario=err%7Cfa
+https://openneato-demo.renjfk.com/?scenario=man%7Cllq#/manual
+```
+
+The demo persists the selected scenario in the same `openneato_scenario` cookie. Firmware and history uploads are
+blocked server-side in demo mode.
+
+## Scenario keys
+
+Robot state:
+
+- `ok` - idle, online, battery 85%
+- `off` - device unreachable
+- `ident` - identifying robot during boot
+- `unsup` - unsupported robot model
+- `upd` - firmware v0.9, triggers update banner
+- `cls` - house cleaning
+- `spt` - spot cleaning
+- `dock` - docking, return to base
+- `rchg` - mid-clean recharge, on dock and charging
+- `chg` - charging, 62%
+- `ch2` - charging, 25%
+- `ful` - full, on dock
+- `mid` - battery 45%
+- `low` - battery 12%
+- `ded` - battery 0%
+- `err` - brush stuck error
+- `alrt` - alert only, brush change
+
+Manual clean, combinable with each other or fault scenarios:
+
+- `man` - manual mode active, no safety issues
+- `mlf` - manual mode active, robot lifted
+- `mbf` - manual mode active, front-left bumper contact
+- `mbs` - manual mode active, side-right bumper contact
+- `msf` - manual mode active, forward stall, reverse to clear
+- `msr` - manual mode active, rear stall, move forward to clear
+
+LIDAR quality, combinable with any state:
+
+- `llq` - low scan quality, fewer than 90 valid points
+- `lsl` - slow LDS rotation, 2.8 Hz
+- `lno` - LIDAR unavailable, `GET /api/lidar` returns an error
+
+Fault injection, combinable with any state:
+
+- `fa` - action faults, clean house, spot, stop, and return operations fail
+- `fs` - settings fault, NVS write error
+- `flr` - log read fault, list and content fail
+- `fld` - log delete fault, delete single and delete all fail
+- `fl` - log reads and deletes fail
+- `fps` - `/api/state` polling fails
+- `fpc` - `/api/charger` polling fails
+- `fpe` - `/api/error` polling fails
+- `fp` - all polling endpoints fail, state, charger, and error
+- `fhc` - history corruption, injects corrupted pose lines in session data
+- `fhl` - history list corruption, malformed JSON in `/api/history` response, triggers recovery panel
+- `fal` - all major faults combined
+
+WiFi:
+
+- `wap` - fallback AP active, STA disconnected and fallback enabled
+- `wnc` - no saved credentials, first boot path, AP always on
+- `wfo` - fallback AP setting off, combine with `wap` to test off plus disconnected
+- `fws` - scan fault, `/api/wifi/scan` returns 500
+- `fwn` - empty scan, `/api/wifi/scan` returns no networks
+- `fwc` - connect fault, `/api/wifi/connect` rejects with auth error
+
+## Examples
+
+- `err|fa` - robot error plus action failures
+- `low|fl|fs` - low battery, log failures, and settings failure
+- `man|llq` - manual mode with degraded LIDAR
+- `wap|wfo` - disconnected station with fallback AP setting disabled
+- `upd|fhl` - update banner plus corrupted history list recovery state
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index e996aae..5f80661 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -1,17 +1,18 @@
-// Mock API server for Neato web UI development
-// Mimics all firmware REST endpoints with realistic stateful responses
-// Runs as a Vite plugin — hooks into Vite's dev server middleware
-// To test different scenarios, edit the `state` object directly and reload
+// Mock API server for Neato web UI development.
+// Runs as a Vite plugin and delegates route behavior to shared-api.js so the
+// Cloudflare demo Worker and local dev server stay aligned.
 
 import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createMockApi } from "./shared-api.js";
+import { createScenarioState, scenarioFromRequest } from "./shared-state.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// --- Helpers ---
+const rand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
 
 const getVersion = () => {
     try {
@@ -22,19 +23,16 @@ const getVersion = () => {
     }
 };
 
-const jsonResponse = (res, data, status = 200) => {
-    const body = JSON.stringify(data);
-    res.writeHead(status, {
-        "Content-Type": "application/json",
-        "Content-Length": Buffer.byteLength(body),
-    });
-    res.end(body);
+const sendResponse = (res, response) => {
+    const headers = { ...response.headers };
+    if (response.body !== undefined && !headers["Content-Length"]) {
+        headers["Content-Length"] = Buffer.byteLength(response.body);
+    }
+    res.writeHead(response.status, headers);
+    res.end(response.body ?? "");
 };
 
-const sendOk = (res) => jsonResponse(res, { ok: true });
-const sendError = (res, msg, status = 500) => jsonResponse(res, { error: msg }, status);
-
-// Request logging — captures original writeHead to log via Vite's logger
+// Request logging - captures original writeHead to log via Vite's logger.
 let viteLogger = null;
 
 const logRequest = (req, res) => {
@@ -51,345 +49,97 @@ const logRequest = (req, res) => {
     };
 };
 
-const readBody = (req) =>
+const readBodyBytes = (req) =>
     new Promise((resolve) => {
-        let body = "";
-        req.on("data", (chunk) => (body += chunk));
-        req.on("end", () => resolve(body));
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
     });
 
-const rand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
-const _randf = (min, max, decimals = 2) => parseFloat((Math.random() * (max - min) + min).toFixed(decimals));
-
-// --- Scenario selector ---
-// Change this value to switch between test states. Save and Vite hot-reloads.
-// Combine multiple scenarios with "|":
-//   "ok"          — Robot idle, online, battery 85%
-//   "err|fa"      — Robot error (brush stuck) + action faults
-//   "low|fl|fs"   — Low battery + log faults + settings fault
-//   "man|llq"     — Manual clean + low LIDAR quality
-//
-// Robot state:
-//   ok   — Idle, battery 85%          off  — Device unreachable
-//   ident — Identifying robot (boot)  unsup — Unsupported robot model
-//   upd  — Firmware v0.9 (triggers update banner)
-//   cls  — House cleaning             spt  — Spot cleaning
-//   dock — Docking (return to base)   rchg — Mid-clean recharge (on dock, charging)
-//   chg  — Charging, 62%              ch2  — Charging, 25%
-//   ful  — Full, on dock              mid  — Battery 45%
-//   low  — Battery 12%                ded  — Battery 0%
-//   err  — Brush stuck error          alrt — Alert only (brush change)
-//
-// Manual clean (combine with each other or fault scenarios):
-//   man  — Manual mode active (no safety issues)
-//   mlf  — Manual + robot lifted
-//   mbf  — Manual + front-left bumper contact
-//   mbs  — Manual + side-right bumper contact
-//   msf  — Manual + forward stall (reverse to clear)
-//   msr  — Manual + rear stall (move forward to clear)
-//
-// LIDAR quality (combine with any state):
-//   llq  — Low scan quality (<90 valid points)
-//   lsl  — Slow LDS rotation (2.8 Hz)
-//   lno  — LIDAR unavailable (GET /api/lidar returns error)
-//
-// Fault injection (combine with any state above):
-//   fa   — Action faults (clean house/spot/stop return errors)
-//   fs   — Settings fault (NVS write error)
-//   flr  — Log read fault (list + content fail)
-//   fld  — Log delete fault (delete single + delete all fail)
-//   fl   — All log faults (read + delete)
-//   fps  — Polling fault: GET /api/state
-//   fpc  — Polling fault: GET /api/charger
-//   fpe  — Polling fault: GET /api/error
-//   fp   — All polling faults (state + charger + error)
-//   fhc  — History corruption (inject corrupted pose lines in session data)
-//   fhl  — History list corruption (malformed JSON in /api/history response, triggers recovery panel)
-//
-// WiFi:
-//   wap  , Fallback AP active (STA disconnected, fallback enabled)
-//   wnc  , No saved credentials (first boot, AP always on)
-//   wfo  , Fallback AP setting off (combine with wap to test off + disconnected)
-//   fws  , Scan fault: /api/wifi/scan returns 500
-//   fwn  , Empty scan: /api/wifi/scan returns no networks
-//   fwc  , Connect fault: /api/wifi/connect rejects with auth error
-//
-//   fal  — All faults combined
-const SCENARIO = "ok";
-
-// --- Robot state ---
-
-const SCENARIOS = {
-    ok: {},
-    off: { offline: true },
-    cls: { cleaning: true },
-    spt: { spotCleaning: true },
-    chg: { fuelPercent: 62, chargingActive: true, extPwrPresent: true },
-    ch2: { fuelPercent: 25, chargingActive: true, extPwrPresent: true },
-    ful: { fuelPercent: 100, chargingActive: false, extPwrPresent: true },
-    mid: { fuelPercent: 45 },
-    low: { fuelPercent: 12 },
-    ded: { fuelPercent: 0 },
-    err: {
-        hasError: true,
-        kind: "error",
-        errorCode: 265,
-        errorMessage:
-            "Error\r\n265 -  (UI_ERROR_BRUSH_STUCK)\r\nAlert\r\n205 -  (UI_ALERT_DUST_BIN_FULL)\r\nUSB state \r\n NOT connected",
-        displayMessage: "Main brush is stuck",
-    },
-    alrt: {
-        hasError: true,
-        kind: "warning",
-        errorCode: 229,
-        errorMessage: "Error\r\n200 -  (UI_ALERT_INVALID)\r\nAlert\r\n229 -  (UI_ALERT_BRUSH_CHANGE)",
-        displayMessage: "Time to replace the brush",
-    },
-    dock: { docking: true, cleaning: false },
-    rchg: {
-        midCleanRecharge: true,
-        fuelPercent: 15,
-        chargingActive: true,
-        extPwrPresent: true,
-    },
-    man: { manualClean: true },
-    mlf: { manualClean: true, manualLifted: true },
-    mbf: { manualClean: true, manualBumperFrontLeft: true },
-    mbs: { manualClean: true, manualBumperSideRight: true },
-    msf: { manualClean: true, manualStallFront: true },
-    msr: { manualClean: true, manualStallRear: true },
-    ident: { identifying: true },
-    unsup: { unsupported: true },
-    upd: { firmwareVersion: "0.9" },
-    llq: { lidarLowQuality: true },
-    lsl: { lidarSlowRotation: true },
-    lno: { lidarUnavailable: true },
-    fa: { faults: { actions: true } },
-    fs: { faults: { settings: true } },
-    flr: { faults: { logsRead: true } },
-    fld: { faults: { logsDelete: true } },
-    fl: { faults: { logsRead: true, logsDelete: true } },
-    fps: { faults: { pollState: true } },
-    fpc: { faults: { pollCharger: true } },
-    fpe: { faults: { pollError: true } },
-    fp: { faults: { pollState: true, pollCharger: true, pollError: true } },
-    fhc: { faults: { historyCorrupt: true } },
-    fhl: { faults: { historyListCorrupt: true } },
-    wap: { wifiDisconnected: true },
-    wnc: { wifiDisconnected: true, wifiNoCredentials: true },
-    wfo: { apFallbackOnDisconnect: false },
-    fws: { faults: { wifiScan: true } },
-    fwn: { faults: { wifiScanEmpty: true } },
-    fwc: { faults: { wifiConnect: true } },
-    fal: {
-        faults: {
-            actions: true,
-            settings: true,
-            logsRead: true,
-            logsDelete: true,
-            pollState: true,
-            pollCharger: true,
-            pollError: true,
-            historyCorrupt: true,
-            historyListCorrupt: true,
-            wifiScan: true,
-            wifiConnect: true,
-        },
-    },
-};
-
-// Merge scenarios split by "|"
-const merged = {};
-const mergedFaults = {};
-for (const key of SCENARIO.split("|")) {
-    const s = SCENARIOS[key] || {};
-    const { faults: sf, ...rest } = s;
-    Object.assign(merged, rest);
-    if (sf) Object.assign(mergedFaults, sf);
-}
-merged.faults = mergedFaults;
-
-// Fault flags — toggled by scenarios, checked by route handlers
-const faults = {
-    actions: false,
-    settings: false,
-    logsRead: false,
-    logsDelete: false,
-    pollState: false,
-    pollCharger: false,
-    pollError: false,
-    historyCorrupt: false,
-    wifiScan: false,
-    wifiScanEmpty: false,
-    wifiConnect: false,
-    ...(merged.faults || {}),
-};
-
-const state = {
-    offline: false,
-    fuelPercent: 85,
-    chargingActive: false,
-    extPwrPresent: false,
-    cleaning: false,
-    spotCleaning: false,
-    docking: false,
-    paused: false,
-    uiState: "UIMGR_STATE_IDLE",
-    robotState: "ST_C_Idle",
-    hasError: false,
-    kind: "",
-    errorCode: 200,
-    errorMessage: "",
-    displayMessage: "",
-    manualClean: false,
-    // Manual clean motor + safety state
-    manualBrush: false,
-    manualVacuum: false,
-    manualSideBrush: false,
-    manualLifted: false,
-    manualBumperFrontLeft: false,
-    manualBumperFrontRight: false,
-    manualBumperSideLeft: false,
-    manualBumperSideRight: false,
-    manualStallFront: false,
-    manualStallRear: false,
-    // Mid-clean recharge (docking to charge, then resume)
-    midCleanRecharge: false,
-    // Robot model
-    identifying: false,
-    unsupported: false,
-    // Firmware version override (null = auto from git hash)
-    firmwareVersion: null,
-    // LIDAR quality overrides
-    lidarLowQuality: false,
-    lidarSlowRotation: false,
-    tz: "UTC0",
-    logLevel: 0,
-    apFallbackOnDisconnect: true,
-    // WiFi mock state , `wifiDisconnected` flips STA to disconnected and
-    // brings up the fallback AP; `wifiNoCredentials` clears saved SSID so
-    // the UI shows the "first boot" path (no current network, no forget).
-    wifiDisconnected: false,
-    wifiNoCredentials: false,
-    syslogEnabled: false,
-    syslogIp: "",
-    wifiTxPower: 60, // 15 dBm in 0.25 dBm units
-    uartTxPin: 3,
-    uartRxPin: 4,
-    maxGpioPin: 21,
-    hostname: "neato",
-    navMode: "Normal",
-    stallThreshold: 60,
-    brushRpm: 1200,
-    vacuumSpeed: 80,
-    sideBrushPower: 1500,
-    ntfyTopic: "",
-    ntfyEnabled: true,
-    ntfyOnDone: true,
-    ntfyOnError: true,
-    ntfyOnAlert: true,
-    ntfyOnDocking: true,
-    // Robot user settings (from GetUserSettings)
-    buttonClick: true,
-    melodies: true,
-    warnings: true,
-    ecoMode: false,
-    intenseClean: false,
-    binFullDetect: true,
-    wallEnable: true,
-    wifi: true,
-    stealthLed: false,
-    filterChange: 2592000,
-    brushChange: 2592000,
-    dirtBin: 30,
-    // Schedule (Mon=0..Sun=6), two slots per day
-    scheduleEnabled: true,
-    // Slot 0 (primary)
-    sched0Hour: 9,
-    sched0Min: 0,
-    sched0On: true, // Mon
-    sched1Hour: 9,
-    sched1Min: 0,
-    sched1On: true, // Tue
-    sched2Hour: 9,
-    sched2Min: 0,
-    sched2On: true, // Wed
-    sched3Hour: 9,
-    sched3Min: 0,
-    sched3On: true, // Thu
-    sched4Hour: 9,
-    sched4Min: 0,
-    sched4On: true, // Fri
-    sched5Hour: 0,
-    sched5Min: 0,
-    sched5On: false, // Sat
-    sched6Hour: 0,
-    sched6Min: 0,
-    sched6On: false, // Sun
-    // Slot 1 (secondary)
-    sched0Slot1Hour: 15,
-    sched0Slot1Min: 0,
-    sched0Slot1On: true, // Mon afternoon
-    sched1Slot1Hour: 15,
-    sched1Slot1Min: 0,
-    sched1Slot1On: true, // Tue afternoon
-    sched2Slot1Hour: 15,
-    sched2Slot1Min: 0,
-    sched2Slot1On: true, // Wed afternoon
-    sched3Slot1Hour: 15,
-    sched3Slot1Min: 0,
-    sched3Slot1On: true, // Thu afternoon
-    sched4Slot1Hour: 15,
-    sched4Slot1Min: 0,
-    sched4Slot1On: true, // Fri afternoon
-    sched5Slot1Hour: 0,
-    sched5Slot1Min: 0,
-    sched5Slot1On: false, // Sat
-    sched6Slot1Hour: 0,
-    sched6Slot1Min: 0,
-    sched6Slot1On: false, // Sun
-    ...merged,
+const createRequestAdapter = (req, parsed) => {
+    let cachedBody = null;
+    const bytes = async () => {
+        cachedBody ??= await readBodyBytes(req);
+        return cachedBody;
+    };
+    return {
+        method: req.method,
+        path: parsed.pathname,
+        query: Object.fromEntries(parsed.searchParams),
+        bytes,
+        text: async () => (await bytes()).toString("utf8"),
+    };
 };
 
-// Boot time for uptime calculation (mutable — reset by simulated reboot)
+// Select scenarios with ?scenario=err|fa. The page stores it in a cookie so
+// subsequent SPA API calls keep using the selected mock state.
+let initializedScenario = null;
 let bootTime = Date.now();
 
-// --- Derived helpers ---
-
-const vBattFromFuel = (fuel) => parseFloat((12.0 + (fuel / 100) * 4.6).toFixed(2));
-
-// --- LIDAR captured scans (real data from Neato D7) ---
-
 const lidarScans = readdirSync(__dirname)
     .filter((f) => f.startsWith("lidar-scan") && f.endsWith(".json"))
     .sort()
     .map((f) => JSON.parse(readFileSync(join(__dirname, f), "utf8")));
 let lidarScanIndex = 0;
 
-// --- Map data — in-memory session store ---
-// Load mapdata-*.jsonl files into memory at startup. The active recording
-// session (no summary line) grows via random-walk timer — no file I/O.
+const getLidarScan = () => {
+    const scan = lidarScans[lidarScanIndex];
+    lidarScanIndex = (lidarScanIndex + 1) % lidarScans.length;
+    return scan;
+};
 
-const historySessions = new Map(); // name -> string[] (JSONL lines)
+const loadHistorySessions = () => {
+    const sessions = new Map();
 
-for (const f of readdirSync(__dirname)
-    .filter((n) => n.startsWith("mapdata-") && n.endsWith(".jsonl"))
-    .sort()) {
-    const lines = readFileSync(join(__dirname, f), "utf8")
-        .trim()
-        .split("\n")
-        .filter((l) => l.length > 0);
-    historySessions.set(f, lines);
-}
+    for (const f of readdirSync(__dirname)
+        .filter((n) => n.startsWith("mapdata-") && n.endsWith(".jsonl"))
+        .sort()) {
+        const lines = readFileSync(join(__dirname, f), "utf8")
+            .trim()
+            .split("\n")
+            .filter((line) => line.length > 0);
+        sessions.set(f, lines);
+    }
+
+    return sessions;
+};
+
+const context = {
+    state: {},
+    faults: {},
+    historySessions: loadHistorySessions(),
+    rand,
+    getVersion,
+    getLidarScan,
+    getBootTime: () => bootTime,
+    reboot: () => {
+        setTimeout(() => {
+            bootTime = Date.now();
+        }, 2000);
+    },
+    shutdown: () => setTimeout(() => process.exit(0), 500),
+    md5Hex: (bytes) => createHash("md5").update(Buffer.from(bytes)).digest("hex"),
+};
+
+const initScenario = (scenario) => {
+    if (scenario === initializedScenario) return;
+    const scenarioState = createScenarioState(scenario);
+    context.state = scenarioState.state;
+    context.faults = scenarioState.faults;
+    context.historySessions = loadHistorySessions();
+    bootTime = Date.now();
+    initializedScenario = scenario;
+};
 
-// Find the active recording session (no summary line) and start random-walk timer
-const recordingFile = [...historySessions.entries()].find(
-    ([, lines]) => !lines.some((l) => l.includes('"type":"summary"')),
+initScenario("ok");
+
+const recordingFile = [...context.historySessions.entries()].find(
+    ([, lines]) => !lines.some((line) => line.includes('"type":"summary"')),
 );
 
 if (recordingFile) {
     const [recordingName, recordingLines] = recordingFile;
-    const lastPose = [...recordingLines].reverse().find((l) => l.includes('"x":'));
+    const lastPose = [...recordingLines].reverse().find((line) => line.includes('"x":'));
     const pos = lastPose ? JSON.parse(lastPose) : { x: 0, y: 0, t: 0, ts: 7244 };
     let simX = pos.x;
     let simY = pos.y;
@@ -405,910 +155,42 @@ if (recordingFile) {
         simX += Math.cos(rad) * step;
         simY -= Math.sin(rad) * step;
         simTs += 2.0 + Math.random() * 0.3;
-        const lines = historySessions.get(recordingName);
-        // Rolling window: drop oldest coordinate (keep session header at [0])
+        const lines = context.historySessions.get(recordingName);
         if (lines.length > 1) lines.splice(1, 1);
         lines.push(`{"x":${simX.toFixed(3)},"y":${simY.toFixed(3)},"t":${simT.toFixed(1)},"ts":${simTs.toFixed(1)}}`);
     }, 2000);
 }
 
-const getLidarScan = () => {
-    const scan = lidarScans[lidarScanIndex];
-    lidarScanIndex = (lidarScanIndex + 1) % lidarScans.length;
-    return scan;
-};
-
-// --- Mock log files ---
-
-const mockLogs = [
-    { name: "current.jsonl", size: 8192, compressed: false },
-    { name: "1700000000.jsonl.hs", size: 4096, compressed: true },
-    { name: "boot_2501.jsonl.hs", size: 1851, compressed: true },
-];
-
-const mockLogContent = [
-    '{"t":1700000100,"typ":"boot","d":{"reason":"power_on","heap":195000}}',
-    '{"t":1700000101,"typ":"wifi","d":{"event":"connected","rssi":-52}}',
-    '{"t":1700000102,"typ":"ntp","d":{"event":"sync_ok","epoch":1700000102}}',
-    '{"t":1700000200,"typ":"command","d":{"cmd":"GetCharger","status":"ok","ms":85,"q":0,"bytes":312,"resp":"GetCharger\\r\\nLabel,Value\\r\\nFuelPercent,85\\r\\nBatteryOverTemp,0\\r\\nChargingActive,0\\r\\nChargingEnabled,1\\r\\n"}}',
-    '{"t":1700000202,"typ":"command","d":{"cmd":"GetState","status":"ok","ms":42,"q":0,"bytes":95,"resp":"GetState\\r\\nCurrent UI State is: UIMGR_STATE_IDLE\\nCurrent Robot State is: ST_C_Idle\\n"}}',
-    '{"t":1700000203,"typ":"command","d":{"cmd":"GetState","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
-    '{"t":1700000210,"typ":"request","d":{"method":"GET","path":"/api/charger","status":200,"ms":92}}',
-    '{"t":1700000215,"typ":"command","d":{"cmd":"GetErr","status":"ok","ms":38,"q":0,"bytes":64,"resp":"GetErr\\r\\nError\\r\\n200 -  (UI_ALERT_INVALID)\\r\\nAlert\\r\\n200 -  (UI_ALERT_INVALID)\\r\\n"}}',
-    '{"t":1700000216,"typ":"command","d":{"cmd":"GetErr","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
-    '{"t":1700000220,"typ":"request","d":{"method":"GET","path":"/api/state","status":200,"ms":48}}',
-    '{"t":1700000300,"typ":"command","d":{"cmd":"GetAnalogSensors","status":"ok","ms":120,"q":1,"bytes":480}}',
-    '{"t":1700000305,"typ":"request","d":{"method":"POST","path":"/api/clean?action=house","status":200,"ms":210}}',
-    '{"t":1700000306,"typ":"command","d":{"cmd":"Clean House","status":"ok","ms":95,"q":0,"bytes":28}}',
-    '{"t":1700000400,"typ":"event","d":{"msg":"cleaning_started","mode":"house"}}',
-    '{"t":1700000500,"typ":"command","d":{"cmd":"GetMotors","status":"ok","ms":110,"q":2,"bytes":520}}',
-    '{"t":1700000600,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":450,"q":0,"bytes":8200}}',
-    '{"t":1700000601,"typ":"command","d":{"cmd":"GetCharger","status":"ok","ms":0,"q":0,"bytes":0,"age":401}}',
-
-    '{"t":1700000615,"typ":"request","d":{"method":"GET","path":"/api/lidar","status":200,"ms":460}}',
-    '{"t":1700000620,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":440,"q":1,"bytes":8140}}',
-    '{"t":1700000621,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
-
-    '{"t":1700000700,"typ":"event","d":{"msg":"cleaning_completed","duration":600}}',
-].join("\n");
-
-// --- Derive UI/robot state from current state ---
-
-const deriveStates = () => {
-    if (state.manualClean) {
-        state.uiState = "UIMGR_STATE_MANUALCLEANING";
-        state.robotState = "ST_C_ManualCleaning";
-    } else if (state.midCleanRecharge) {
-        state.uiState = "UIMGR_STATE_CLEANINGSUSPENDED";
-        state.robotState = "ST_M1_Charging_Cleaning";
-    } else if (state.docking) {
-        state.uiState = "UIMGR_STATE_DOCKINGRUNNING";
-        state.robotState = "ST_C_Docking";
-    } else if (state.cleaning && !state.paused) {
-        state.uiState = "UIMGR_STATE_HOUSECLEANINGRUNNING";
-        state.robotState = "ST_C_HouseCleaning";
-    } else if (state.cleaning && state.paused) {
-        state.uiState = "UIMGR_STATE_HOUSECLEANINGPAUSED";
-        state.robotState = "ST_C_Standby";
-    } else if (state.spotCleaning && !state.paused) {
-        state.uiState = "UIMGR_STATE_SPOTCLEANINGRUNNING";
-        state.robotState = "ST_C_SpotCleaning";
-    } else if (state.spotCleaning && state.paused) {
-        state.uiState = "UIMGR_STATE_SPOTCLEANINGPAUSED";
-        state.robotState = "ST_C_Standby";
-    } else {
-        state.uiState = "UIMGR_STATE_IDLE";
-        state.robotState = "ST_C_Idle";
-    }
-};
-
-// --- Route handlers ---
-
-const routes = {
-    // Sensor routes
-    "GET /api/version": (_req, res) => {
-        jsonResponse(res, {
-            modelName: "BotVacD7",
-            serialNumber: "OPS01234AA,0000001,D",
-            softwareVersion: "4.5.3-142",
-            ldsVersion: "V2.6.15295",
-            ldsSerial: "KSH-V5F4",
-            mainBoardVersion: "15.0",
-            smartBatteryAuthorization: 1,
-            smartBatteryDataVersion: 512,
-            smartBatteryChemistry: "LION1",
-            smartBatteryDeviceName: "F164A10288",
-            smartBatteryManufacturerName: "Panasonic",
-            smartBatteryMfgDate: "2089-02-18",
-            smartBatterySerialNumber: "34832",
-            smartBatterySoftwareVersion: "2048",
-        });
-    },
-
-    "GET /api/charger": (_req, res) => {
-        if (faults.pollCharger) return sendError(res, "UART timeout reading charger", 500);
-        const fuel = Math.round(state.fuelPercent);
-        jsonResponse(res, {
-            fuelPercent: fuel,
-            batteryOverTemp: false,
-            chargingActive: state.chargingActive,
-            chargingEnabled: true,
-            confidOnFuel: fuel > 20,
-            onReservedFuel: fuel < 10,
-            emptyFuel: fuel === 0,
-            batteryFailure: false,
-            extPwrPresent: state.extPwrPresent,
-            vBattV: vBattFromFuel(fuel),
-            vExtV: state.extPwrPresent ? 22.3 : 0.0,
-            chargerMAH: state.chargingActive ? 1200 : 0,
-            dischargeMAH: Math.round(((100 - fuel) / 100) * 2800),
-        });
-    },
-
-    "GET /api/analog": (_req, res) => {
-        if (faults.pollCharger) return sendError(res, "UART timeout reading battery diagnostics", 500);
-        const fuel = Math.round(state.fuelPercent);
-        const batteryCurrentMA = state.chargingActive
-            ? rand(180, 720)
-            : state.extPwrPresent
-              ? rand(-20, 20)
-              : -rand(80, 420);
-        const batteryTemperatureC = parseFloat((24 + (state.chargingActive ? 1.8 : 0) + Math.random()).toFixed(1));
-
-        jsonResponse(res, {
-            batteryVoltageV: vBattFromFuel(fuel),
-            batteryCurrentMA,
-            batteryTemperatureC,
-            externalVoltageV: state.extPwrPresent ? 18.66 : 0.0,
-        });
-    },
-
-    "GET /api/warranty": (_req, res) => {
-        jsonResponse(res, {
-            cumulativeBatteryCycles: 728,
-            cumulativeCleaningTimeSeconds: 885884,
-            validationCode: "b40b2e9a",
-        });
-    },
-
-    "POST /api/battery/new": (_req, res) => {
-        jsonResponse(res, { ok: true });
-    },
-
-    "GET /api/motors": (_req, res) => {
-        const cleaning = state.cleaning || state.spotCleaning;
-        jsonResponse(res, {
-            brushRPM: cleaning ? rand(1100, 1300) : 0,
-            brushMA: cleaning ? rand(200, 400) : 0,
-            vacuumRPM: cleaning ? rand(2200, 2600) : 0,
-            vacuumMA: cleaning ? rand(400, 700) : 0,
-            leftWheelRPM: cleaning ? rand(60, 120) : 0,
-            leftWheelLoad: cleaning ? rand(10, 40) : 0,
-            leftWheelPositionMM: state.leftWheelPos,
-            leftWheelSpeed: cleaning ? rand(150, 300) : 0,
-            rightWheelRPM: cleaning ? rand(60, 120) : 0,
-            rightWheelLoad: cleaning ? rand(10, 40) : 0,
-            rightWheelPositionMM: state.rightWheelPos,
-            rightWheelSpeed: cleaning ? rand(150, 300) : 0,
-            sideBrushMA: cleaning ? rand(50, 200) : 0,
-            laserRPM: cleaning ? rand(290, 310) : 0,
-        });
-    },
-
-    "GET /api/state": (_req, res) => {
-        if (faults.pollState) return sendError(res, "UART timeout reading state", 500);
-        deriveStates();
-        jsonResponse(res, {
-            uiState: state.uiState,
-            robotState: state.robotState,
-        });
-    },
-
-    "GET /api/error": (_req, res) => {
-        if (faults.pollError) return sendError(res, "UART timeout reading error", 500);
-        jsonResponse(res, {
-            hasError: state.hasError,
-            kind: state.kind,
-            errorCode: state.errorCode,
-            errorMessage: state.errorMessage,
-            displayMessage: state.displayMessage,
-        });
-    },
-
-    "GET /api/lidar": (_req, res) => {
-        if (state.lidarUnavailable) return sendError(res, "UART timeout reading LDS scan", 500);
-        const scan = getLidarScan();
-        // Degrade scan for quality scenarios
-        if (state.lidarLowQuality || state.lidarSlowRotation) {
-            const degraded = { ...scan };
-            if (state.lidarSlowRotation) degraded.rotationSpeed = 2.8;
-            if (state.lidarLowQuality) {
-                // Zero out most points to simulate poor readings
-                degraded.points = scan.points.map((p, i) =>
-                    i % 5 === 0 ? p : { ...p, dist: 0, intensity: 0, error: 8035 },
-                );
-                degraded.validPoints = degraded.points.filter((p) => p.dist > 0).length;
-            }
-            return jsonResponse(res, degraded);
-        }
-        jsonResponse(res, scan);
-    },
-
-    // Action routes — parameterized via query string
-    "POST /api/clean": (_req, res, query) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        const action = query.action || "house";
-        if (action === "dock") {
-            if (state.cleaning || state.spotCleaning) {
-                state.docking = true; // Simulate return-to-base
-                state.cleaning = false;
-                state.spotCleaning = false;
-                state.paused = false;
-            }
-        } else if (action === "pause") {
-            if ((state.cleaning || state.spotCleaning) && !state.paused) {
-                state.paused = true; // Running -> Paused
-            }
-        } else if (action === "stop") {
-            state.cleaning = false;
-            state.spotCleaning = false;
-            state.docking = false;
-            state.paused = false;
-        } else if (action === "spot") {
-            state.spotCleaning = true;
-            state.cleaning = false;
-            state.docking = false;
-            state.paused = false;
-        } else {
-            state.cleaning = true;
-            state.spotCleaning = false;
-            state.docking = false;
-            state.paused = false;
-        }
-        deriveStates();
-        sendOk(res);
-    },
-
-    "GET /api/manual/status": (_req, res) => {
-        jsonResponse(res, {
-            active: state.manualClean,
-            brush: state.manualBrush,
-            vacuum: state.manualVacuum,
-            sideBrush: state.manualSideBrush,
-            lifted: state.manualLifted,
-            bumperFrontLeft: state.manualBumperFrontLeft,
-            bumperFrontRight: state.manualBumperFrontRight,
-            bumperSideLeft: state.manualBumperSideLeft,
-            bumperSideRight: state.manualBumperSideRight,
-            stallFront: state.manualStallFront,
-            stallRear: state.manualStallRear,
-        });
-    },
-
-    "POST /api/manual/move": (_req, res) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        if (!state.manualClean) return sendError(res, "Not in manual mode", 400);
-        sendOk(res);
-    },
-
-    "POST /api/manual/motors": (_req, res, query) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        if (!state.manualClean) return sendError(res, "Not in manual mode", 400);
-        state.manualBrush = query.brush === "1";
-        state.manualVacuum = query.vacuum === "1";
-        state.manualSideBrush = query.sideBrush === "1";
-        setTimeout(() => sendOk(res), 600);
-    },
-
-    "POST /api/power": (_req, res, query) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        const action = query.action;
-        if (action === "restart") {
-            // Simulate robot power cycle — robot recovers in ~1s, ESP32 stays online
-            sendOk(res);
-        } else if (action === "shutdown") {
-            // Simulate real ESP32 power loss — respond then kill the dev server
-            sendOk(res);
-            setTimeout(() => process.exit(0), 500);
-        } else {
-            sendError(res, "unknown action", 400);
-        }
-    },
-
-    "POST /api/clear-errors": (_req, res) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        sendOk(res);
-    },
-
-    "POST /api/sound": (_req, res) => {
-        // Accept and ignore — just acknowledge
-        sendOk(res);
-    },
-
-    "POST /api/manual": (_req, res, query) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        const enable = query.enable === "1";
-        state.manualClean = enable;
-        if (enable) {
-            state.cleaning = false;
-            state.spotCleaning = false;
-            state.paused = false;
-        }
-        // Reset motor and safety state on enable/disable
-        state.manualBrush = false;
-        state.manualVacuum = false;
-        state.manualSideBrush = false;
-        if (!enable) {
-            state.manualLifted = false;
-            state.manualBumperFrontLeft = false;
-            state.manualBumperFrontRight = false;
-            state.manualBumperSideLeft = false;
-            state.manualBumperSideRight = false;
-            state.manualStallFront = false;
-            state.manualStallRear = false;
-        }
-        deriveStates();
-        sendOk(res);
-    },
-
-    "POST /api/lidar/rotate": (_req, res) => {
-        if (faults.actions) return sendError(res, "UART timeout: robot not responding", 500);
-        // LDS rotation is fire-and-forget — no state change visible in polls
-        sendOk(res);
-    },
-
-    // Log routes
-    "GET /api/logs": (_req, res) => {
-        if (faults.logsRead) return sendError(res, "SPIFFS read failed", 500);
-        jsonResponse(res, mockLogs);
-    },
-
-    "DELETE /api/logs": (_req, res) => {
-        if (faults.logsDelete) return sendError(res, "SPIFFS busy, try again later", 503);
-        sendOk(res);
-    },
-
-    // System routes
-    "GET /api/system": (_req, res) => {
-        const now = new Date();
-        const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
-        const pad = (n) => n.toString().padStart(2, "0");
-        const localTime = `${days[now.getDay()]} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
-        jsonResponse(res, {
-            heap: rand(160000, 200000),
-            heapTotal: 327680,
-            uptime: Date.now() - bootTime,
-            rssi: rand(-65, -40),
-            fsUsed: rand(10000, 50000),
-            fsTotal: 262144,
-            ntpSynced: true,
-            time: Math.floor(Date.now() / 1000),
-            timeSource: "ntp",
-            tz: state.tz,
-            localTime,
-            isDst: now.getTimezoneOffset() !== new Date(now.getFullYear(), 0, 1).getTimezoneOffset(),
-        });
-    },
-
-    "POST /api/system/restart": (_req, res) => {
-        sendOk(res);
-        setTimeout(() => {
-            bootTime = Date.now();
-        }, 2000);
-    },
-
-    "POST /api/system/format-fs": (_req, res) => {
-        sendOk(res);
-        setTimeout(() => {
-            bootTime = Date.now();
-        }, 2000);
-    },
-
-    "POST /api/system/reset": (_req, res) => {
-        sendOk(res);
-        setTimeout(() => {
-            bootTime = Date.now();
-        }, 2000);
-    },
-
-    "GET /api/settings": (_req, res) => {
-        const s = {};
-        const keys = [
-            "tz",
-            "logLevel",
-            "apFallbackOnDisconnect",
-            "syslogEnabled",
-            "syslogIp",
-            "wifiTxPower",
-            "uartTxPin",
-            "uartRxPin",
-            "maxGpioPin",
-            "hostname",
-            "navMode",
-            "stallThreshold",
-            "brushRpm",
-            "vacuumSpeed",
-            "sideBrushPower",
-            "ntfyTopic",
-            "ntfyEnabled",
-            "ntfyOnDone",
-            "ntfyOnError",
-            "ntfyOnAlert",
-            "ntfyOnDocking",
-            "scheduleEnabled",
-        ];
-        for (const k of keys) s[k] = state[k];
-        for (let d = 0; d < 7; d++) {
-            s[`sched${d}Hour`] = state[`sched${d}Hour`];
-            s[`sched${d}Min`] = state[`sched${d}Min`];
-            s[`sched${d}On`] = state[`sched${d}On`];
-            s[`sched${d}Slot1Hour`] = state[`sched${d}Slot1Hour`];
-            s[`sched${d}Slot1Min`] = state[`sched${d}Slot1Min`];
-            s[`sched${d}Slot1On`] = state[`sched${d}Slot1On`];
-        }
-        jsonResponse(res, s);
-    },
-
-    "GET /api/wifi/status": (_req, res) => {
-        // No saved credentials: STA never reports a "last SSID" and the
-        // fallback AP is always up regardless of the toggle.
-        const hasCreds = !state.wifiNoCredentials;
-        const apOn = !!state.wifiDisconnected || !hasCreds;
-        jsonResponse(res, {
-            staConnected: !state.wifiDisconnected && hasCreds,
-            ssid: hasCreds ? "HomeWiFi" : "",
-            ip: state.wifiDisconnected || !hasCreds ? "" : "192.168.1.42",
-            rssi: state.wifiDisconnected || !hasCreds ? 0 : -52,
-            apActive: apOn,
-            apSsid: apOn ? `${state.hostname}-ap` : "",
-            apIp: apOn ? "192.168.4.1" : "",
-            apClients: apOn ? (hasCreds ? 1 : 0) : 0,
-            apFallbackOnDisconnect: state.apFallbackOnDisconnect,
-            lastError: state.wifiDisconnected && hasCreds ? "wrong password or authentication rejected" : "",
-        });
-    },
-
-    "GET /api/wifi/scan": async (_req, res) => {
-        // Simulate scan latency
-        await new Promise((r) => setTimeout(r, rand(800, 1500)));
-        if (faults.wifiScan) return sendError(res, "WiFi scan failed: radio busy", 500);
-        if (faults.wifiScanEmpty) return jsonResponse(res, { networks: [] });
-        jsonResponse(res, {
-            networks: [
-                { ssid: "HomeWiFi", rssi: -52, open: false },
-                { ssid: "Neighbour-5G", rssi: -68, open: false },
-                { ssid: "GuestNet", rssi: -71, open: true },
-                { ssid: "FritzBox-2", rssi: -78, open: false },
-                { ssid: "TP-Link-Guest", rssi: -82, open: true },
-            ],
-        });
-    },
-
-    "POST /api/wifi/connect": async (_req, res, query) => {
-        if (!query.ssid) return sendError(res, "missing ssid", 400);
-        await new Promise((r) => setTimeout(r, rand(500, 1500)));
-        if (faults.wifiConnect) {
-            return sendError(res, "wrong password or authentication rejected", 500);
-        }
-        // Simulate reboot path on success , caller will see the AP go away
-        state.wifiDisconnected = false;
-        state.wifiNoCredentials = false;
-        sendOk(res);
-    },
-
-    "POST /api/wifi/disconnect": (_req, res) => {
-        state.wifiDisconnected = true;
-        state.wifiNoCredentials = true;
-        sendOk(res);
-    },
-
-    "POST /api/notifications/test": (_req, res, query) => {
-        if (!query.topic) return sendError(res, "missing topic", 400);
-        sendOk(res);
-    },
-
-    "GET /repos/renjfk/OpenNeato/releases/latest": (_req, res) => {
-        jsonResponse(res, { tag_name: "v1.0" });
-    },
-
-    "GET /api/user-settings": (_req, res) => {
-        jsonResponse(res, {
-            buttonClick: state.buttonClick,
-            melodies: state.melodies,
-            warnings: state.warnings,
-            ecoMode: state.ecoMode,
-            intenseClean: state.intenseClean,
-            binFullDetect: state.binFullDetect,
-            wallEnable: state.wallEnable,
-            wifi: state.wifi,
-            stealthLed: state.stealthLed,
-            filterChange: state.filterChange,
-            brushChange: state.brushChange,
-            dirtBin: state.dirtBin,
-        });
-    },
-
-    "POST /api/user-settings": (_req, res, query) => {
-        const keyMap = {
-            ButtonClick: "buttonClick",
-            Melodies: "melodies",
-            Warnings: "warnings",
-            EcoMode: "ecoMode",
-            IntenseClean: "intenseClean",
-            BinFullDetect: "binFullDetect",
-            WallEnable: "wallEnable",
-            WiFi: "wifi",
-            StealthLED: "stealthLed",
-            FilterChange: "filterChange",
-            BrushChange: "brushChange",
-            DirtBin: "dirtBin",
-        };
-        const serialKey = query.key;
-        const value = query.value;
-        if (!serialKey || !value) return sendError(res, "missing key or value", 400);
-        const stateKey = keyMap[serialKey];
-        if (!stateKey) return sendError(res, "unknown key", 400);
-        if (["filterChange", "brushChange", "dirtBin"].includes(stateKey)) {
-            state[stateKey] = parseInt(value, 10);
-        } else {
-            state[stateKey] = value.toUpperCase() === "ON";
-        }
-        sendOk(res);
-    },
-
-    "GET /api/firmware/version": (_req, res) => {
-        jsonResponse(res, {
-            name: "OpenNeato",
-            version: state.firmwareVersion ?? getVersion(),
-            chip: "ESP32-C3",
-            model: state.identifying ? "" : state.unsupported ? "Botvac Connected" : "Botvac D7",
-            hostname: "neato-kitchen",
-            supported: !state.unsupported && !state.identifying,
-            identifying: state.identifying,
-            repositoryUrl: "https://github.com/renjfk/OpenNeato",
-            license: "MIT",
-        });
-    },
-};
-
-// --- Core request handler ---
+const api = createMockApi(context);
 
 const handleRequest = async (req, res) => {
-    // Simulate device unreachable — drop connection
-    if (state.offline) {
-        req.destroy();
-        return;
-    }
-
     const parsed = new URL(req.url, "http://localhost");
-    const path = parsed.pathname;
-    const query = Object.fromEntries(parsed.searchParams);
-
-    // Match history routes: GET /api/history, GET/DELETE /api/history/{filename}
-    // Inject corrupted pose lines to test frontend repair logic (simulates
-    // heatshrink decompression artifacts: '.' -> ':', '.' -> '"', digit -> letter)
-    const injectCorruptedPoses = (lines) => {
-        const corruptions = [
-            '{"x":-0.798,"y":3.459,"t":100:5,"ts":8203.4}',
-            '{"x":-0.785,"y":4.192,"t":100:3,"ts":8208.1}',
-            '{"x":-1.286,"y":4.007,"t":177:5,"ts":8215.6}',
-            '{"x":-1.8"3,"y":2.254,"t":181.0,"ts":8288.6}',
-            '{"x":-1.946,"y":2.0"3,"t":181.9,"ts":8312.8}',
-            '{"x":-4.793,"y":-1.6t2,"t":356.5,"ts":9182.5}',
-            '{"x":-1.740,"y":3.510,"t":1.6,"ts":8242:0}',
-        ];
-        const result = [lines[0]];
-        for (let i = 1; i < lines.length; i++) {
-            result.push(lines[i]);
-            // Sprinkle corrupted lines at ~5% rate among pose lines
-            if (!lines[i].includes('"type"') && i % 20 === 0) {
-                result.push(corruptions[i % corruptions.length]);
-            }
-        }
-        return result;
-    };
-
-    if (path === "/api/history" && req.method === "GET") {
-        // List sessions from in-memory store with embedded session/summary metadata
-        const list = [...historySessions.entries()].map(([name, lines]) => {
-            let session = null;
-            let summary = null;
-            if (lines.length > 0) {
-                try {
-                    const first = JSON.parse(lines[0]);
-                    if (first.type === "session") session = first;
-                } catch {}
-            }
-            if (lines.length > 1) {
-                try {
-                    const last = JSON.parse(lines[lines.length - 1]);
-                    if (last.type === "summary") summary = last;
-                } catch {}
-            }
-            const raw = `${lines.join("\n")}\n`;
-            return {
-                name,
-                size: Buffer.byteLength(raw),
-                compressed: name.endsWith(".hs"),
-                recording: summary === null,
-                session,
-                summary,
-            };
-        });
-        // Mimic the firmware bug from issue #90: one session's summary field
-        // contains a truncated pose snapshot concatenated with the real
-        // summary, which makes the entire response unparseable. Triggers the
-        // recovery panel in the frontend.
-        if (faults.historyListCorrupt && list.length > 0) {
-            const target = list[Math.min(1, list.length - 1)];
-            const summaryJson = target.summary ? JSON.stringify(target.summary) : '{"type":"summary"}';
-            const corruptedSummary = `{"x":-0.218,"y":0.007,"t":35${summaryJson.slice(1)}`;
-            const body = JSON.stringify(list).replace(JSON.stringify(target.summary ?? null), corruptedSummary);
-            res.writeHead(200, {
-                "Content-Type": "application/json",
-                "Content-Length": Buffer.byteLength(body),
-            });
-            res.end(body);
-            return;
-        }
-        return jsonResponse(res, list);
-    }
-
-    if (path === "/api/history" && req.method === "DELETE") {
-        historySessions.clear();
-        return sendOk(res);
-    }
-
-    // POST /api/history/import — accept multipart upload, parse JSONL, store in memory
-    if (path === "/api/history/import" && req.method === "POST") {
-        const chunks = [];
-        await new Promise((resolve) => {
-            req.on("data", (chunk) => chunks.push(chunk));
-            req.on("end", resolve);
-        });
-        const body = Buffer.concat(chunks);
-        const bodyStr = body.toString("binary");
-        // Extract filename from Content-Disposition header in multipart body
-        const nameMatch = bodyStr.match(/filename="([^"]+)"/);
-        if (!nameMatch?.[1].endsWith(".jsonl")) {
-            return sendError(res, "Invalid file: expected a .jsonl session file", 400);
-        }
-        const filename = nameMatch[1];
-        // Extract file content between multipart headers and closing boundary
-        const headerEnd = bodyStr.indexOf("\r\n\r\n");
-        const boundaryEnd = bodyStr.lastIndexOf("\r\n--");
-        if (headerEnd < 0 || boundaryEnd < 0) {
-            return sendError(res, "Malformed multipart body", 400);
-        }
-        const content = body.subarray(headerEnd + 4, boundaryEnd).toString("utf8");
-        const lines = content
-            .trim()
-            .split("\n")
-            .filter((l) => l.length > 0);
-        if (lines.length === 0) {
-            return sendError(res, "Empty session file", 400);
-        }
-        // Validate first line is a session header with matching timestamp
-        try {
-            const header = JSON.parse(lines[0]);
-            if (header.type !== "session") {
-                return sendError(res, "First line must be a session header", 400);
-            }
-            // Filename is <epoch>.jsonl — extract epoch and compare to header time
-            const fileEpoch = filename.replace(".jsonl", "");
-            if (header.time !== undefined && String(header.time) !== fileEpoch) {
-                return sendError(res, "Session timestamp does not match filename", 400);
-            }
-        } catch {
-            return sendError(res, "Invalid JSON in session header", 400);
-        }
-        // Check for duplicate — firmware stores as .hs, but also check raw name
-        const storedName = `${filename}.hs`;
-        if (historySessions.has(storedName) || historySessions.has(filename)) {
-            return sendError(res, "Session already exists", 409);
-        }
-        historySessions.set(storedName, lines);
-        // Simulate compression delay
-        await new Promise((r) => setTimeout(r, rand(200, 500)));
-        return sendOk(res);
-    }
-
-    const historyMatch = path.match(/^\/api\/history\/(.+)$/);
-    if (historyMatch) {
-        const filename = historyMatch[1];
-        if (req.method === "GET") {
-            const lines = historySessions.get(filename);
-            if (!lines) return sendError(res, "session not found", 404);
-            const served = faults.historyCorrupt ? injectCorruptedPoses(lines) : lines;
-            const raw = `${served.join("\n")}\n`;
-            res.writeHead(200, {
-                "Content-Type": "application/x-ndjson",
-                "Content-Length": Buffer.byteLength(raw),
-            });
-            return res.end(raw);
-        }
-        if (req.method === "DELETE") {
-            historySessions.delete(filename);
-            return sendOk(res);
-        }
-        return sendError(res, "method not allowed", 405);
-    }
-
-    // Match log file routes: GET/DELETE /api/logs/{filename}
-    const logFileMatch = path.match(/^\/api\/logs\/(.+)$/);
-    if (logFileMatch) {
-        const filename = logFileMatch[1];
-        if (req.method === "GET") {
-            if (faults.logsRead) return sendError(res, "SPIFFS read failed", 500);
-            res.writeHead(200, {
-                "Content-Type": "application/x-ndjson",
-                "Content-Disposition": `attachment; filename="${filename.replace(/\.hs$/, "")}"`,
-            });
-            return res.end(mockLogContent);
-        }
-        if (req.method === "DELETE") {
-            if (faults.logsDelete) return sendError(res, "SPIFFS busy, try again later", 503);
-            return sendOk(res);
-        }
-        return sendError(res, "method not allowed", 405);
-    }
-
-    // POST /api/firmware/update?hash=<md5> — validate chip ID + MD5, simulate flash write, reboot
-    if (req.method === "POST" && path === "/api/firmware/update") {
-        const expectedMd5 = query.hash || "";
-        if (!expectedMd5) return sendError(res, "MD5 hash required", 400);
-        const MOCK_CHIP_ID = 5; // ESP32-C3
-        const chunks = [];
-        await new Promise((resolve) => {
-            req.on("data", (chunk) => chunks.push(chunk));
-            req.on("end", resolve);
-        });
-        // Extract file bytes from multipart body (skip boundary/headers, find file content)
-        const body = Buffer.concat(chunks);
-        const bodyStr = body.toString("binary");
-        const headerEnd = bodyStr.indexOf("\r\n\r\n");
-        // Find end of file content (before the closing boundary)
-        const boundaryEnd = bodyStr.lastIndexOf("\r\n--");
-        const fileStart = headerEnd !== -1 ? headerEnd + 4 : -1;
-        const fileEnd = boundaryEnd > fileStart ? boundaryEnd : body.length;
-        if (fileStart !== -1) {
-            if (body.length >= fileStart + 16) {
-                const chipId = body[fileStart + 12];
-                if (chipId !== MOCK_CHIP_ID) {
-                    return sendError(res, "Firmware chip mismatch: file targets a different ESP32 variant", 400);
-                }
-            }
-            // MD5 verification — mirrors ESP32 Update.setMD5 / Update.end(true) behavior
-            const fileBytes = body.subarray(fileStart, fileEnd);
-            const actualMd5 = createHash("md5").update(fileBytes).digest("hex");
-            if (actualMd5 !== expectedMd5.toLowerCase()) {
-                return sendError(res, "MD5 mismatch: firmware integrity check failed", 400);
-            }
-        }
-        // Simulate flash write: 3-5s delay
-        await new Promise((r) => setTimeout(r, rand(3000, 5000)));
-        sendOk(res);
-        setTimeout(() => {
-            bootTime = Date.now();
-        }, 2000);
+    initScenario(scenarioFromRequest(parsed.searchParams, req.headers.cookie));
+    const response = await api.handle(createRequestAdapter(req, parsed));
+    if (response === false) return false;
+    if (response.offline) {
+        req.destroy();
         return;
     }
-
-    // PUT /api/settings — partial update, simulate NVS write delay
-    if (req.method === "PUT" && path === "/api/settings") {
-        if (faults.settings) {
-            await new Promise((r) => setTimeout(r, rand(200, 400)));
-            return sendError(res, "NVS write failed: flash error", 500);
-        }
-        const body = await readBody(req);
-        try {
-            const data = JSON.parse(body);
-            await new Promise((r) => setTimeout(r, rand(300, 600)));
-            if (data.tz !== undefined) state.tz = data.tz;
-            if (data.logLevel !== undefined) state.logLevel = data.logLevel;
-            if (data.apFallbackOnDisconnect !== undefined) state.apFallbackOnDisconnect = data.apFallbackOnDisconnect;
-            if (data.syslogEnabled !== undefined) state.syslogEnabled = data.syslogEnabled;
-            if (data.syslogIp !== undefined) state.syslogIp = data.syslogIp;
-            if (data.wifiTxPower !== undefined) state.wifiTxPower = data.wifiTxPower;
-            const pinsChanged =
-                (data.uartTxPin !== undefined && data.uartTxPin !== state.uartTxPin) ||
-                (data.uartRxPin !== undefined && data.uartRxPin !== state.uartRxPin);
-            if (data.uartTxPin !== undefined) state.uartTxPin = data.uartTxPin;
-            if (data.uartRxPin !== undefined) state.uartRxPin = data.uartRxPin;
-            const hostnameChanged = data.hostname !== undefined && data.hostname !== state.hostname;
-            if (data.hostname !== undefined) state.hostname = data.hostname;
-            if (data.navMode !== undefined) state.navMode = data.navMode;
-            if (data.stallThreshold !== undefined) state.stallThreshold = data.stallThreshold;
-            if (data.brushRpm !== undefined) state.brushRpm = data.brushRpm;
-            if (data.vacuumSpeed !== undefined) state.vacuumSpeed = data.vacuumSpeed;
-            if (data.sideBrushPower !== undefined) state.sideBrushPower = data.sideBrushPower;
-            if (data.ntfyTopic !== undefined) state.ntfyTopic = data.ntfyTopic;
-            if (data.ntfyEnabled !== undefined) state.ntfyEnabled = data.ntfyEnabled;
-            if (data.ntfyOnDone !== undefined) state.ntfyOnDone = data.ntfyOnDone;
-            if (data.ntfyOnError !== undefined) state.ntfyOnError = data.ntfyOnError;
-            if (data.ntfyOnAlert !== undefined) state.ntfyOnAlert = data.ntfyOnAlert;
-            if (data.ntfyOnDocking !== undefined) state.ntfyOnDocking = data.ntfyOnDocking;
-            if (data.scheduleEnabled !== undefined) state.scheduleEnabled = data.scheduleEnabled;
-            for (let d = 0; d < 7; d++) {
-                if (data[`sched${d}Hour`] !== undefined) state[`sched${d}Hour`] = data[`sched${d}Hour`];
-                if (data[`sched${d}Min`] !== undefined) state[`sched${d}Min`] = data[`sched${d}Min`];
-                if (data[`sched${d}On`] !== undefined) state[`sched${d}On`] = data[`sched${d}On`];
-                if (data[`sched${d}Slot1Hour`] !== undefined) state[`sched${d}Slot1Hour`] = data[`sched${d}Slot1Hour`];
-                if (data[`sched${d}Slot1Min`] !== undefined) state[`sched${d}Slot1Min`] = data[`sched${d}Slot1Min`];
-                if (data[`sched${d}Slot1On`] !== undefined) state[`sched${d}Slot1On`] = data[`sched${d}Slot1On`];
-            }
-            if (pinsChanged || hostnameChanged) {
-                setTimeout(() => {
-                    bootTime = Date.now();
-                }, 2000);
-            }
-            // Return full settings (reuse GET handler logic)
-            const s = {};
-            const keys = [
-                "tz",
-                "logLevel",
-                "apFallbackOnDisconnect",
-                "syslogEnabled",
-                "syslogIp",
-                "wifiTxPower",
-                "uartTxPin",
-                "uartRxPin",
-                "maxGpioPin",
-                "hostname",
-                "stallThreshold",
-                "brushRpm",
-                "vacuumSpeed",
-                "sideBrushPower",
-                "ntfyTopic",
-                "ntfyEnabled",
-                "ntfyOnDone",
-                "ntfyOnError",
-                "ntfyOnAlert",
-                "ntfyOnDocking",
-                "scheduleEnabled",
-            ];
-            for (const k of keys) s[k] = state[k];
-            for (let d = 0; d < 7; d++) {
-                s[`sched${d}Hour`] = state[`sched${d}Hour`];
-                s[`sched${d}Min`] = state[`sched${d}Min`];
-                s[`sched${d}On`] = state[`sched${d}On`];
-                s[`sched${d}Slot1Hour`] = state[`sched${d}Slot1Hour`];
-                s[`sched${d}Slot1Min`] = state[`sched${d}Slot1Min`];
-                s[`sched${d}Slot1On`] = state[`sched${d}Slot1On`];
-            }
-            return jsonResponse(res, s);
-        } catch {
-            return sendError(res, "invalid JSON", 400);
-        }
-    }
-
-    // Serial endpoint — always available (no log level gate)
-    if (req.method === "POST" && path === "/api/serial") {
-        const cmd = query.cmd;
-        if (!cmd) return sendError(res, "missing cmd", 400);
-        // Simulate serial response with a delay
-        await new Promise((r) => setTimeout(r, rand(50, 150)));
-        const body = `${cmd}\r\nMock response for: ${cmd}\r\n\x1a`;
-        res.writeHead(200, { "Content-Type": "text/plain", "Content-Length": Buffer.byteLength(body) });
-        return res.end(body);
-    }
-
-    // Standard route lookup
-    const key = `${req.method} ${path}`;
-    const handler = routes[key];
-    if (handler) {
-        return handler(req, res, query);
-    }
-
-    // Not an API route — return false so Vite can handle it
-    return false;
+    sendResponse(res, response);
 };
 
-// --- Vite plugin ---
-// Hooks into Vite's dev server middleware so /api/* requests are handled
-// in-process — single port, single `npm run dev`
-
 function mockApiPlugin() {
     return {
         name: "mock-api",
-        // Clear update localStorage when not in upd scenario
         transformIndexHtml(html) {
-            if (SCENARIO.split("|").includes("upd")) return html;
             return html.replace(
                 "</head>",
-                `<script>localStorage.removeItem("update_latest_version");localStorage.removeItem("update_last_check");</script></head>`,
+                `<script>(()=>{const p=new URLSearchParams(location.search);const s=p.get("scenario");if(s)document.cookie="openneato_scenario="+encodeURIComponent(s)+"; Path=/; SameSite=Lax";const active=s||document.cookie.split("; ").find((v)=>v.startsWith("openneato_scenario="))?.split("=").slice(1).join("=");const scenario=active?decodeURIComponent(active):"ok";if(!scenario.split("|").includes("upd")){localStorage.removeItem("update_latest_version");localStorage.removeItem("update_last_check");}})();</script></head>`,
             );
         },
         configureServer(server) {
             viteLogger = server.config.logger;
             server.middlewares.use(async (req, res, next) => {
-                // Only intercept /api/* and /repos/* (GitHub API mock) requests
                 if (!req.url.startsWith("/api") && !req.url.startsWith("/repos")) return next();
 
                 logRequest(req, res);
-
-                // Latency simulation (50-200ms)
-                await new Promise((r) => setTimeout(r, rand(50, 200)));
+                await new Promise((resolve) => setTimeout(resolve, rand(50, 200)));
 
                 const handled = await handleRequest(req, res);
                 if (handled === false) next();
diff --git a/frontend/mock/shared-api.js b/frontend/mock/shared-api.js
new file mode 100644
index 0000000..d2e52e6
--- /dev/null
+++ b/frontend/mock/shared-api.js
@@ -0,0 +1,729 @@
+const textEncoder = new TextEncoder();
+
+const defaultRand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const jsonResponse = (data, status = 200) => ({
+    status,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+});
+
+const textResponse = (body, status = 200, headers = {}) => ({ status, headers, body });
+const okResponse = () => jsonResponse({ ok: true });
+const errorResponse = (message, status = 500) => jsonResponse({ error: message }, status);
+
+const byteLength = (value) => textEncoder.encode(value).length;
+const vBattFromFuel = (fuel) => Number((12.0 + (fuel / 100) * 4.6).toFixed(2));
+
+const mockLogs = [
+    { name: "current.jsonl", size: 8192, compressed: false },
+    { name: "1700000000.jsonl.hs", size: 4096, compressed: true },
+    { name: "boot_2501.jsonl.hs", size: 1851, compressed: true },
+];
+
+const mockLogContent = [
+    '{"t":1700000100,"typ":"boot","d":{"reason":"power_on","heap":195000}}',
+    '{"t":1700000101,"typ":"wifi","d":{"event":"connected","rssi":-52}}',
+    '{"t":1700000102,"typ":"ntp","d":{"event":"sync_ok","epoch":1700000102}}',
+    '{"t":1700000200,"typ":"command","d":{"cmd":"GetCharger","status":"ok","ms":85,"q":0,"bytes":312,"resp":"GetCharger\\r\\nLabel,Value\\r\\nFuelPercent,85\\r\\nBatteryOverTemp,0\\r\\nChargingActive,0\\r\\nChargingEnabled,1\\r\\n"}}',
+    '{"t":1700000202,"typ":"command","d":{"cmd":"GetState","status":"ok","ms":42,"q":0,"bytes":95,"resp":"GetState\\r\\nCurrent UI State is: UIMGR_STATE_IDLE\\nCurrent Robot State is: ST_C_Idle\\n"}}',
+    '{"t":1700000203,"typ":"command","d":{"cmd":"GetState","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
+    '{"t":1700000210,"typ":"request","d":{"method":"GET","path":"/api/charger","status":200,"ms":92}}',
+    '{"t":1700000215,"typ":"command","d":{"cmd":"GetErr","status":"ok","ms":38,"q":0,"bytes":64,"resp":"GetErr\\r\\nError\\r\\n200 -  (UI_ALERT_INVALID)\\r\\nAlert\\r\\n200 -  (UI_ALERT_INVALID)\\r\\n"}}',
+    '{"t":1700000216,"typ":"command","d":{"cmd":"GetErr","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
+    '{"t":1700000220,"typ":"request","d":{"method":"GET","path":"/api/state","status":200,"ms":48}}',
+    '{"t":1700000300,"typ":"command","d":{"cmd":"GetAnalogSensors","status":"ok","ms":120,"q":1,"bytes":480}}',
+    '{"t":1700000305,"typ":"request","d":{"method":"POST","path":"/api/clean?action=house","status":200,"ms":210}}',
+    '{"t":1700000306,"typ":"command","d":{"cmd":"Clean House","status":"ok","ms":95,"q":0,"bytes":28}}',
+    '{"t":1700000400,"typ":"event","d":{"msg":"cleaning_started","mode":"house"}}',
+    '{"t":1700000500,"typ":"command","d":{"cmd":"GetMotors","status":"ok","ms":110,"q":2,"bytes":520}}',
+    '{"t":1700000600,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":450,"q":0,"bytes":8200}}',
+    '{"t":1700000601,"typ":"command","d":{"cmd":"GetCharger","status":"ok","ms":0,"q":0,"bytes":0,"age":401}}',
+    '{"t":1700000615,"typ":"request","d":{"method":"GET","path":"/api/lidar","status":200,"ms":460}}',
+    '{"t":1700000620,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":440,"q":1,"bytes":8140}}',
+    '{"t":1700000621,"typ":"command","d":{"cmd":"GetLDSScan","status":"ok","ms":0,"q":0,"bytes":0,"age":1}}',
+    '{"t":1700000700,"typ":"event","d":{"msg":"cleaning_completed","duration":600}}',
+].join("\n");
+
+const syntheticLidarScan = (rand) => {
+    const points = [];
+    for (let i = 0; i < 360; i++) {
+        const rad = (i * Math.PI) / 180;
+        const base = 1500 + Math.round(Math.sin(rad * 2) * 250) + rand(-40, 40);
+        points.push({ angle: i, dist: Math.max(0, base), intensity: rand(20, 70), error: 0 });
+    }
+    return { rotationSpeed: 5, validPoints: points.length, points };
+};
+
+const deriveStates = (state) => {
+    if (state.manualClean) {
+        state.uiState = "UIMGR_STATE_MANUALCLEANING";
+        state.robotState = "ST_C_ManualCleaning";
+    } else if (state.midCleanRecharge) {
+        state.uiState = "UIMGR_STATE_CLEANINGSUSPENDED";
+        state.robotState = "ST_M1_Charging_Cleaning";
+    } else if (state.docking) {
+        state.uiState = "UIMGR_STATE_DOCKINGRUNNING";
+        state.robotState = "ST_C_Docking";
+    } else if (state.cleaning && !state.paused) {
+        state.uiState = "UIMGR_STATE_HOUSECLEANINGRUNNING";
+        state.robotState = "ST_C_HouseCleaning";
+    } else if (state.cleaning && state.paused) {
+        state.uiState = "UIMGR_STATE_HOUSECLEANINGPAUSED";
+        state.robotState = "ST_C_Standby";
+    } else if (state.spotCleaning && !state.paused) {
+        state.uiState = "UIMGR_STATE_SPOTCLEANINGRUNNING";
+        state.robotState = "ST_C_SpotCleaning";
+    } else if (state.spotCleaning && state.paused) {
+        state.uiState = "UIMGR_STATE_SPOTCLEANINGPAUSED";
+        state.robotState = "ST_C_Standby";
+    } else {
+        state.uiState = "UIMGR_STATE_IDLE";
+        state.robotState = "ST_C_Idle";
+    }
+};
+
+const settingsPayload = (state, includeNavMode = true) => {
+    const settings = {};
+    const keys = [
+        "tz",
+        "logLevel",
+        "apFallbackOnDisconnect",
+        "syslogEnabled",
+        "syslogIp",
+        "wifiTxPower",
+        "uartTxPin",
+        "uartRxPin",
+        "maxGpioPin",
+        "hostname",
+        ...(includeNavMode ? ["navMode"] : []),
+        "stallThreshold",
+        "brushRpm",
+        "vacuumSpeed",
+        "sideBrushPower",
+        "ntfyTopic",
+        "ntfyEnabled",
+        "ntfyOnDone",
+        "ntfyOnError",
+        "ntfyOnAlert",
+        "ntfyOnDocking",
+        "scheduleEnabled",
+    ];
+    for (const key of keys) settings[key] = state[key];
+    for (let day = 0; day < 7; day++) {
+        settings[`sched${day}Hour`] = state[`sched${day}Hour`];
+        settings[`sched${day}Min`] = state[`sched${day}Min`];
+        settings[`sched${day}On`] = state[`sched${day}On`];
+        settings[`sched${day}Slot1Hour`] = state[`sched${day}Slot1Hour`];
+        settings[`sched${day}Slot1Min`] = state[`sched${day}Slot1Min`];
+        settings[`sched${day}Slot1On`] = state[`sched${day}Slot1On`];
+    }
+    return settings;
+};
+
+const injectCorruptedPoses = (lines) => {
+    const corruptions = [
+        '{"x":-0.798,"y":3.459,"t":100:5,"ts":8203.4}',
+        '{"x":-0.785,"y":4.192,"t":100:3,"ts":8208.1}',
+        '{"x":-1.286,"y":4.007,"t":177:5,"ts":8215.6}',
+        '{"x":-1.8"3,"y":2.254,"t":181.0,"ts":8288.6}',
+        '{"x":-1.946,"y":2.0"3,"t":181.9,"ts":8312.8}',
+        '{"x":-4.793,"y":-1.6t2,"t":356.5,"ts":9182.5}',
+        '{"x":-1.740,"y":3.510,"t":1.6,"ts":8242:0}',
+    ];
+    const result = [lines[0]];
+    for (let i = 1; i < lines.length; i++) {
+        result.push(lines[i]);
+        if (!lines[i].includes('"type"') && i % 20 === 0) result.push(corruptions[i % corruptions.length]);
+    }
+    return result;
+};
+
+const listHistory = (historySessions, faults) => {
+    const list = [...historySessions.entries()].map(([name, lines]) => {
+        let session = null;
+        let summary = null;
+        if (lines.length > 0) {
+            try {
+                const first = JSON.parse(lines[0]);
+                if (first.type === "session") session = first;
+            } catch {}
+        }
+        if (lines.length > 1) {
+            try {
+                const last = JSON.parse(lines[lines.length - 1]);
+                if (last.type === "summary") summary = last;
+            } catch {}
+        }
+        const raw = `${lines.join("\n")}\n`;
+        return {
+            name,
+            size: byteLength(raw),
+            compressed: name.endsWith(".hs"),
+            recording: summary === null,
+            session,
+            summary,
+        };
+    });
+
+    if (faults.historyListCorrupt && list.length > 0) {
+        const target = list[Math.min(1, list.length - 1)];
+        const summaryJson = target.summary ? JSON.stringify(target.summary) : '{"type":"summary"}';
+        const corruptedSummary = `{"x":-0.218,"y":0.007,"t":35${summaryJson.slice(1)}`;
+        return textResponse(
+            JSON.stringify(list).replace(JSON.stringify(target.summary ?? null), corruptedSummary),
+            200,
+            {
+                "Content-Type": "application/json",
+            },
+        );
+    }
+
+    return jsonResponse(list);
+};
+
+const parseMultipartJsonlUpload = (bodyBytes) => {
+    const bodyStr = new TextDecoder("latin1").decode(bodyBytes);
+    const nameMatch = bodyStr.match(/filename="([^"]+)"/);
+    if (!nameMatch?.[1].endsWith(".jsonl")) {
+        return { error: "Invalid file: expected a .jsonl session file", status: 400 };
+    }
+    const headerEnd = bodyStr.indexOf("\r\n\r\n");
+    const boundaryEnd = bodyStr.lastIndexOf("\r\n--");
+    if (headerEnd < 0 || boundaryEnd < 0) return { error: "Malformed multipart body", status: 400 };
+
+    const filename = nameMatch[1];
+    const content = new TextDecoder().decode(bodyBytes.slice(headerEnd + 4, boundaryEnd));
+    const lines = content
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) return { error: "Empty session file", status: 400 };
+
+    try {
+        const header = JSON.parse(lines[0]);
+        if (header.type !== "session") return { error: "First line must be a session header", status: 400 };
+        const fileEpoch = filename.replace(".jsonl", "");
+        if (header.time !== undefined && String(header.time) !== fileEpoch) {
+            return { error: "Session timestamp does not match filename", status: 400 };
+        }
+    } catch {
+        return { error: "Invalid JSON in session header", status: 400 };
+    }
+
+    return { filename, lines };
+};
+
+const extractFirmwarePayload = (bodyBytes) => {
+    const bodyStr = new TextDecoder("latin1").decode(bodyBytes);
+    const headerEnd = bodyStr.indexOf("\r\n\r\n");
+    const boundaryEnd = bodyStr.lastIndexOf("\r\n--");
+    const fileStart = headerEnd !== -1 ? headerEnd + 4 : -1;
+    const fileEnd = boundaryEnd > fileStart ? boundaryEnd : bodyBytes.length;
+    if (fileStart === -1) return null;
+    return bodyBytes.slice(fileStart, fileEnd);
+};
+
+function createMockApi(context) {
+    const rand = context.rand ?? defaultRand;
+    const sleep = context.sleep ?? defaultSleep;
+
+    const getState = () => context.state;
+    const getFaults = () => context.faults;
+
+    const handle = async (request) => {
+        const state = getState();
+        const faults = getFaults();
+        const method = request.method;
+        const path = request.path;
+        const query = request.query;
+
+        if (state.offline) return { offline: true };
+
+        if (method === "GET" && path === "/api/version") {
+            return jsonResponse({
+                modelName: "BotVacD7",
+                serialNumber: "OPS01234AA,0000001,D",
+                softwareVersion: "4.5.3-142",
+                ldsVersion: "V2.6.15295",
+                ldsSerial: "KSH-V5F4",
+                mainBoardVersion: "15.0",
+                smartBatteryAuthorization: 1,
+                smartBatteryDataVersion: 512,
+                smartBatteryChemistry: "LION1",
+                smartBatteryDeviceName: "F164A10288",
+                smartBatteryManufacturerName: "Panasonic",
+                smartBatteryMfgDate: "2089-02-18",
+                smartBatterySerialNumber: "34832",
+                smartBatterySoftwareVersion: "2048",
+            });
+        }
+
+        if (method === "GET" && path === "/api/charger") {
+            if (faults.pollCharger) return errorResponse("UART timeout reading charger", 500);
+            const fuel = Math.round(state.fuelPercent);
+            return jsonResponse({
+                fuelPercent: fuel,
+                batteryOverTemp: false,
+                chargingActive: state.chargingActive,
+                chargingEnabled: true,
+                confidOnFuel: fuel > 20,
+                onReservedFuel: fuel < 10,
+                emptyFuel: fuel === 0,
+                batteryFailure: false,
+                extPwrPresent: state.extPwrPresent,
+                vBattV: vBattFromFuel(fuel),
+                vExtV: state.extPwrPresent ? 22.3 : 0.0,
+                chargerMAH: state.chargingActive ? 1200 : 0,
+                dischargeMAH: Math.round(((100 - fuel) / 100) * 2800),
+            });
+        }
+
+        if (method === "GET" && path === "/api/analog") {
+            if (faults.pollCharger) return errorResponse("UART timeout reading battery diagnostics", 500);
+            const fuel = Math.round(state.fuelPercent);
+            const batteryCurrentMA = state.chargingActive
+                ? rand(180, 720)
+                : state.extPwrPresent
+                  ? rand(-20, 20)
+                  : -rand(80, 420);
+            return jsonResponse({
+                batteryVoltageV: vBattFromFuel(fuel),
+                batteryCurrentMA,
+                batteryTemperatureC: Number((24 + (state.chargingActive ? 1.8 : 0) + Math.random()).toFixed(1)),
+                externalVoltageV: state.extPwrPresent ? 18.66 : 0.0,
+            });
+        }
+
+        if (method === "GET" && path === "/api/warranty") {
+            return jsonResponse({
+                cumulativeBatteryCycles: 728,
+                cumulativeCleaningTimeSeconds: 885884,
+                validationCode: "b40b2e9a",
+            });
+        }
+
+        if (method === "POST" && path === "/api/battery/new") return okResponse();
+
+        if (method === "GET" && path === "/api/motors") {
+            const cleaning = state.cleaning || state.spotCleaning;
+            return jsonResponse({
+                brushRPM: cleaning ? rand(1100, 1300) : 0,
+                brushMA: cleaning ? rand(200, 400) : 0,
+                vacuumRPM: cleaning ? rand(2200, 2600) : 0,
+                vacuumMA: cleaning ? rand(400, 700) : 0,
+                leftWheelRPM: cleaning ? rand(60, 120) : 0,
+                leftWheelLoad: cleaning ? rand(10, 40) : 0,
+                leftWheelPositionMM: state.leftWheelPos,
+                leftWheelSpeed: cleaning ? rand(150, 300) : 0,
+                rightWheelRPM: cleaning ? rand(60, 120) : 0,
+                rightWheelLoad: cleaning ? rand(10, 40) : 0,
+                rightWheelPositionMM: state.rightWheelPos,
+                rightWheelSpeed: cleaning ? rand(150, 300) : 0,
+                sideBrushMA: cleaning ? rand(50, 200) : 0,
+                laserRPM: cleaning ? rand(290, 310) : 0,
+            });
+        }
+
+        if (method === "GET" && path === "/api/state") {
+            if (faults.pollState) return errorResponse("UART timeout reading state", 500);
+            deriveStates(state);
+            return jsonResponse({ uiState: state.uiState, robotState: state.robotState });
+        }
+
+        if (method === "GET" && path === "/api/error") {
+            if (faults.pollError) return errorResponse("UART timeout reading error", 500);
+            return jsonResponse({
+                hasError: state.hasError,
+                kind: state.kind,
+                errorCode: state.errorCode,
+                errorMessage: state.errorMessage,
+                displayMessage: state.displayMessage,
+            });
+        }
+
+        if (method === "GET" && path === "/api/lidar") {
+            if (state.lidarUnavailable) return errorResponse("UART timeout reading LDS scan", 500);
+            const scan = context.getLidarScan ? context.getLidarScan() : syntheticLidarScan(rand);
+            if (state.lidarLowQuality || state.lidarSlowRotation) {
+                const degraded = { ...scan };
+                if (state.lidarSlowRotation) degraded.rotationSpeed = 2.8;
+                if (state.lidarLowQuality) {
+                    degraded.points = scan.points.map((point, index) =>
+                        index % 5 === 0 ? point : { ...point, dist: 0, intensity: 0, error: 8035 },
+                    );
+                    degraded.validPoints = degraded.points.filter((point) => point.dist > 0).length;
+                }
+                return jsonResponse(degraded);
+            }
+            return jsonResponse(scan);
+        }
+
+        if (method === "POST" && path === "/api/clean") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            const action = query.action || "house";
+            if (action === "dock") {
+                if (state.cleaning || state.spotCleaning) {
+                    state.docking = true;
+                    state.cleaning = false;
+                    state.spotCleaning = false;
+                    state.paused = false;
+                }
+            } else if (action === "pause") {
+                if ((state.cleaning || state.spotCleaning) && !state.paused) state.paused = true;
+            } else if (action === "stop") {
+                state.cleaning = false;
+                state.spotCleaning = false;
+                state.docking = false;
+                state.paused = false;
+            } else if (action === "spot") {
+                state.spotCleaning = true;
+                state.cleaning = false;
+                state.docking = false;
+                state.paused = false;
+            } else {
+                state.cleaning = true;
+                state.spotCleaning = false;
+                state.docking = false;
+                state.paused = false;
+            }
+            deriveStates(state);
+            return okResponse();
+        }
+
+        if (method === "GET" && path === "/api/manual/status") {
+            return jsonResponse({
+                active: state.manualClean,
+                brush: state.manualBrush,
+                vacuum: state.manualVacuum,
+                sideBrush: state.manualSideBrush,
+                lifted: state.manualLifted,
+                bumperFrontLeft: state.manualBumperFrontLeft,
+                bumperFrontRight: state.manualBumperFrontRight,
+                bumperSideLeft: state.manualBumperSideLeft,
+                bumperSideRight: state.manualBumperSideRight,
+                stallFront: state.manualStallFront,
+                stallRear: state.manualStallRear,
+            });
+        }
+
+        if (method === "POST" && path === "/api/manual/move") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            if (!state.manualClean) return errorResponse("Not in manual mode", 400);
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/manual/motors") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            if (!state.manualClean) return errorResponse("Not in manual mode", 400);
+            state.manualBrush = query.brush === "1";
+            state.manualVacuum = query.vacuum === "1";
+            state.manualSideBrush = query.sideBrush === "1";
+            await sleep(600);
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/power") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            if (query.action === "restart") return okResponse();
+            if (query.action === "shutdown") {
+                context.shutdown?.();
+                return okResponse();
+            }
+            return errorResponse("unknown action", 400);
+        }
+
+        if (method === "POST" && path === "/api/clear-errors") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/sound") return okResponse();
+
+        if (method === "POST" && path === "/api/manual") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            const enable = query.enable === "1";
+            state.manualClean = enable;
+            if (enable) {
+                state.cleaning = false;
+                state.spotCleaning = false;
+                state.paused = false;
+            }
+            state.manualBrush = false;
+            state.manualVacuum = false;
+            state.manualSideBrush = false;
+            if (!enable) {
+                state.manualLifted = false;
+                state.manualBumperFrontLeft = false;
+                state.manualBumperFrontRight = false;
+                state.manualBumperSideLeft = false;
+                state.manualBumperSideRight = false;
+                state.manualStallFront = false;
+                state.manualStallRear = false;
+            }
+            deriveStates(state);
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/lidar/rotate") {
+            if (faults.actions) return errorResponse("UART timeout: robot not responding", 500);
+            return okResponse();
+        }
+
+        if (method === "GET" && path === "/api/logs") {
+            if (faults.logsRead) return errorResponse("SPIFFS read failed", 500);
+            return jsonResponse(mockLogs);
+        }
+
+        if (method === "DELETE" && path === "/api/logs") {
+            if (faults.logsDelete) return errorResponse("SPIFFS busy, try again later", 503);
+            return okResponse();
+        }
+
+        const logFileMatch = path.match(/^\/api\/logs\/(.+)$/);
+        if (logFileMatch) {
+            const filename = decodeURIComponent(logFileMatch[1]);
+            if (method === "GET") {
+                if (faults.logsRead) return errorResponse("SPIFFS read failed", 500);
+                return textResponse(mockLogContent, 200, {
+                    "Content-Type": "application/x-ndjson",
+                    "Content-Disposition": `attachment; filename="${filename.replace(/\.hs$/, "")}"`,
+                });
+            }
+            if (method === "DELETE") {
+                if (faults.logsDelete) return errorResponse("SPIFFS busy, try again later", 503);
+                return okResponse();
+            }
+            return errorResponse("method not allowed", 405);
+        }
+
+        if (method === "GET" && path === "/api/system") {
+            const now = new Date();
+            const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+            const pad = (number) => number.toString().padStart(2, "0");
+            const localTime = `${days[now.getDay()]} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+            return jsonResponse({
+                heap: rand(160000, 200000),
+                heapTotal: 327680,
+                uptime: Date.now() - context.getBootTime(),
+                rssi: rand(-65, -40),
+                fsUsed: rand(10000, 50000),
+                fsTotal: 262144,
+                ntpSynced: true,
+                time: Math.floor(Date.now() / 1000),
+                timeSource: "ntp",
+                tz: state.tz,
+                localTime,
+                isDst: now.getTimezoneOffset() !== new Date(now.getFullYear(), 0, 1).getTimezoneOffset(),
+            });
+        }
+
+        if (method === "POST" && ["/api/system/restart", "/api/system/format-fs", "/api/system/reset"].includes(path)) {
+            context.reboot?.();
+            return okResponse();
+        }
+
+        if (method === "GET" && path === "/api/settings") return jsonResponse(settingsPayload(state));
+
+        if (method === "PUT" && path === "/api/settings") {
+            if (faults.settings) {
+                await sleep(rand(200, 400));
+                return errorResponse("NVS write failed: flash error", 500);
+            }
+            try {
+                const data = JSON.parse(await request.text());
+                await sleep(rand(300, 600));
+                const oldTx = state.uartTxPin;
+                const oldRx = state.uartRxPin;
+                const oldHostname = state.hostname;
+                Object.assign(state, data);
+                if (state.uartTxPin !== oldTx || state.uartRxPin !== oldRx || state.hostname !== oldHostname)
+                    context.reboot?.();
+                return jsonResponse(settingsPayload(state, false));
+            } catch {
+                return errorResponse("invalid JSON", 400);
+            }
+        }
+
+        if (method === "GET" && path === "/api/wifi/status") {
+            const hasCreds = !state.wifiNoCredentials;
+            const apOn = !!state.wifiDisconnected || !hasCreds;
+            return jsonResponse({
+                staConnected: !state.wifiDisconnected && hasCreds,
+                ssid: hasCreds ? "HomeWiFi" : "",
+                ip: state.wifiDisconnected || !hasCreds ? "" : "192.168.1.42",
+                rssi: state.wifiDisconnected || !hasCreds ? 0 : -52,
+                apActive: apOn,
+                apSsid: apOn ? `${state.hostname}-ap` : "",
+                apIp: apOn ? "192.168.4.1" : "",
+                apClients: apOn ? (hasCreds ? 1 : 0) : 0,
+                apFallbackOnDisconnect: state.apFallbackOnDisconnect,
+                lastError: state.wifiDisconnected && hasCreds ? "wrong password or authentication rejected" : "",
+            });
+        }
+
+        if (method === "GET" && path === "/api/wifi/scan") {
+            await sleep(rand(800, 1500));
+            if (faults.wifiScan) return errorResponse("WiFi scan failed: radio busy", 500);
+            if (faults.wifiScanEmpty) return jsonResponse({ networks: [] });
+            return jsonResponse({
+                networks: [
+                    { ssid: "HomeWiFi", rssi: -52, open: false },
+                    { ssid: "Neighbour-5G", rssi: -68, open: false },
+                    { ssid: "GuestNet", rssi: -71, open: true },
+                    { ssid: "FritzBox-2", rssi: -78, open: false },
+                    { ssid: "TP-Link-Guest", rssi: -82, open: true },
+                ],
+            });
+        }
+
+        if (method === "POST" && path === "/api/wifi/connect") {
+            if (!query.ssid) return errorResponse("missing ssid", 400);
+            await sleep(rand(500, 1500));
+            if (faults.wifiConnect) return errorResponse("wrong password or authentication rejected", 500);
+            state.wifiDisconnected = false;
+            state.wifiNoCredentials = false;
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/wifi/disconnect") {
+            state.wifiDisconnected = true;
+            state.wifiNoCredentials = true;
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/notifications/test") {
+            if (!query.topic) return errorResponse("missing topic", 400);
+            return okResponse();
+        }
+
+        if (method === "GET" && path === "/repos/renjfk/OpenNeato/releases/latest")
+            return jsonResponse({ tag_name: "v1.0" });
+
+        if (method === "GET" && path === "/api/user-settings") {
+            return jsonResponse({
+                buttonClick: state.buttonClick,
+                melodies: state.melodies,
+                warnings: state.warnings,
+                ecoMode: state.ecoMode,
+                intenseClean: state.intenseClean,
+                binFullDetect: state.binFullDetect,
+                wallEnable: state.wallEnable,
+                wifi: state.wifi,
+                stealthLed: state.stealthLed,
+                filterChange: state.filterChange,
+                brushChange: state.brushChange,
+                dirtBin: state.dirtBin,
+            });
+        }
+
+        if (method === "POST" && path === "/api/user-settings") {
+            const keyMap = {
+                ButtonClick: "buttonClick",
+                Melodies: "melodies",
+                Warnings: "warnings",
+                EcoMode: "ecoMode",
+                IntenseClean: "intenseClean",
+                BinFullDetect: "binFullDetect",
+                WallEnable: "wallEnable",
+                WiFi: "wifi",
+                StealthLED: "stealthLed",
+                FilterChange: "filterChange",
+                BrushChange: "brushChange",
+                DirtBin: "dirtBin",
+            };
+            const serialKey = query.key;
+            const value = query.value;
+            if (!serialKey || !value) return errorResponse("missing key or value", 400);
+            const stateKey = keyMap[serialKey];
+            if (!stateKey) return errorResponse("unknown key", 400);
+            state[stateKey] = ["filterChange", "brushChange", "dirtBin"].includes(stateKey)
+                ? Number.parseInt(value, 10)
+                : value.toUpperCase() === "ON";
+            return okResponse();
+        }
+
+        if (method === "GET" && path === "/api/firmware/version") {
+            return jsonResponse({
+                name: "OpenNeato",
+                version: state.firmwareVersion ?? context.getVersion(),
+                chip: "ESP32-C3",
+                model: state.identifying ? "" : state.unsupported ? "Botvac Connected" : "Botvac D7",
+                hostname: "neato-kitchen",
+                supported: !state.unsupported && !state.identifying,
+                identifying: state.identifying,
+                repositoryUrl: "https://github.com/renjfk/OpenNeato",
+                license: "MIT",
+            });
+        }
+
+        if (method === "POST" && path === "/api/firmware/update") {
+            const expectedMd5 = query.hash || "";
+            if (!expectedMd5) return errorResponse("MD5 hash required", 400);
+            const bodyBytes = await request.bytes();
+            const fileBytes = extractFirmwarePayload(bodyBytes);
+            if (fileBytes) {
+                const mockChipId = 5;
+                if (fileBytes.length >= 16 && fileBytes[12] !== mockChipId) {
+                    return errorResponse("Firmware chip mismatch: file targets a different ESP32 variant", 400);
+                }
+                if (!context.md5Hex) return errorResponse("MD5 verification unavailable", 500);
+                const actualMd5 = await context.md5Hex(fileBytes);
+                if (actualMd5 !== expectedMd5.toLowerCase())
+                    return errorResponse("MD5 mismatch: firmware integrity check failed", 400);
+            }
+            await sleep(rand(3000, 5000));
+            context.reboot?.();
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/serial") {
+            const cmd = query.cmd;
+            if (!cmd) return errorResponse("missing cmd", 400);
+            await sleep(rand(50, 150));
+            return textResponse(`${cmd}\r\nMock response for: ${cmd}\r\n\x1a`, 200, { "Content-Type": "text/plain" });
+        }
+
+        if (method === "GET" && path === "/api/history") return listHistory(context.historySessions, faults);
+
+        if (method === "DELETE" && path === "/api/history") {
+            context.historySessions.clear();
+            return okResponse();
+        }
+
+        if (method === "POST" && path === "/api/history/import") {
+            const parsed = parseMultipartJsonlUpload(await request.bytes());
+            if (parsed.error) return errorResponse(parsed.error, parsed.status);
+            const storedName = `${parsed.filename}.hs`;
+            if (context.historySessions.has(storedName) || context.historySessions.has(parsed.filename)) {
+                return errorResponse("Session already exists", 409);
+            }
+            context.historySessions.set(storedName, parsed.lines);
+            await sleep(rand(200, 500));
+            return okResponse();
+        }
+
+        const historyMatch = path.match(/^\/api\/history\/(.+)$/);
+        if (historyMatch) {
+            const filename = decodeURIComponent(historyMatch[1]);
+            if (method === "GET") {
+                const lines = context.historySessions.get(filename);
+                if (!lines) return errorResponse("session not found", 404);
+                const served = faults.historyCorrupt ? injectCorruptedPoses(lines) : lines;
+                return textResponse(`${served.join("\n")}\n`, 200, { "Content-Type": "application/x-ndjson" });
+            }
+            if (method === "DELETE") {
+                context.historySessions.delete(filename);
+                return okResponse();
+            }
+            return errorResponse("method not allowed", 405);
+        }
+
+        return false;
+    };
+
+    return { handle };
+}
+
+export { createMockApi };
diff --git a/frontend/mock/shared-state.js b/frontend/mock/shared-state.js
new file mode 100644
index 0000000..79fdb5d
--- /dev/null
+++ b/frontend/mock/shared-state.js
@@ -0,0 +1,251 @@
+const SCENARIOS = {
+    ok: {},
+    off: { offline: true },
+    cls: { cleaning: true },
+    spt: { spotCleaning: true },
+    chg: { fuelPercent: 62, chargingActive: true, extPwrPresent: true },
+    ch2: { fuelPercent: 25, chargingActive: true, extPwrPresent: true },
+    ful: { fuelPercent: 100, chargingActive: false, extPwrPresent: true },
+    mid: { fuelPercent: 45 },
+    low: { fuelPercent: 12 },
+    ded: { fuelPercent: 0 },
+    err: {
+        hasError: true,
+        kind: "error",
+        errorCode: 265,
+        errorMessage:
+            "Error\r\n265 -  (UI_ERROR_BRUSH_STUCK)\r\nAlert\r\n205 -  (UI_ALERT_DUST_BIN_FULL)\r\nUSB state \r\n NOT connected",
+        displayMessage: "Main brush is stuck",
+    },
+    alrt: {
+        hasError: true,
+        kind: "warning",
+        errorCode: 229,
+        errorMessage: "Error\r\n200 -  (UI_ALERT_INVALID)\r\nAlert\r\n229 -  (UI_ALERT_BRUSH_CHANGE)",
+        displayMessage: "Time to replace the brush",
+    },
+    dock: { docking: true, cleaning: false },
+    rchg: {
+        midCleanRecharge: true,
+        fuelPercent: 15,
+        chargingActive: true,
+        extPwrPresent: true,
+    },
+    man: { manualClean: true },
+    mlf: { manualClean: true, manualLifted: true },
+    mbf: { manualClean: true, manualBumperFrontLeft: true },
+    mbs: { manualClean: true, manualBumperSideRight: true },
+    msf: { manualClean: true, manualStallFront: true },
+    msr: { manualClean: true, manualStallRear: true },
+    ident: { identifying: true },
+    unsup: { unsupported: true },
+    upd: { firmwareVersion: "0.9" },
+    llq: { lidarLowQuality: true },
+    lsl: { lidarSlowRotation: true },
+    lno: { lidarUnavailable: true },
+    fa: { faults: { actions: true } },
+    fs: { faults: { settings: true } },
+    flr: { faults: { logsRead: true } },
+    fld: { faults: { logsDelete: true } },
+    fl: { faults: { logsRead: true, logsDelete: true } },
+    fps: { faults: { pollState: true } },
+    fpc: { faults: { pollCharger: true } },
+    fpe: { faults: { pollError: true } },
+    fp: { faults: { pollState: true, pollCharger: true, pollError: true } },
+    fhc: { faults: { historyCorrupt: true } },
+    fhl: { faults: { historyListCorrupt: true } },
+    wap: { wifiDisconnected: true },
+    wnc: { wifiDisconnected: true, wifiNoCredentials: true },
+    wfo: { apFallbackOnDisconnect: false },
+    fws: { faults: { wifiScan: true } },
+    fwn: { faults: { wifiScanEmpty: true } },
+    fwc: { faults: { wifiConnect: true } },
+    fal: {
+        faults: {
+            actions: true,
+            settings: true,
+            logsRead: true,
+            logsDelete: true,
+            pollState: true,
+            pollCharger: true,
+            pollError: true,
+            historyCorrupt: true,
+            historyListCorrupt: true,
+            wifiScan: true,
+            wifiConnect: true,
+        },
+    },
+};
+
+const DEFAULT_STATE = {
+    offline: false,
+    fuelPercent: 85,
+    chargingActive: false,
+    extPwrPresent: false,
+    cleaning: false,
+    spotCleaning: false,
+    docking: false,
+    paused: false,
+    uiState: "UIMGR_STATE_IDLE",
+    robotState: "ST_C_Idle",
+    hasError: false,
+    kind: "",
+    errorCode: 200,
+    errorMessage: "",
+    displayMessage: "",
+    manualClean: false,
+    manualBrush: false,
+    manualVacuum: false,
+    manualSideBrush: false,
+    manualLifted: false,
+    manualBumperFrontLeft: false,
+    manualBumperFrontRight: false,
+    manualBumperSideLeft: false,
+    manualBumperSideRight: false,
+    manualStallFront: false,
+    manualStallRear: false,
+    midCleanRecharge: false,
+    identifying: false,
+    unsupported: false,
+    firmwareVersion: null,
+    lidarLowQuality: false,
+    lidarSlowRotation: false,
+    lidarUnavailable: false,
+    tz: "UTC0",
+    logLevel: 0,
+    apFallbackOnDisconnect: true,
+    wifiDisconnected: false,
+    wifiNoCredentials: false,
+    syslogEnabled: false,
+    syslogIp: "",
+    wifiTxPower: 60,
+    uartTxPin: 3,
+    uartRxPin: 4,
+    maxGpioPin: 21,
+    hostname: "neato",
+    navMode: "Normal",
+    stallThreshold: 60,
+    brushRpm: 1200,
+    vacuumSpeed: 80,
+    sideBrushPower: 1500,
+    ntfyTopic: "",
+    ntfyEnabled: true,
+    ntfyOnDone: true,
+    ntfyOnError: true,
+    ntfyOnAlert: true,
+    ntfyOnDocking: true,
+    buttonClick: true,
+    melodies: true,
+    warnings: true,
+    ecoMode: false,
+    intenseClean: false,
+    binFullDetect: true,
+    wallEnable: true,
+    wifi: true,
+    stealthLed: false,
+    filterChange: 2592000,
+    brushChange: 2592000,
+    dirtBin: 30,
+    scheduleEnabled: true,
+    sched0Hour: 9,
+    sched0Min: 0,
+    sched0On: true,
+    sched1Hour: 9,
+    sched1Min: 0,
+    sched1On: true,
+    sched2Hour: 9,
+    sched2Min: 0,
+    sched2On: true,
+    sched3Hour: 9,
+    sched3Min: 0,
+    sched3On: true,
+    sched4Hour: 9,
+    sched4Min: 0,
+    sched4On: true,
+    sched5Hour: 0,
+    sched5Min: 0,
+    sched5On: false,
+    sched6Hour: 0,
+    sched6Min: 0,
+    sched6On: false,
+    sched0Slot1Hour: 15,
+    sched0Slot1Min: 0,
+    sched0Slot1On: true,
+    sched1Slot1Hour: 15,
+    sched1Slot1Min: 0,
+    sched1Slot1On: true,
+    sched2Slot1Hour: 15,
+    sched2Slot1Min: 0,
+    sched2Slot1On: true,
+    sched3Slot1Hour: 15,
+    sched3Slot1Min: 0,
+    sched3Slot1On: true,
+    sched4Slot1Hour: 15,
+    sched4Slot1Min: 0,
+    sched4Slot1On: true,
+    sched5Slot1Hour: 0,
+    sched5Slot1Min: 0,
+    sched5Slot1On: false,
+    sched6Slot1Hour: 0,
+    sched6Slot1Min: 0,
+    sched6Slot1On: false,
+};
+
+const DEFAULT_FAULTS = {
+    actions: false,
+    settings: false,
+    logsRead: false,
+    logsDelete: false,
+    pollState: false,
+    pollCharger: false,
+    pollError: false,
+    historyCorrupt: false,
+    historyListCorrupt: false,
+    wifiScan: false,
+    wifiScanEmpty: false,
+    wifiConnect: false,
+};
+
+const SCENARIO_COOKIE = "openneato_scenario";
+
+function normalizeScenario(scenario) {
+    return (scenario || "ok").trim() || "ok";
+}
+
+function parseCookies(cookieHeader = "") {
+    const cookies = {};
+    for (const part of cookieHeader.split(";")) {
+        const [rawName, ...rawValue] = part.trim().split("=");
+        if (!rawName) continue;
+        cookies[rawName] = decodeURIComponent(rawValue.join("="));
+    }
+    return cookies;
+}
+
+function scenarioFromRequest(query = {}, cookieHeader = "") {
+    const queryScenario = typeof query.get === "function" ? query.get("scenario") : query.scenario;
+    return normalizeScenario(queryScenario || parseCookies(cookieHeader)[SCENARIO_COOKIE]);
+}
+
+function scenarioCookie(scenario) {
+    return `${SCENARIO_COOKIE}=${encodeURIComponent(normalizeScenario(scenario))}; Path=/; SameSite=Lax`;
+}
+
+function createScenarioState(scenario = "ok") {
+    const merged = {};
+    const mergedFaults = {};
+
+    for (const key of scenario.split("|")) {
+        const s = SCENARIOS[key] || {};
+        const { faults, ...rest } = s;
+        Object.assign(merged, rest);
+        if (faults) Object.assign(mergedFaults, faults);
+    }
+
+    return {
+        state: { ...DEFAULT_STATE, ...merged },
+        faults: { ...DEFAULT_FAULTS, ...mergedFaults },
+    };
+}
+
+export { createScenarioState, SCENARIOS, scenarioCookie, scenarioFromRequest };
diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
new file mode 100644
index 0000000..02ce878
--- /dev/null
+++ b/frontend/mock/worker.js
@@ -0,0 +1,174 @@
+import { createMockApi } from "./shared-api.js";
+import { createScenarioState, scenarioCookie, scenarioFromRequest } from "./shared-state.js";
+
+const UMAMI_ENDPOINT = "https://cloud.umami.is/api/send";
+const WEBSITE_ID = "417b882b-03c5-45d2-b070-9d7b8b7855d4";
+
+const randomInt = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const json = (data, status = 200) =>
+    new Response(JSON.stringify(data), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+
+const err = (message, status = 500) => json({ error: message }, status);
+
+async function handleCollect(request) {
+    try {
+        const form = await request.formData();
+        const hostname = new URL(request.url).hostname;
+
+        const response = await fetch(UMAMI_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": request.headers.get("User-Agent") || "Mozilla/5.0",
+            },
+            body: JSON.stringify({
+                type: "event",
+                payload: {
+                    website: WEBSITE_ID,
+                    hostname,
+                    ip: request.headers.get("CF-Connecting-IP") || undefined,
+                    screen: form.get("s") || "",
+                    language: form.get("l") || "",
+                    title: form.get("t") || "",
+                    url: form.get("u") || "",
+                    referrer: form.get("r") || "",
+                },
+            }),
+        });
+
+        return new Response(null, { status: response.ok ? 204 : 502 });
+    } catch (error) {
+        console.error("[Analytics]", error);
+        return new Response(null, { status: 502 });
+    }
+}
+
+const createDefaultHistory = () => {
+    const now = Math.floor(Date.now() / 1000);
+    const house = `${now - 7200}`;
+    const spot = `${now - 3600}`;
+
+    return new Map([
+        [
+            `${house}.jsonl.hs`,
+            [
+                `{"type":"session","time":${house},"mode":"house","battery":95}`,
+                '{"x":0.0,"y":0.0,"t":0.0,"ts":0.0}',
+                '{"x":0.5,"y":0.2,"t":15.0,"ts":4.0}',
+                '{"x":1.2,"y":0.8,"t":45.0,"ts":10.0}',
+                '{"type":"summary","duration":1800,"distanceTraveled":34.5,"areaCovered":26.2,"batteryEnd":62}',
+            ],
+        ],
+        [
+            `${spot}.jsonl.hs`,
+            [
+                `{"type":"session","time":${spot},"mode":"spot","battery":80}`,
+                '{"x":0.0,"y":0.0,"t":0.0,"ts":0.0}',
+                '{"x":0.3,"y":0.3,"t":45.0,"ts":2.0}',
+                '{"type":"summary","duration":420,"distanceTraveled":8.4,"areaCovered":4.1,"batteryEnd":71}',
+            ],
+        ],
+    ]);
+};
+
+let initializedScenario = null;
+let bootTime = Date.now();
+
+const context = {
+    state: {},
+    faults: {},
+    historySessions: new Map(),
+    rand: randomInt,
+    sleep,
+    getVersion: () => "0.0",
+    getBootTime: () => bootTime,
+    reboot: () => {
+        bootTime = Date.now();
+    },
+};
+
+const api = createMockApi(context);
+
+function initScenario(rawScenario) {
+    const scenario = rawScenario.trim() || "ok";
+    const scenarioState = createScenarioState(scenario);
+    context.state = scenarioState.state;
+    context.faults = scenarioState.faults;
+    context.historySessions = createDefaultHistory();
+    bootTime = Date.now();
+    initializedScenario = scenario;
+}
+
+const toWorkerResponse = (response) => {
+    if (response === false) return err("not found", 404);
+    if (response.offline) return err("Device unreachable", 503);
+    return new Response(response.body ?? "", {
+        status: response.status,
+        headers: response.headers,
+    });
+};
+
+async function handleApi(request, env) {
+    const url = new URL(request.url);
+    const scenario = scenarioFromRequest(url.searchParams, request.headers.get("Cookie") ?? "");
+    if (scenario !== initializedScenario) initScenario(scenario);
+
+    await sleep(randomInt(50, 200));
+
+    const demoMode = (env.DEMO_MODE ?? "true").toLowerCase() === "true";
+
+    if (demoMode && request.method === "POST" && url.pathname === "/api/firmware/update") {
+        return err("Firmware upload is disabled in demo mode", 403);
+    }
+    if (demoMode && request.method === "POST" && url.pathname === "/api/history/import") {
+        return err("Session import is disabled in demo mode", 403);
+    }
+
+    let cachedBytes = null;
+    const bytes = async () => {
+        cachedBytes ??= new Uint8Array(await request.arrayBuffer());
+        return cachedBytes;
+    };
+
+    const response = toWorkerResponse(
+        await api.handle({
+            method: request.method,
+            path: url.pathname,
+            query: Object.fromEntries(url.searchParams),
+            bytes,
+            text: async () => new TextDecoder().decode(await bytes()),
+        }),
+    );
+    if (url.searchParams.has("scenario")) response.headers.set("Set-Cookie", scenarioCookie(scenario));
+    return response;
+}
+
+async function serveAsset(request, env) {
+    const url = new URL(request.url);
+    const scenario = url.searchParams.get("scenario");
+    const rawAssetResponse = await env.ASSETS.fetch(request);
+    const assetResponse = new Response(rawAssetResponse.body, rawAssetResponse);
+    if (scenario) assetResponse.headers.set("Set-Cookie", scenarioCookie(scenario));
+    if (assetResponse.status !== 404) return assetResponse;
+
+    const indexRequest = new Request(new URL("/index.html", url).toString(), request);
+    const rawIndexResponse = await env.ASSETS.fetch(indexRequest);
+    const indexResponse = new Response(rawIndexResponse.body, rawIndexResponse);
+    if (scenario) indexResponse.headers.set("Set-Cookie", scenarioCookie(scenario));
+    if (indexResponse.status !== 404) return indexResponse;
+    return assetResponse;
+}
+
+export default {
+    async fetch(request, env) {
+        const url = new URL(request.url);
+        if (request.method === "POST" && url.pathname === "/api/collect") return handleCollect(request);
+        if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/repos/")) return handleApi(request, env);
+        return serveAsset(request, env);
+    },
+};
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 6c90e34..150451a 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -16,6 +16,7 @@
                 "openapi-typescript": "7.13.0",
                 "typescript": "6.0.3",
                 "vite": "8.0.13",
+                "wrangler": "4.92.0",
                 "yaml": "2.9.0"
             }
         },
@@ -509,38 +510,1153 @@
                 "node": ">=14.21.3"
             }
         },
+        "node_modules/@cloudflare/kv-asset-handler": {
+            "version": "0.5.0",
+            "resolved": "https://registry.npmjs.org/@cloudflare/kv-asset-handler/-/kv-asset-handler-0.5.0.tgz",
+            "integrity": "sha512-jxQYkj8dSIzc0cD6cMMNdOc1UVjqSqu8BZdor5s8cGjW2I8BjODt/kWPVdY+u9zj3ms75Q5qaZgnxUad83+eAg==",
+            "dev": true,
+            "license": "MIT OR Apache-2.0",
+            "engines": {
+                "node": ">=22.0.0"
+            }
+        },
+        "node_modules/@cloudflare/unenv-preset": {
+            "version": "2.16.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.16.1.tgz",
+            "integrity": "sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw==",
+            "dev": true,
+            "license": "MIT OR Apache-2.0",
+            "peerDependencies": {
+                "unenv": "2.0.0-rc.24",
+                "workerd": ">1.20260305.0 <2.0.0-0"
+            },
+            "peerDependenciesMeta": {
+                "workerd": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/@cloudflare/workerd-darwin-64": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260515.1.tgz",
+            "integrity": "sha512-Wtw44el2pNbzixvTkWdfeBDTrQwQbJRz7/JUvPKV27I0pQWXbhNJPpM8cstq/pbrU5AGcA/HjFH6yPMRTIRKig==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=16"
+            }
+        },
+        "node_modules/@cloudflare/workerd-darwin-arm64": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260515.1.tgz",
+            "integrity": "sha512-X8EqkZej6FfmhF9AVAQ3FhyQRr9acS4RcDunMU2YiuxKHF1IU8zzH3vY30/POaG+rUu9vGDp/VgUl49VPenHJQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=16"
+            }
+        },
+        "node_modules/@cloudflare/workerd-linux-64": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260515.1.tgz",
+            "integrity": "sha512-CDC89QxQ7Y7t7RG1Jd9vj/qolE1sQRkI2OSEuV5BMJi0vW/gV4OVG6xjpdK3b1OYnSWDzF7NpvlR5Yg86q7k4g==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16"
+            }
+        },
+        "node_modules/@cloudflare/workerd-linux-arm64": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260515.1.tgz",
+            "integrity": "sha512-WxbW/PToYES4fvHXzsr/5qOiETQs/Z9iZ0mjSZAiEwq5cMLZemzGN0COx+uFb9OvQwzh6Pg159qPFnw3+i9FuA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16"
+            }
+        },
+        "node_modules/@cloudflare/workerd-windows-64": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260515.1.tgz",
+            "integrity": "sha512-WmV/iv+MHjYsvkcMVzpM2B5/mf06UUkdpVhZrtMfV9graWjBGPYFvE/eab8748RPVGKh1Xe1vXofLzDSwc08lA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=16"
+            }
+        },
+        "node_modules/@cspotcode/source-map-support": {
+            "version": "0.8.1",
+            "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
+            "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jridgewell/trace-mapping": "0.3.9"
+            },
+            "engines": {
+                "node": ">=12"
+            }
+        },
+        "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": {
+            "version": "0.3.9",
+            "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
+            "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jridgewell/resolve-uri": "^3.0.3",
+                "@jridgewell/sourcemap-codec": "^1.4.10"
+            }
+        },
         "node_modules/@emnapi/core": {
             "version": "1.10.0",
             "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
             "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
             "dev": true,
-            "license": "MIT",
+            "license": "MIT",
+            "optional": true,
+            "dependencies": {
+                "@emnapi/wasi-threads": "1.2.1",
+                "tslib": "^2.4.0"
+            }
+        },
+        "node_modules/@emnapi/runtime": {
+            "version": "1.10.0",
+            "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+            "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "dependencies": {
+                "tslib": "^2.4.0"
+            }
+        },
+        "node_modules/@emnapi/wasi-threads": {
+            "version": "1.2.1",
+            "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+            "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "dependencies": {
+                "tslib": "^2.4.0"
+            }
+        },
+        "node_modules/@esbuild/aix-ppc64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",
+            "integrity": "sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "aix"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/android-arm": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.3.tgz",
+            "integrity": "sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/android-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.3.tgz",
+            "integrity": "sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/android-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.3.tgz",
+            "integrity": "sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/darwin-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.3.tgz",
+            "integrity": "sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/darwin-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.3.tgz",
+            "integrity": "sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/freebsd-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.3.tgz",
+            "integrity": "sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/freebsd-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.3.tgz",
+            "integrity": "sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-arm": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.3.tgz",
+            "integrity": "sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.3.tgz",
+            "integrity": "sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-ia32": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.3.tgz",
+            "integrity": "sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==",
+            "cpu": [
+                "ia32"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-loong64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.3.tgz",
+            "integrity": "sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==",
+            "cpu": [
+                "loong64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-mips64el": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.3.tgz",
+            "integrity": "sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==",
+            "cpu": [
+                "mips64el"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-ppc64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.3.tgz",
+            "integrity": "sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-riscv64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.3.tgz",
+            "integrity": "sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==",
+            "cpu": [
+                "riscv64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-s390x": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.3.tgz",
+            "integrity": "sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==",
+            "cpu": [
+                "s390x"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/linux-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.3.tgz",
+            "integrity": "sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/netbsd-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.3.tgz",
+            "integrity": "sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "netbsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/netbsd-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.3.tgz",
+            "integrity": "sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "netbsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/openbsd-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.3.tgz",
+            "integrity": "sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "openbsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/openbsd-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.3.tgz",
+            "integrity": "sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "openbsd"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/openharmony-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.3.tgz",
+            "integrity": "sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "openharmony"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/sunos-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.3.tgz",
+            "integrity": "sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "sunos"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/win32-arm64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.3.tgz",
+            "integrity": "sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/win32-ia32": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.3.tgz",
+            "integrity": "sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==",
+            "cpu": [
+                "ia32"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@esbuild/win32-x64": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.3.tgz",
+            "integrity": "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@img/colour": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
+            "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/@img/sharp-darwin-arm64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
+            "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-darwin-arm64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-darwin-x64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+            "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-darwin-x64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-libvips-darwin-arm64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
+            "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-darwin-x64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+            "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-arm": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+            "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-arm64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+            "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-ppc64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+            "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-riscv64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+            "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+            "cpu": [
+                "riscv64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-s390x": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+            "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+            "cpu": [
+                "s390x"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linux-x64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+            "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+            "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+            "version": "1.2.4",
+            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+            "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-linux-arm": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+            "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-arm": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linux-arm64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+            "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-arm64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linux-ppc64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+            "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-ppc64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linux-riscv64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+            "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+            "cpu": [
+                "riscv64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-riscv64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linux-s390x": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+            "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+            "cpu": [
+                "s390x"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-s390x": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linux-x64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+            "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linux-x64": "1.2.4"
+            }
+        },
+        "node_modules/@img/sharp-linuxmusl-arm64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+            "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "Apache-2.0",
             "optional": true,
-            "dependencies": {
-                "@emnapi/wasi-threads": "1.2.1",
-                "tslib": "^2.4.0"
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
             }
         },
-        "node_modules/@emnapi/runtime": {
-            "version": "1.10.0",
-            "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
-            "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+        "node_modules/@img/sharp-linuxmusl-x64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+            "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+            "cpu": [
+                "x64"
+            ],
             "dev": true,
-            "license": "MIT",
+            "libc": [
+                "musl"
+            ],
+            "license": "Apache-2.0",
             "optional": true,
-            "dependencies": {
-                "tslib": "^2.4.0"
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
             }
         },
-        "node_modules/@emnapi/wasi-threads": {
-            "version": "1.2.1",
-            "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
-            "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+        "node_modules/@img/sharp-wasm32": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+            "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+            "cpu": [
+                "wasm32"
+            ],
             "dev": true,
-            "license": "MIT",
+            "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
             "optional": true,
             "dependencies": {
-                "tslib": "^2.4.0"
+                "@emnapi/runtime": "^1.7.0"
+            },
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-win32-arm64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+            "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0 AND LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-win32-ia32": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+            "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
+            "cpu": [
+                "ia32"
+            ],
+            "dev": true,
+            "license": "Apache-2.0 AND LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            }
+        },
+        "node_modules/@img/sharp-win32-x64": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+            "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0 AND LGPL-3.0-or-later",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
             }
         },
         "node_modules/@jridgewell/gen-mapping": {
@@ -622,6 +1738,35 @@
                 "url": "https://github.com/sponsors/Boshen"
             }
         },
+        "node_modules/@poppinss/colors": {
+            "version": "4.1.6",
+            "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz",
+            "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "kleur": "^4.1.5"
+            }
+        },
+        "node_modules/@poppinss/dumper": {
+            "version": "0.6.5",
+            "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz",
+            "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@poppinss/colors": "^4.1.5",
+                "@sindresorhus/is": "^7.0.2",
+                "supports-color": "^10.0.0"
+            }
+        },
+        "node_modules/@poppinss/exception": {
+            "version": "1.2.3",
+            "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz",
+            "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/@preact/preset-vite": {
             "version": "2.10.5",
             "resolved": "https://registry.npmjs.org/@preact/preset-vite/-/preset-vite-2.10.5.tgz",
@@ -1065,6 +2210,26 @@
                 }
             }
         },
+        "node_modules/@sindresorhus/is": {
+            "version": "7.2.0",
+            "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz",
+            "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "url": "https://github.com/sindresorhus/is?sponsor=1"
+            }
+        },
+        "node_modules/@speed-highlight/core": {
+            "version": "1.2.15",
+            "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.15.tgz",
+            "integrity": "sha512-BMq1K3DsElxDWawkX6eLg9+CKJrTVGCBAWVuHXVUV2u0s2711qiChLSId6ikYPfxhdYocLNt3wWwSvDiTvFabw==",
+            "dev": true,
+            "license": "CC0-1.0"
+        },
         "node_modules/@tybys/wasm-util": {
             "version": "0.10.2",
             "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
@@ -1140,6 +2305,13 @@
                 "node": ">=6.0.0"
             }
         },
+        "node_modules/blake3-wasm": {
+            "version": "2.1.5",
+            "resolved": "https://registry.npmjs.org/blake3-wasm/-/blake3-wasm-2.1.5.tgz",
+            "integrity": "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/boolbase": {
             "version": "1.0.0",
             "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
@@ -1233,6 +2405,20 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/cookie": {
+            "version": "1.1.1",
+            "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+            "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/express"
+            }
+        },
         "node_modules/css-select": {
             "version": "5.2.2",
             "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz",
@@ -1370,6 +2556,58 @@
                 "url": "https://github.com/fb55/entities?sponsor=1"
             }
         },
+        "node_modules/error-stack-parser-es": {
+            "version": "1.0.5",
+            "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz",
+            "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://github.com/sponsors/antfu"
+            }
+        },
+        "node_modules/esbuild": {
+            "version": "0.27.3",
+            "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
+            "integrity": "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==",
+            "dev": true,
+            "hasInstallScript": true,
+            "license": "MIT",
+            "bin": {
+                "esbuild": "bin/esbuild"
+            },
+            "engines": {
+                "node": ">=18"
+            },
+            "optionalDependencies": {
+                "@esbuild/aix-ppc64": "0.27.3",
+                "@esbuild/android-arm": "0.27.3",
+                "@esbuild/android-arm64": "0.27.3",
+                "@esbuild/android-x64": "0.27.3",
+                "@esbuild/darwin-arm64": "0.27.3",
+                "@esbuild/darwin-x64": "0.27.3",
+                "@esbuild/freebsd-arm64": "0.27.3",
+                "@esbuild/freebsd-x64": "0.27.3",
+                "@esbuild/linux-arm": "0.27.3",
+                "@esbuild/linux-arm64": "0.27.3",
+                "@esbuild/linux-ia32": "0.27.3",
+                "@esbuild/linux-loong64": "0.27.3",
+                "@esbuild/linux-mips64el": "0.27.3",
+                "@esbuild/linux-ppc64": "0.27.3",
+                "@esbuild/linux-riscv64": "0.27.3",
+                "@esbuild/linux-s390x": "0.27.3",
+                "@esbuild/linux-x64": "0.27.3",
+                "@esbuild/netbsd-arm64": "0.27.3",
+                "@esbuild/netbsd-x64": "0.27.3",
+                "@esbuild/openbsd-arm64": "0.27.3",
+                "@esbuild/openbsd-x64": "0.27.3",
+                "@esbuild/openharmony-arm64": "0.27.3",
+                "@esbuild/sunos-x64": "0.27.3",
+                "@esbuild/win32-arm64": "0.27.3",
+                "@esbuild/win32-ia32": "0.27.3",
+                "@esbuild/win32-x64": "0.27.3"
+            }
+        },
         "node_modules/escalade": {
             "version": "3.2.0",
             "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -1537,6 +2775,16 @@
                 "node": ">=6"
             }
         },
+        "node_modules/kleur": {
+            "version": "4.1.5",
+            "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
+            "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
         "node_modules/kolorist": {
             "version": "1.8.0",
             "resolved": "https://registry.npmjs.org/kolorist/-/kolorist-1.8.0.tgz",
@@ -1837,6 +3085,27 @@
                 "@jridgewell/sourcemap-codec": "^1.5.5"
             }
         },
+        "node_modules/miniflare": {
+            "version": "4.20260515.0",
+            "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260515.0.tgz",
+            "integrity": "sha512-2j0oQWizk1Eu4Cm8tDX7Z+Nsjd0nebIj1TQcQ+Oy1QKeo0Ay9+bdn8wfLAtOj9znDCybDCUlnS1+nYvKXEdfNg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@cspotcode/source-map-support": "0.8.1",
+                "sharp": "^0.34.5",
+                "undici": "7.24.8",
+                "workerd": "1.20260515.1",
+                "ws": "8.18.0",
+                "youch": "4.1.0-beta.10"
+            },
+            "bin": {
+                "miniflare": "bootstrap.js"
+            },
+            "engines": {
+                "node": ">=22.0.0"
+            }
+        },
         "node_modules/minimatch": {
             "version": "5.1.9",
             "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.9.tgz",
@@ -1946,6 +3215,20 @@
                 "url": "https://github.com/sponsors/sindresorhus"
             }
         },
+        "node_modules/path-to-regexp": {
+            "version": "6.3.0",
+            "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz",
+            "integrity": "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/pathe": {
+            "version": "2.0.3",
+            "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+            "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/picocolors": {
             "version": "1.1.1",
             "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -2069,6 +3352,64 @@
                 "semver": "bin/semver.js"
             }
         },
+        "node_modules/sharp": {
+            "version": "0.34.5",
+            "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
+            "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+            "dev": true,
+            "hasInstallScript": true,
+            "license": "Apache-2.0",
+            "dependencies": {
+                "@img/colour": "^1.0.0",
+                "detect-libc": "^2.1.2",
+                "semver": "^7.7.3"
+            },
+            "engines": {
+                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/libvips"
+            },
+            "optionalDependencies": {
+                "@img/sharp-darwin-arm64": "0.34.5",
+                "@img/sharp-darwin-x64": "0.34.5",
+                "@img/sharp-libvips-darwin-arm64": "1.2.4",
+                "@img/sharp-libvips-darwin-x64": "1.2.4",
+                "@img/sharp-libvips-linux-arm": "1.2.4",
+                "@img/sharp-libvips-linux-arm64": "1.2.4",
+                "@img/sharp-libvips-linux-ppc64": "1.2.4",
+                "@img/sharp-libvips-linux-riscv64": "1.2.4",
+                "@img/sharp-libvips-linux-s390x": "1.2.4",
+                "@img/sharp-libvips-linux-x64": "1.2.4",
+                "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
+                "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
+                "@img/sharp-linux-arm": "0.34.5",
+                "@img/sharp-linux-arm64": "0.34.5",
+                "@img/sharp-linux-ppc64": "0.34.5",
+                "@img/sharp-linux-riscv64": "0.34.5",
+                "@img/sharp-linux-s390x": "0.34.5",
+                "@img/sharp-linux-x64": "0.34.5",
+                "@img/sharp-linuxmusl-arm64": "0.34.5",
+                "@img/sharp-linuxmusl-x64": "0.34.5",
+                "@img/sharp-wasm32": "0.34.5",
+                "@img/sharp-win32-arm64": "0.34.5",
+                "@img/sharp-win32-ia32": "0.34.5",
+                "@img/sharp-win32-x64": "0.34.5"
+            }
+        },
+        "node_modules/sharp/node_modules/semver": {
+            "version": "7.8.0",
+            "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+            "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
+            "dev": true,
+            "license": "ISC",
+            "bin": {
+                "semver": "bin/semver.js"
+            },
+            "engines": {
+                "node": ">=10"
+            }
+        },
         "node_modules/simple-code-frame": {
             "version": "1.3.0",
             "resolved": "https://registry.npmjs.org/simple-code-frame/-/simple-code-frame-1.3.0.tgz",
@@ -2174,6 +3515,26 @@
                 "node": ">=14.17"
             }
         },
+        "node_modules/undici": {
+            "version": "7.24.8",
+            "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.8.tgz",
+            "integrity": "sha512-6KQ/+QxK49Z/p3HO6E5ZCZWNnCasyZLa5ExaVYyvPxUwKtbCPMKELJOqh7EqOle0t9cH/7d2TaaTRRa6Nhs4YQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=20.18.1"
+            }
+        },
+        "node_modules/unenv": {
+            "version": "2.0.0-rc.24",
+            "resolved": "https://registry.npmjs.org/unenv/-/unenv-2.0.0-rc.24.tgz",
+            "integrity": "sha512-i7qRCmY42zmCwnYlh9H2SvLEypEFGye5iRmEMKjcGi7zk9UquigRjFtTLz0TYqr0ZGLZhaMHl/foy1bZR+Cwlw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pathe": "^2.0.3"
+            }
+        },
         "node_modules/update-browserslist-db": {
             "version": "1.2.3",
             "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -2308,6 +3669,84 @@
                 "vite": "5.x || 6.x || 7.x || 8.x"
             }
         },
+        "node_modules/workerd": {
+            "version": "1.20260515.1",
+            "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260515.1.tgz",
+            "integrity": "sha512-MjKOJLcvU45xXedQowvuiHtJTxu4WTHYQeIlF7YmjuqhiI6dImTFxWCEoRQHiskztxuVSNEmdO7/0UfDu6OMnQ==",
+            "dev": true,
+            "hasInstallScript": true,
+            "license": "Apache-2.0",
+            "bin": {
+                "workerd": "bin/workerd"
+            },
+            "engines": {
+                "node": ">=16"
+            },
+            "optionalDependencies": {
+                "@cloudflare/workerd-darwin-64": "1.20260515.1",
+                "@cloudflare/workerd-darwin-arm64": "1.20260515.1",
+                "@cloudflare/workerd-linux-64": "1.20260515.1",
+                "@cloudflare/workerd-linux-arm64": "1.20260515.1",
+                "@cloudflare/workerd-windows-64": "1.20260515.1"
+            }
+        },
+        "node_modules/wrangler": {
+            "version": "4.92.0",
+            "resolved": "https://registry.npmjs.org/wrangler/-/wrangler-4.92.0.tgz",
+            "integrity": "sha512-/DKpQHPxkuZbQsO9dFW2700VTD/4DSZMHjy92fO/frNoDRi/zQsFCAd2ONCV6TGqcUoXcP3D8Bo2gj/L4M0qQQ==",
+            "dev": true,
+            "license": "MIT OR Apache-2.0",
+            "dependencies": {
+                "@cloudflare/kv-asset-handler": "0.5.0",
+                "@cloudflare/unenv-preset": "2.16.1",
+                "blake3-wasm": "2.1.5",
+                "esbuild": "0.27.3",
+                "miniflare": "4.20260515.0",
+                "path-to-regexp": "6.3.0",
+                "unenv": "2.0.0-rc.24",
+                "workerd": "1.20260515.1"
+            },
+            "bin": {
+                "wrangler": "bin/wrangler.js",
+                "wrangler2": "bin/wrangler.js"
+            },
+            "engines": {
+                "node": ">=22.0.0"
+            },
+            "optionalDependencies": {
+                "fsevents": "~2.3.2"
+            },
+            "peerDependencies": {
+                "@cloudflare/workers-types": "^4.20260515.1"
+            },
+            "peerDependenciesMeta": {
+                "@cloudflare/workers-types": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/ws": {
+            "version": "8.18.0",
+            "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.0.tgz",
+            "integrity": "sha512-8VbfWfHLbbwu3+N6OKsOMpBdT4kXPDDB9cJk2bJ6mh9ucxdlnNvH1e+roYkKmN9Nxw2yjz7VzeO9oOz2zJ04Pw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=10.0.0"
+            },
+            "peerDependencies": {
+                "bufferutil": "^4.0.1",
+                "utf-8-validate": ">=5.0.2"
+            },
+            "peerDependenciesMeta": {
+                "bufferutil": {
+                    "optional": true
+                },
+                "utf-8-validate": {
+                    "optional": true
+                }
+            }
+        },
         "node_modules/yallist": {
             "version": "3.1.1",
             "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
@@ -2348,6 +3787,31 @@
                 "node": ">=12"
             }
         },
+        "node_modules/youch": {
+            "version": "4.1.0-beta.10",
+            "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz",
+            "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@poppinss/colors": "^4.1.5",
+                "@poppinss/dumper": "^0.6.4",
+                "@speed-highlight/core": "^1.2.7",
+                "cookie": "^1.0.2",
+                "youch-core": "^0.3.3"
+            }
+        },
+        "node_modules/youch-core": {
+            "version": "0.3.3",
+            "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz",
+            "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@poppinss/exception": "^1.2.2",
+                "error-stack-parser-es": "^1.0.5"
+            }
+        },
         "node_modules/zimmerframe": {
             "version": "1.1.4",
             "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index d931af4..ee38955 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,6 +6,7 @@
     "scripts": {
         "dev": "npm run gen:types && vite",
         "gen:types": "openapi-typescript --root-types --root-types-no-schema-prefix --output src/types.generated.ts api/openapi.yaml",
+        "build:demo": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build --mode demo",
         "build": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build && node scripts/embed_frontend.js",
         "preview": "vite preview",
         "check": "biome check",
@@ -21,6 +22,7 @@
         "openapi-typescript": "7.13.0",
         "typescript": "6.0.3",
         "vite": "8.0.13",
+        "wrangler": "4.92.0",
         "yaml": "2.9.0"
     }
 }
diff --git a/frontend/src/analytics.ts b/frontend/src/analytics.ts
new file mode 100644
index 0000000..d458a65
--- /dev/null
+++ b/frontend/src/analytics.ts
@@ -0,0 +1,39 @@
+function currentUrl(): string {
+    return `${location.pathname}${location.search}${location.hash}`;
+}
+
+function send(url: string, referrer?: string): void {
+    const payload = new URLSearchParams();
+    payload.set("s", `${screen.width}x${screen.height}`);
+    payload.set("l", navigator.language);
+    payload.set("t", document.title);
+    payload.set("u", url);
+    payload.set("r", referrer || document.referrer);
+
+    if (navigator.sendBeacon) {
+        navigator.sendBeacon("/api/collect", payload);
+    } else {
+        void fetch("/api/collect", { method: "POST", body: payload, keepalive: true });
+    }
+}
+
+export function startAnalytics(): void {
+    let previous = currentUrl();
+    send(previous);
+
+    const track = () => {
+        const next = currentUrl();
+        if (next === previous) return;
+        send(next, previous);
+        previous = next;
+    };
+
+    const pushState = history.pushState.bind(history);
+    history.pushState = (...args) => {
+        pushState(...args);
+        track();
+    };
+
+    window.addEventListener("hashchange", track);
+    window.addEventListener("popstate", track);
+}
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index fdf1a12..a73a41e 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -2,5 +2,11 @@ import { render } from "preact";
 import { App } from "./app";
 import "./style.css";
 
+declare const __DEMO_BUILD__: boolean;
+
+if (__DEMO_BUILD__) {
+    void import("./analytics").then(({ startAnalytics }) => startAnalytics());
+}
+
 const root = document.getElementById("app");
 if (root) render(<App />, root);
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 3cef2f6..97cbae1 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,14 +1,18 @@
 import preact from "@preact/preset-vite";
 import { defineConfig } from "vite";
 
-export default defineConfig(async ({ command }) => {
+export default defineConfig(async ({ command, mode }) => {
     const isDev = command === "serve";
+    const isDemo = mode === "demo";
     const serverHost = "0.0.0.0";
     const serverPort = 5173;
     const mockApiPlugin = isDev ? (await import("./mock/server.js")).mockApiPlugin : null;
     return {
         plugins: [preact(), ...(mockApiPlugin ? [mockApiPlugin()] : [])],
-        define: isDev ? { __GITHUB_API_BASE__: JSON.stringify(`http://${serverHost}:${serverPort}`) } : {},
+        define: {
+            __DEMO_BUILD__: JSON.stringify(isDemo),
+            ...(isDev ? { __GITHUB_API_BASE__: JSON.stringify(`http://${serverHost}:${serverPort}`) } : {}),
+        },
         server: {
             host: serverHost,
             port: serverPort,
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
new file mode 100644
index 0000000..0e12537
--- /dev/null
+++ b/frontend/wrangler.toml
@@ -0,0 +1,19 @@
+name = "openneato-demo"
+main = "mock/worker.js"
+compatibility_date = "2026-05-18"
+compatibility_flags = ["nodejs_compat"]
+
+workers_dev = false
+preview_urls = false
+
+assets = { directory = "dist", binding = "ASSETS" }
+
+[vars]
+DEMO_MODE = "true"
+
+[[routes]]
+pattern = "openneato-demo.renjfk.com"
+custom_domain = true
+
+[observability]
+enabled = true

From d9f74c3b56d0381fef77392307beba56a605a57d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:23:22 +0300
Subject: [PATCH 25/44] fix: align Cloudflare demo config

---
 frontend/wrangler.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index 0e12537..852e2f9 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -1,6 +1,6 @@
-name = "openneato-demo"
+name = "openneato"
 main = "mock/worker.js"
-compatibility_date = "2026-05-18"
+compatibility_date = "2026-05-17"
 compatibility_flags = ["nodejs_compat"]
 
 workers_dev = false

From 5d56b1d487f708dc9ab81ea0f15fdfbaad4c7c6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:28:15 +0300
Subject: [PATCH 26/44] fix: align demo history fixtures

---
 frontend/mock/worker.js | 78 ++++++++++++++++++++++++++++-------------
 frontend/wrangler.toml  |  5 +++
 2 files changed, 58 insertions(+), 25 deletions(-)

diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 02ce878..09094b8 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -1,3 +1,7 @@
+import mapdataEmpty04 from "./mapdata-empty-04.jsonl";
+import mapdataHouse03 from "./mapdata-house-03.jsonl";
+import mapdataSpot01 from "./mapdata-spot-01.jsonl";
+import mapdataSpot02 from "./mapdata-spot-02.jsonl";
 import { createMockApi } from "./shared-api.js";
 import { createScenarioState, scenarioCookie, scenarioFromRequest } from "./shared-state.js";
 
@@ -15,6 +19,13 @@ const json = (data, status = 200) =>
 
 const err = (message, status = 500) => json({ error: message }, status);
 
+const historyFixtures = [
+    ["mapdata-empty-04.jsonl", mapdataEmpty04],
+    ["mapdata-house-03.jsonl", mapdataHouse03],
+    ["mapdata-spot-01.jsonl", mapdataSpot01],
+    ["mapdata-spot-02.jsonl", mapdataSpot02],
+];
+
 async function handleCollect(request) {
     try {
         const form = await request.formData();
@@ -49,33 +60,47 @@ async function handleCollect(request) {
 }
 
 const createDefaultHistory = () => {
-    const now = Math.floor(Date.now() / 1000);
-    const house = `${now - 7200}`;
-    const spot = `${now - 3600}`;
-
-    return new Map([
-        [
-            `${house}.jsonl.hs`,
-            [
-                `{"type":"session","time":${house},"mode":"house","battery":95}`,
-                '{"x":0.0,"y":0.0,"t":0.0,"ts":0.0}',
-                '{"x":0.5,"y":0.2,"t":15.0,"ts":4.0}',
-                '{"x":1.2,"y":0.8,"t":45.0,"ts":10.0}',
-                '{"type":"summary","duration":1800,"distanceTraveled":34.5,"areaCovered":26.2,"batteryEnd":62}',
-            ],
-        ],
-        [
-            `${spot}.jsonl.hs`,
-            [
-                `{"type":"session","time":${spot},"mode":"spot","battery":80}`,
-                '{"x":0.0,"y":0.0,"t":0.0,"ts":0.0}',
-                '{"x":0.3,"y":0.3,"t":45.0,"ts":2.0}',
-                '{"type":"summary","duration":420,"distanceTraveled":8.4,"areaCovered":4.1,"batteryEnd":71}',
-            ],
-        ],
-    ]);
+    return new Map(
+        historyFixtures.map(([name, content]) => [
+            name,
+            content
+                .trim()
+                .split("\n")
+                .filter((line) => line.length > 0),
+        ]),
+    );
 };
 
+function startRecordingTimer() {
+    const recordingFile = [...context.historySessions.entries()].find(
+        ([, lines]) => !lines.some((line) => line.includes('"type":"summary"')),
+    );
+    if (!recordingFile) return;
+
+    const [recordingName, recordingLines] = recordingFile;
+    const lastPose = [...recordingLines].reverse().find((line) => line.includes('"x":'));
+    const pos = lastPose ? JSON.parse(lastPose) : { x: 0, y: 0, t: 0, ts: 7244 };
+    let simX = pos.x;
+    let simY = pos.y;
+    let simT = pos.t;
+    let simTs = pos.ts;
+
+    setInterval(() => {
+        simT += (Math.random() - 0.5) * 30;
+        if (simT < 0) simT += 360;
+        if (simT >= 360) simT -= 360;
+        const rad = (simT * Math.PI) / 180;
+        const step = 0.08 + Math.random() * 0.12;
+        simX += Math.cos(rad) * step;
+        simY -= Math.sin(rad) * step;
+        simTs += 2.0 + Math.random() * 0.3;
+        const lines = context.historySessions.get(recordingName);
+        if (!lines) return;
+        if (lines.length > 1) lines.splice(1, 1);
+        lines.push(`{"x":${simX.toFixed(3)},"y":${simY.toFixed(3)},"t":${simT.toFixed(1)},"ts":${simTs.toFixed(1)}}`);
+    }, 2000);
+}
+
 let initializedScenario = null;
 let bootTime = Date.now();
 
@@ -104,6 +129,9 @@ function initScenario(rawScenario) {
     initializedScenario = scenario;
 }
 
+initScenario("ok");
+startRecordingTimer();
+
 const toWorkerResponse = (response) => {
     if (response === false) return err("not found", 404);
     if (response.offline) return err("Device unreachable", 503);
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index 852e2f9..f52752a 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -8,6 +8,11 @@ preview_urls = false
 
 assets = { directory = "dist", binding = "ASSETS" }
 
+[[rules]]
+type = "Text"
+globs = ["**/*.jsonl"]
+fallthrough = true
+
 [vars]
 DEMO_MODE = "true"
 

From 5a9bd5898efab72868031553ffbb997ee908ebea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:30:16 +0300
Subject: [PATCH 27/44] fix: avoid global timer in demo worker

---
 frontend/mock/worker.js | 59 +++++++++++++++++++++++++++--------------
 frontend/wrangler.toml  |  2 +-
 2 files changed, 40 insertions(+), 21 deletions(-)

diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 09094b8..8096f40 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -71,38 +71,56 @@ const createDefaultHistory = () => {
     );
 };
 
-function startRecordingTimer() {
+function resetRecordingSimulation() {
     const recordingFile = [...context.historySessions.entries()].find(
         ([, lines]) => !lines.some((line) => line.includes('"type":"summary"')),
     );
-    if (!recordingFile) return;
+    if (!recordingFile) {
+        recordingSimulation = null;
+        return;
+    }
 
     const [recordingName, recordingLines] = recordingFile;
     const lastPose = [...recordingLines].reverse().find((line) => line.includes('"x":'));
     const pos = lastPose ? JSON.parse(lastPose) : { x: 0, y: 0, t: 0, ts: 7244 };
-    let simX = pos.x;
-    let simY = pos.y;
-    let simT = pos.t;
-    let simTs = pos.ts;
-
-    setInterval(() => {
-        simT += (Math.random() - 0.5) * 30;
-        if (simT < 0) simT += 360;
-        if (simT >= 360) simT -= 360;
-        const rad = (simT * Math.PI) / 180;
+    recordingSimulation = {
+        name: recordingName,
+        x: pos.x,
+        y: pos.y,
+        t: pos.t,
+        ts: pos.ts,
+        lastUpdate: Date.now(),
+    };
+}
+
+function updateRecordingSession() {
+    if (!recordingSimulation) return;
+    const elapsed = Math.floor((Date.now() - recordingSimulation.lastUpdate) / 2000);
+    if (elapsed <= 0) return;
+    recordingSimulation.lastUpdate += elapsed * 2000;
+
+    const lines = context.historySessions.get(recordingSimulation.name);
+    if (!lines) return;
+
+    for (let i = 0; i < elapsed; i++) {
+        recordingSimulation.t += (Math.random() - 0.5) * 30;
+        if (recordingSimulation.t < 0) recordingSimulation.t += 360;
+        if (recordingSimulation.t >= 360) recordingSimulation.t -= 360;
+        const rad = (recordingSimulation.t * Math.PI) / 180;
         const step = 0.08 + Math.random() * 0.12;
-        simX += Math.cos(rad) * step;
-        simY -= Math.sin(rad) * step;
-        simTs += 2.0 + Math.random() * 0.3;
-        const lines = context.historySessions.get(recordingName);
-        if (!lines) return;
+        recordingSimulation.x += Math.cos(rad) * step;
+        recordingSimulation.y -= Math.sin(rad) * step;
+        recordingSimulation.ts += 2.0 + Math.random() * 0.3;
         if (lines.length > 1) lines.splice(1, 1);
-        lines.push(`{"x":${simX.toFixed(3)},"y":${simY.toFixed(3)},"t":${simT.toFixed(1)},"ts":${simTs.toFixed(1)}}`);
-    }, 2000);
+        lines.push(
+            `{"x":${recordingSimulation.x.toFixed(3)},"y":${recordingSimulation.y.toFixed(3)},"t":${recordingSimulation.t.toFixed(1)},"ts":${recordingSimulation.ts.toFixed(1)}}`,
+        );
+    }
 }
 
 let initializedScenario = null;
 let bootTime = Date.now();
+let recordingSimulation = null;
 
 const context = {
     state: {},
@@ -127,10 +145,10 @@ function initScenario(rawScenario) {
     context.historySessions = createDefaultHistory();
     bootTime = Date.now();
     initializedScenario = scenario;
+    resetRecordingSimulation();
 }
 
 initScenario("ok");
-startRecordingTimer();
 
 const toWorkerResponse = (response) => {
     if (response === false) return err("not found", 404);
@@ -145,6 +163,7 @@ async function handleApi(request, env) {
     const url = new URL(request.url);
     const scenario = scenarioFromRequest(url.searchParams, request.headers.get("Cookie") ?? "");
     if (scenario !== initializedScenario) initScenario(scenario);
+    updateRecordingSession();
 
     await sleep(randomInt(50, 200));
 
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index f52752a..bd3236f 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -1,4 +1,4 @@
-name = "openneato"
+name = "openneato-demo"
 main = "mock/worker.js"
 compatibility_date = "2026-05-17"
 compatibility_flags = ["nodejs_compat"]

From e6f94d856852e94a43c18481fa765f780f0b0d51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:40:54 +0300
Subject: [PATCH 28/44] fix: align demo firmware version

---
 frontend/mock/build-info.js               |  1 +
 frontend/mock/server.js                   |  5 +++--
 frontend/mock/shared-api.js               |  3 ++-
 frontend/mock/shared-version.js           |  7 +++++++
 frontend/mock/worker.js                   |  4 ++--
 frontend/package.json                     |  2 +-
 frontend/scripts/write_demo_build_info.js | 16 ++++++++++++++++
 7 files changed, 32 insertions(+), 6 deletions(-)
 create mode 100644 frontend/mock/build-info.js
 create mode 100644 frontend/mock/shared-version.js
 create mode 100644 frontend/scripts/write_demo_build_info.js

diff --git a/frontend/mock/build-info.js b/frontend/mock/build-info.js
new file mode 100644
index 0000000..bc635bb
--- /dev/null
+++ b/frontend/mock/build-info.js
@@ -0,0 +1 @@
+export const DEMO_VERSION = "0.0-5a9bd58";
diff --git a/frontend/mock/server.js b/frontend/mock/server.js
index 5f80661..4f1121c 100644
--- a/frontend/mock/server.js
+++ b/frontend/mock/server.js
@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createMockApi } from "./shared-api.js";
 import { createScenarioState, scenarioFromRequest } from "./shared-state.js";
+import { DEFAULT_MOCK_VERSION, mockVersionFromHash } from "./shared-version.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -17,9 +18,9 @@ const rand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
 const getVersion = () => {
     try {
         const hash = execSync("git rev-parse --short=7 HEAD", { encoding: "utf8" }).trim();
-        return `0.0-${hash}`;
+        return mockVersionFromHash(hash);
     } catch {
-        return "0.0";
+        return DEFAULT_MOCK_VERSION;
     }
 };
 
diff --git a/frontend/mock/shared-api.js b/frontend/mock/shared-api.js
index d2e52e6..438451b 100644
--- a/frontend/mock/shared-api.js
+++ b/frontend/mock/shared-api.js
@@ -645,9 +645,10 @@ function createMockApi(context) {
         }
 
         if (method === "GET" && path === "/api/firmware/version") {
+            const version = state.firmwareVersion ?? (await context.getVersion());
             return jsonResponse({
                 name: "OpenNeato",
-                version: state.firmwareVersion ?? context.getVersion(),
+                version,
                 chip: "ESP32-C3",
                 model: state.identifying ? "" : state.unsupported ? "Botvac Connected" : "Botvac D7",
                 hostname: "neato-kitchen",
diff --git a/frontend/mock/shared-version.js b/frontend/mock/shared-version.js
new file mode 100644
index 0000000..d2c00b7
--- /dev/null
+++ b/frontend/mock/shared-version.js
@@ -0,0 +1,7 @@
+const DEFAULT_MOCK_VERSION = "0.0-dev";
+
+function mockVersionFromHash(hash) {
+    return hash ? `0.0-${hash}` : DEFAULT_MOCK_VERSION;
+}
+
+export { DEFAULT_MOCK_VERSION, mockVersionFromHash };
diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 8096f40..5a79b51 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -1,3 +1,4 @@
+import { DEMO_VERSION } from "./build-info.js";
 import mapdataEmpty04 from "./mapdata-empty-04.jsonl";
 import mapdataHouse03 from "./mapdata-house-03.jsonl";
 import mapdataSpot01 from "./mapdata-spot-01.jsonl";
@@ -121,14 +122,13 @@ function updateRecordingSession() {
 let initializedScenario = null;
 let bootTime = Date.now();
 let recordingSimulation = null;
-
 const context = {
     state: {},
     faults: {},
     historySessions: new Map(),
     rand: randomInt,
     sleep,
-    getVersion: () => "0.0",
+    getVersion: () => DEMO_VERSION,
     getBootTime: () => bootTime,
     reboot: () => {
         bootTime = Date.now();
diff --git a/frontend/package.json b/frontend/package.json
index ee38955..4c94bdd 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,7 +6,7 @@
     "scripts": {
         "dev": "npm run gen:types && vite",
         "gen:types": "openapi-typescript --root-types --root-types-no-schema-prefix --output src/types.generated.ts api/openapi.yaml",
-        "build:demo": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build --mode demo",
+        "build:demo": "node scripts/write_demo_build_info.js && biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build --mode demo",
         "build": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build && node scripts/embed_frontend.js",
         "preview": "vite preview",
         "check": "biome check",
diff --git a/frontend/scripts/write_demo_build_info.js b/frontend/scripts/write_demo_build_info.js
new file mode 100644
index 0000000..323e35b
--- /dev/null
+++ b/frontend/scripts/write_demo_build_info.js
@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { mockVersionFromHash } from "../mock/shared-version.js";
+
+function shortHash() {
+    const envHash = process.env.CF_PAGES_COMMIT_SHA || process.env.GITHUB_SHA || process.env.COMMIT_SHA;
+    if (envHash) return envHash.slice(0, 7);
+
+    try {
+        return execSync("git rev-parse --short=7 HEAD", { encoding: "utf8" }).trim();
+    } catch {
+        return "dev";
+    }
+}
+
+writeFileSync("mock/build-info.js", `export const DEMO_VERSION = "${mockVersionFromHash(shortHash())}";\n`);

From 4f2dc6d9dbd3b9d7ddb3942dd8362646b24ba7c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 01:48:22 +0300
Subject: [PATCH 29/44] fix: persist demo scenario client-side

---
 .gitignore                  | 1 +
 frontend/mock/build-info.js | 1 -
 frontend/src/main.tsx       | 6 ++++++
 3 files changed, 7 insertions(+), 1 deletion(-)
 delete mode 100644 frontend/mock/build-info.js

diff --git a/.gitignore b/.gitignore
index fd037b4..746ef71 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ firmware/compile_commands.json
 firmware/src/web_assets.h
 frontend/node_modules
 frontend/dist
+frontend/mock/build-info.js
 frontend/src/types.generated.ts
 flash/openneato-flash
 release/
diff --git a/frontend/mock/build-info.js b/frontend/mock/build-info.js
deleted file mode 100644
index bc635bb..0000000
--- a/frontend/mock/build-info.js
+++ /dev/null
@@ -1 +0,0 @@
-export const DEMO_VERSION = "0.0-5a9bd58";
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index a73a41e..6671ec0 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -5,6 +5,12 @@ import "./style.css";
 declare const __DEMO_BUILD__: boolean;
 
 if (__DEMO_BUILD__) {
+    const scenario = new URLSearchParams(location.search).get("scenario");
+    if (scenario) {
+        // biome-ignore lint/suspicious/noDocumentCookie: The Cookie Store API is not universal, and this runs before API calls.
+        document.cookie = `openneato_scenario=${encodeURIComponent(scenario)}; Path=/; SameSite=Lax`;
+    }
+
     void import("./analytics").then(({ startAnalytics }) => startAnalytics());
 }
 

From 3bc08d01fd2fed02599558936aa127a577d3b288 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 02:20:13 +0300
Subject: [PATCH 30/44] fix: harden demo worker

---
 frontend/mock/shared-api.js |   4 +-
 frontend/mock/worker.js     | 276 +++++++++++++++++++++++++++++-------
 2 files changed, 227 insertions(+), 53 deletions(-)

diff --git a/frontend/mock/shared-api.js b/frontend/mock/shared-api.js
index 438451b..7724f54 100644
--- a/frontend/mock/shared-api.js
+++ b/frontend/mock/shared-api.js
@@ -15,6 +15,7 @@ const errorResponse = (message, status = 500) => jsonResponse({ error: message }
 
 const byteLength = (value) => textEncoder.encode(value).length;
 const vBattFromFuel = (fuel) => Number((12.0 + (fuel / 100) * 4.6).toFixed(2));
+const isSafeFilename = (name) => /^[A-Za-z0-9._-]+$/.test(name) && !name.includes("..");
 
 const mockLogs = [
     { name: "current.jsonl", size: 8192, compressed: false },
@@ -186,7 +187,7 @@ const listHistory = (historySessions, faults) => {
 const parseMultipartJsonlUpload = (bodyBytes) => {
     const bodyStr = new TextDecoder("latin1").decode(bodyBytes);
     const nameMatch = bodyStr.match(/filename="([^"]+)"/);
-    if (!nameMatch?.[1].endsWith(".jsonl")) {
+    if (!nameMatch?.[1].endsWith(".jsonl") || !isSafeFilename(nameMatch[1])) {
         return { error: "Invalid file: expected a .jsonl session file", status: 400 };
     }
     const headerEnd = bodyStr.indexOf("\r\n\r\n");
@@ -484,6 +485,7 @@ function createMockApi(context) {
         const logFileMatch = path.match(/^\/api\/logs\/(.+)$/);
         if (logFileMatch) {
             const filename = decodeURIComponent(logFileMatch[1]);
+            if (!isSafeFilename(filename)) return errorResponse("invalid filename", 400);
             if (method === "GET") {
                 if (faults.logsRead) return errorResponse("SPIFFS read failed", 500);
                 return textResponse(mockLogContent, 200, {
diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 5a79b51..d67bfd7 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -8,6 +8,10 @@ import { createScenarioState, scenarioCookie, scenarioFromRequest } from "./shar
 
 const UMAMI_ENDPOINT = "https://cloud.umami.is/api/send";
 const WEBSITE_ID = "417b882b-03c5-45d2-b070-9d7b8b7855d4";
+const SESSION_COOKIE = "openneato_demo_session";
+const MAX_BODY_BYTES = 64 * 1024;
+const MAX_SESSIONS = 100;
+const SESSION_TTL_MS = 60 * 60 * 1000;
 
 const randomInt = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -20,6 +24,73 @@ const json = (data, status = 200) =>
 
 const err = (message, status = 500) => json({ error: message }, status);
 
+const SECURITY_HEADERS = {
+    "Content-Security-Policy": [
+        "default-src 'self'",
+        "script-src 'self'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        "object-src 'none'",
+        "base-uri 'none'",
+        "form-action 'self'",
+        "frame-ancestors 'none'",
+    ].join("; "),
+    "Cross-Origin-Resource-Policy": "same-origin",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+};
+
+const withSecurityHeaders = (response) => {
+    const secured = new Response(response.body, response);
+    for (const [name, value] of Object.entries(SECURITY_HEADERS)) secured.headers.set(name, value);
+    return secured;
+};
+
+const parseCookieValue = (cookieHeader, name) => {
+    for (const part of cookieHeader.split(";")) {
+        const [rawName, ...rawValue] = part.trim().split("=");
+        if (rawName !== name) continue;
+        try {
+            return decodeURIComponent(rawValue.join("="));
+        } catch {
+            return "";
+        }
+    }
+    return "";
+};
+
+const sessionCookie = (id) =>
+    `${SESSION_COOKIE}=${encodeURIComponent(id)}; Path=/; Max-Age=3600; SameSite=Lax; HttpOnly; Secure`;
+
+async function readBodyWithLimit(request) {
+    if (!request.body) return new Uint8Array();
+
+    const reader = request.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > MAX_BODY_BYTES) {
+            await reader.cancel();
+            throw new Error("Request body too large");
+        }
+        chunks.push(value);
+    }
+
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+
 const historyFixtures = [
     ["mapdata-empty-04.jsonl", mapdataEmpty04],
     ["mapdata-house-03.jsonl", mapdataHouse03],
@@ -29,8 +100,22 @@ const historyFixtures = [
 
 async function handleCollect(request) {
     try {
+        const url = new URL(request.url);
+        const origin = request.headers.get("Origin");
+        if (origin) {
+            let originHost = "";
+            try {
+                originHost = new URL(origin).host;
+            } catch {
+                return new Response(null, { status: 403 });
+            }
+            if (originHost !== url.host) return new Response(null, { status: 403 });
+        }
+        const contentLength = Number(request.headers.get("Content-Length") || "0");
+        if (contentLength > MAX_BODY_BYTES) return new Response(null, { status: 413 });
+
         const form = await request.formData();
-        const hostname = new URL(request.url).hostname;
+        const hostname = url.hostname;
 
         const response = await fetch(UMAMI_ENDPOINT, {
             method: "POST",
@@ -72,19 +157,19 @@ const createDefaultHistory = () => {
     );
 };
 
-function resetRecordingSimulation() {
-    const recordingFile = [...context.historySessions.entries()].find(
+function resetRecordingSimulation(session) {
+    const recordingFile = [...session.context.historySessions.entries()].find(
         ([, lines]) => !lines.some((line) => line.includes('"type":"summary"')),
     );
     if (!recordingFile) {
-        recordingSimulation = null;
+        session.recordingSimulation = null;
         return;
     }
 
     const [recordingName, recordingLines] = recordingFile;
     const lastPose = [...recordingLines].reverse().find((line) => line.includes('"x":'));
     const pos = lastPose ? JSON.parse(lastPose) : { x: 0, y: 0, t: 0, ts: 7244 };
-    recordingSimulation = {
+    session.recordingSimulation = {
         name: recordingName,
         x: pos.x,
         y: pos.y,
@@ -94,13 +179,14 @@ function resetRecordingSimulation() {
     };
 }
 
-function updateRecordingSession() {
+function updateRecordingSession(session) {
+    const recordingSimulation = session.recordingSimulation;
     if (!recordingSimulation) return;
     const elapsed = Math.floor((Date.now() - recordingSimulation.lastUpdate) / 2000);
     if (elapsed <= 0) return;
     recordingSimulation.lastUpdate += elapsed * 2000;
 
-    const lines = context.historySessions.get(recordingSimulation.name);
+    const lines = session.context.historySessions.get(recordingSimulation.name);
     if (!lines) return;
 
     for (let i = 0; i < elapsed; i++) {
@@ -119,36 +205,102 @@ function updateRecordingSession() {
     }
 }
 
-let initializedScenario = null;
-let bootTime = Date.now();
-let recordingSimulation = null;
-const context = {
-    state: {},
-    faults: {},
-    historySessions: new Map(),
-    rand: randomInt,
-    sleep,
-    getVersion: () => DEMO_VERSION,
-    getBootTime: () => bootTime,
-    reboot: () => {
-        bootTime = Date.now();
-    },
-};
+const sessions = new Map();
 
-const api = createMockApi(context);
+function createSession(id) {
+    const session = {
+        id,
+        api: null,
+        context: null,
+        initializedScenario: null,
+        bootTime: Date.now(),
+        lastAccess: Date.now(),
+        recordingSimulation: null,
+    };
+    session.context = {
+        state: {},
+        faults: {},
+        historySessions: new Map(),
+        rand: randomInt,
+        sleep,
+        getVersion: () => DEMO_VERSION,
+        getBootTime: () => session.bootTime,
+        reboot: () => {
+            session.bootTime = Date.now();
+        },
+    };
+    session.api = createMockApi(session.context);
+    initScenario(session, "ok");
+    return session;
+}
 
-function initScenario(rawScenario) {
+function pruneSessions(now) {
+    for (const [id, session] of sessions) {
+        if (now - session.lastAccess > SESSION_TTL_MS) sessions.delete(id);
+    }
+    while (sessions.size > MAX_SESSIONS) {
+        let oldestId = null;
+        let oldestAccess = Infinity;
+        for (const [id, session] of sessions) {
+            if (session.lastAccess < oldestAccess) {
+                oldestId = id;
+                oldestAccess = session.lastAccess;
+            }
+        }
+        if (!oldestId) break;
+        sessions.delete(oldestId);
+    }
+}
+
+function getSession(request) {
+    const now = Date.now();
+    pruneSessions(now);
+
+    const cookieHeader = request.headers.get("Cookie") ?? "";
+    let id = parseCookieValue(cookieHeader, SESSION_COOKIE);
+    let isNew = false;
+    if (!/^[0-9a-f-]{36}$/i.test(id)) {
+        id = crypto.randomUUID();
+        isNew = true;
+    }
+
+    let session = sessions.get(id);
+    if (!session) {
+        session = createSession(id);
+        sessions.set(id, session);
+        isNew = true;
+    }
+    session.lastAccess = now;
+    return { session, isNew };
+}
+
+function initScenario(session, rawScenario) {
     const scenario = rawScenario.trim() || "ok";
+    if (scenario === session.initializedScenario) return;
     const scenarioState = createScenarioState(scenario);
-    context.state = scenarioState.state;
-    context.faults = scenarioState.faults;
-    context.historySessions = createDefaultHistory();
-    bootTime = Date.now();
-    initializedScenario = scenario;
-    resetRecordingSimulation();
+    session.context.state = scenarioState.state;
+    session.context.faults = scenarioState.faults;
+    session.context.historySessions = createDefaultHistory();
+    session.bootTime = Date.now();
+    session.initializedScenario = scenario;
+    resetRecordingSimulation(session);
 }
 
-initScenario("ok");
+function isBlockedDemoEndpoint(method, path, query) {
+    if (method === "DELETE") return true;
+    if (method !== "POST") return false;
+    if (path === "/api/firmware/update" || path === "/api/history/import") return true;
+    if (["/api/system/restart", "/api/system/format-fs", "/api/system/reset"].includes(path)) return true;
+    return path === "/api/power" && ["restart", "shutdown"].includes(query.action || "");
+}
+
+function scenarioForRequest(url, request) {
+    try {
+        return scenarioFromRequest(url.searchParams, request.headers.get("Cookie") ?? "");
+    } catch {
+        return (url.searchParams.get("scenario") || "ok").trim() || "ok";
+    }
+}
 
 const toWorkerResponse = (response) => {
     if (response === false) return err("not found", 404);
@@ -161,37 +313,53 @@ const toWorkerResponse = (response) => {
 
 async function handleApi(request, env) {
     const url = new URL(request.url);
-    const scenario = scenarioFromRequest(url.searchParams, request.headers.get("Cookie") ?? "");
-    if (scenario !== initializedScenario) initScenario(scenario);
-    updateRecordingSession();
+    const { session, isNew } = getSession(request);
+    const scenario = scenarioForRequest(url, request);
+    initScenario(session, scenario);
+    updateRecordingSession(session);
 
     await sleep(randomInt(50, 200));
 
     const demoMode = (env.DEMO_MODE ?? "true").toLowerCase() === "true";
+    const query = Object.fromEntries(url.searchParams);
 
-    if (demoMode && request.method === "POST" && url.pathname === "/api/firmware/update") {
-        return err("Firmware upload is disabled in demo mode", 403);
+    if (demoMode && isBlockedDemoEndpoint(request.method, url.pathname, query)) {
+        const response = err("This action is disabled in demo mode", 403);
+        if (isNew) response.headers.append("Set-Cookie", sessionCookie(session.id));
+        if (url.searchParams.has("scenario")) response.headers.append("Set-Cookie", scenarioCookie(scenario));
+        return response;
     }
-    if (demoMode && request.method === "POST" && url.pathname === "/api/history/import") {
-        return err("Session import is disabled in demo mode", 403);
+
+    const contentLength = Number(request.headers.get("Content-Length") || "0");
+    if (contentLength > MAX_BODY_BYTES) {
+        const response = err("Request body too large", 413);
+        if (isNew) response.headers.append("Set-Cookie", sessionCookie(session.id));
+        if (url.searchParams.has("scenario")) response.headers.append("Set-Cookie", scenarioCookie(scenario));
+        return response;
     }
 
     let cachedBytes = null;
     const bytes = async () => {
-        cachedBytes ??= new Uint8Array(await request.arrayBuffer());
+        cachedBytes ??= await readBodyWithLimit(request);
         return cachedBytes;
     };
 
-    const response = toWorkerResponse(
-        await api.handle({
-            method: request.method,
-            path: url.pathname,
-            query: Object.fromEntries(url.searchParams),
-            bytes,
-            text: async () => new TextDecoder().decode(await bytes()),
-        }),
-    );
-    if (url.searchParams.has("scenario")) response.headers.set("Set-Cookie", scenarioCookie(scenario));
+    let response;
+    try {
+        response = toWorkerResponse(
+            await session.api.handle({
+                method: request.method,
+                path: url.pathname,
+                query,
+                bytes,
+                text: async () => new TextDecoder().decode(await bytes()),
+            }),
+        );
+    } catch (error) {
+        response = error.message === "Request body too large" ? err(error.message, 413) : err("Internal error", 500);
+    }
+    if (isNew) response.headers.append("Set-Cookie", sessionCookie(session.id));
+    if (url.searchParams.has("scenario")) response.headers.append("Set-Cookie", scenarioCookie(scenario));
     return response;
 }
 
@@ -214,8 +382,12 @@ async function serveAsset(request, env) {
 export default {
     async fetch(request, env) {
         const url = new URL(request.url);
-        if (request.method === "POST" && url.pathname === "/api/collect") return handleCollect(request);
-        if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/repos/")) return handleApi(request, env);
-        return serveAsset(request, env);
+        if (request.method === "POST" && url.pathname === "/api/collect") {
+            return withSecurityHeaders(await handleCollect(request));
+        }
+        if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/repos/")) {
+            return withSecurityHeaders(await handleApi(request, env));
+        }
+        return withSecurityHeaders(await serveAsset(request, env));
     },
 };

From 7a600cd662debcf24ef575ecb5889361797d5c23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 02:40:04 +0300
Subject: [PATCH 31/44] fix: rate limit demo analytics

---
 frontend/mock/worker.js | 28 +++++++++++++++++++++++++---
 frontend/wrangler.toml  |  8 ++++++++
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index d67bfd7..711bf6f 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -65,6 +65,20 @@ const parseCookieValue = (cookieHeader, name) => {
 const sessionCookie = (id) =>
     `${SESSION_COOKIE}=${encodeURIComponent(id)}; Path=/; Max-Age=3600; SameSite=Lax; HttpOnly; Secure`;
 
+async function checkAnalyticsRateLimit(request, env) {
+    if (!env.ANALYTICS_RATE_LIMITER) return null;
+
+    const cookieSession = parseCookieValue(request.headers.get("Cookie") ?? "", SESSION_COOKIE);
+    const clientId = cookieSession || request.headers.get("CF-Connecting-IP") || "anonymous";
+    const { success } = await env.ANALYTICS_RATE_LIMITER.limit({ key: `collect:${clientId}` });
+    if (success) return null;
+
+    return new Response(null, {
+        status: 429,
+        headers: { "Retry-After": "60" },
+    });
+}
+
 async function readBodyWithLimit(request) {
     if (!request.body) return new Uint8Array();
 
@@ -98,7 +112,7 @@ const historyFixtures = [
     ["mapdata-spot-02.jsonl", mapdataSpot02],
 ];
 
-async function handleCollect(request) {
+async function handleCollect(request, env) {
     try {
         const url = new URL(request.url);
         const origin = request.headers.get("Origin");
@@ -114,7 +128,15 @@ async function handleCollect(request) {
         const contentLength = Number(request.headers.get("Content-Length") || "0");
         if (contentLength > MAX_BODY_BYTES) return new Response(null, { status: 413 });
 
-        const form = await request.formData();
+        const rateLimited = await checkAnalyticsRateLimit(request, env);
+        if (rateLimited) return rateLimited;
+
+        const formRequest = new Request(request.url, {
+            method: "POST",
+            headers: request.headers,
+            body: await readBodyWithLimit(request),
+        });
+        const form = await formRequest.formData();
         const hostname = url.hostname;
 
         const response = await fetch(UMAMI_ENDPOINT, {
@@ -383,7 +405,7 @@ export default {
     async fetch(request, env) {
         const url = new URL(request.url);
         if (request.method === "POST" && url.pathname === "/api/collect") {
-            return withSecurityHeaders(await handleCollect(request));
+            return withSecurityHeaders(await handleCollect(request, env));
         }
         if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/repos/")) {
             return withSecurityHeaders(await handleApi(request, env));
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index bd3236f..b962b60 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -16,6 +16,14 @@ fallthrough = true
 [vars]
 DEMO_MODE = "true"
 
+[[ratelimits]]
+name = "ANALYTICS_RATE_LIMITER"
+namespace_id = "20260518"
+
+  [ratelimits.simple]
+  limit = 60
+  period = 60
+
 [[routes]]
 pattern = "openneato-demo.renjfk.com"
 custom_domain = true

From cd17822f5c503454eb946168638320671b7f099f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 09:52:45 +0300
Subject: [PATCH 32/44] fix: share polling and add duplicate checks

---
 AGENTS.md                                 |    5 +-
 frontend/.jscpd.json                      |    5 +
 frontend/package-lock.json                | 1390 ++++++++++++++++++++-
 frontend/package.json                     |    6 +-
 frontend/src/api.ts                       |   33 +-
 frontend/src/hooks/use-poll.ts            |   57 +
 frontend/src/views/history.tsx            |   32 +-
 frontend/src/views/settings.tsx           |   37 +-
 frontend/src/views/settings/use-reboot.ts |   43 +-
 9 files changed, 1506 insertions(+), 102 deletions(-)
 create mode 100644 frontend/.jscpd.json
 create mode 100644 frontend/src/hooks/use-poll.ts

diff --git a/AGENTS.md b/AGENTS.md
index b175d41..15b6634 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@ Three top-level components: `firmware/` (ESP32 C/C++), `frontend/` (Preact SPA),
 - Flash tool: Go CLI, cross-compiled via GoReleaser, uses esptool subprocess
 - Mock server: `frontend/mock/server.js` Vite plugin, `SCENARIO` constant for state switching. Reset to `"ok"` before
   committing.
-- Build pipeline: `npm run build` -> lint -> `openapi-typescript` regenerates `src/types.generated.ts` from
+- Build pipeline: `npm run build` -> lint -> `jscpd` duplicate check -> `openapi-typescript` regenerates `src/types.generated.ts` from
   `frontend/api/openapi.yaml` -> `check_api_paths.js` enforces firmware↔spec route parity -> tsc -> vite ->
   `embed_frontend.js` generates `web_assets.h`. `frontend/api/openapi.yaml` ships as a release asset.
 
@@ -85,8 +85,9 @@ Verify GitHub Actions workflow changes: install `actionlint` if missing, then ru
 ```bash
 cd frontend
 npm run dev          # Vite dev server with mock API
-npm run build        # Lint + type check + build + embed into firmware header
+npm run build        # Lint + duplicate check + type check + build + embed into firmware header
 npm run check        # Biome lint/format check
+npm run dupes        # Duplicate code check via jscpd
 npm run fix          # Auto-fix safe issues
 ```
 
diff --git a/frontend/.jscpd.json b/frontend/.jscpd.json
new file mode 100644
index 0000000..458d0e8
--- /dev/null
+++ b/frontend/.jscpd.json
@@ -0,0 +1,5 @@
+{
+    "threshold": 1.1,
+    "minLines": 5,
+    "minTokens": 75
+}
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 150451a..10f091a 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,6 +13,7 @@
             "devDependencies": {
                 "@biomejs/biome": "2.4.15",
                 "@preact/preset-vite": "2.10.5",
+                "jscpd": "4.2.2",
                 "openapi-typescript": "7.13.0",
                 "typescript": "6.0.3",
                 "vite": "8.0.13",
@@ -621,6 +622,17 @@
                 "node": ">=16"
             }
         },
+        "node_modules/@colors/colors": {
+            "version": "1.5.0",
+            "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz",
+            "integrity": "sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==",
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "engines": {
+                "node": ">=0.1.90"
+            }
+        },
         "node_modules/@cspotcode/source-map-support": {
             "version": "0.8.1",
             "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
@@ -1709,6 +1721,70 @@
                 "@jridgewell/sourcemap-codec": "^1.4.14"
             }
         },
+        "node_modules/@jscpd/badge-reporter": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/@jscpd/badge-reporter/-/badge-reporter-4.2.2.tgz",
+            "integrity": "sha512-03ngWGBtvdL6dRC7+Q/4FdoUozN4KBHpaJ1SjGnPaMuPoEmcGDdw7W/+HfhPWSwpzam3lfTM2yBsGhrG2g3LqQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "badgen": "^3.2.3",
+                "colors": "^1.4.0",
+                "fs-extra": "^11.2.0"
+            }
+        },
+        "node_modules/@jscpd/core": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/@jscpd/core/-/core-4.2.2.tgz",
+            "integrity": "sha512-YheyoZAVIeZXyQ5mE1lZ+no8Rs8bo02PXnTfW6PN9QrPUOlRsuJ0br5F3T/H6GU8S2DUP5gUJPOp1Lz7oxN+aA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "eventemitter3": "^5.0.1"
+            }
+        },
+        "node_modules/@jscpd/finder": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/@jscpd/finder/-/finder-4.2.2.tgz",
+            "integrity": "sha512-HGsvprcIVTjSU3x8+Ofb5mKq2gRYYZ8Cd1O00w97x8GWUub5sHLGOdvlP4Bw19FVoZzBz+1pjnF5dDvzEoj4rg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jscpd/core": "4.2.2",
+                "@jscpd/tokenizer": "4.2.2",
+                "blamer": "^1.0.6",
+                "bytes": "^3.1.2",
+                "cli-table3": "^0.6.5",
+                "colors": "^1.4.0",
+                "fast-glob": "^3.3.2",
+                "fs-extra": "^11.2.0",
+                "markdown-table": "^2.0.0",
+                "pug": "^3.0.3"
+            }
+        },
+        "node_modules/@jscpd/html-reporter": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/@jscpd/html-reporter/-/html-reporter-4.2.2.tgz",
+            "integrity": "sha512-pw+spkYfgWNiDH9bURB0jWzGlfbpQjc8gUe3c726qzPSgMUe9QB3fBA44e9iAJP/o0jtizgUd4MZHyWRbVAw1w==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "colors": "1.4.0",
+                "fs-extra": "^11.2.0",
+                "pug": "^3.0.3"
+            }
+        },
+        "node_modules/@jscpd/tokenizer": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/@jscpd/tokenizer/-/tokenizer-4.2.2.tgz",
+            "integrity": "sha512-haV7OWM2xzQ3I7tWgNTAOcR+kkFr0lYxkdnTOSd5Pve4QGx1Jk7kwk9gotqpXTd6AauaPnBdfHPxeZrUY21QYA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jscpd/core": "4.2.2",
+                "spark-md5": "^3.0.2"
+            }
+        },
         "node_modules/@napi-rs/wasm-runtime": {
             "version": "1.1.4",
             "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
@@ -1728,6 +1804,44 @@
                 "@emnapi/runtime": "^1.7.1"
             }
         },
+        "node_modules/@nodelib/fs.scandir": {
+            "version": "2.1.5",
+            "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
+            "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@nodelib/fs.stat": "2.0.5",
+                "run-parallel": "^1.1.9"
+            },
+            "engines": {
+                "node": ">= 8"
+            }
+        },
+        "node_modules/@nodelib/fs.stat": {
+            "version": "2.0.5",
+            "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz",
+            "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 8"
+            }
+        },
+        "node_modules/@nodelib/fs.walk": {
+            "version": "1.2.8",
+            "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz",
+            "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@nodelib/fs.scandir": "2.1.5",
+                "fastq": "^1.6.0"
+            },
+            "engines": {
+                "node": ">= 8"
+            }
+        },
         "node_modules/@oxc-project/types": {
             "version": "0.130.0",
             "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.130.0.tgz",
@@ -2248,6 +2362,26 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/@types/sarif": {
+            "version": "2.1.7",
+            "resolved": "https://registry.npmjs.org/@types/sarif/-/sarif-2.1.7.tgz",
+            "integrity": "sha512-kRz0VEkJqWLf1LLVN4pT1cg1Z9wAuvI6L97V3m2f5B76Tg8d413ddvLBPTEHAZJlnn4XSvu0FkZtViCQGVyrXQ==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/acorn": {
+            "version": "7.4.1",
+            "resolved": "https://registry.npmjs.org/acorn/-/acorn-7.4.1.tgz",
+            "integrity": "sha512-nQyp0o1/mNdbTO1PO6kHkwSrmgZ0MT/jCCpNiwbUjGoRN4dlBhqJtoQuCnEOKzgTVwg0ZWiCoQy6SxMebQVh8A==",
+            "dev": true,
+            "license": "MIT",
+            "bin": {
+                "acorn": "bin/acorn"
+            },
+            "engines": {
+                "node": ">=0.4.0"
+            }
+        },
         "node_modules/agent-base": {
             "version": "7.1.4",
             "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
@@ -2268,6 +2402,16 @@
                 "node": ">=6"
             }
         },
+        "node_modules/ansi-regex": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+            "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            }
+        },
         "node_modules/argparse": {
             "version": "2.0.1",
             "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
@@ -2275,6 +2419,20 @@
             "dev": true,
             "license": "Python-2.0"
         },
+        "node_modules/asap": {
+            "version": "2.0.6",
+            "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+            "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/assert-never": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/assert-never/-/assert-never-1.4.0.tgz",
+            "integrity": "sha512-5oJg84os6NMQNl27T9LnZkvvqzvAnHu03ShCnoj6bsJwS7L8AO4lf+C/XjK/nvzEqQB744moC6V128RucQd1jA==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/babel-plugin-transform-hook-names": {
             "version": "1.0.2",
             "resolved": "https://registry.npmjs.org/babel-plugin-transform-hook-names/-/babel-plugin-transform-hook-names-1.0.2.tgz",
@@ -2285,6 +2443,26 @@
                 "@babel/core": "^7.12.10"
             }
         },
+        "node_modules/babel-walk": {
+            "version": "3.0.0-canary-5",
+            "resolved": "https://registry.npmjs.org/babel-walk/-/babel-walk-3.0.0-canary-5.tgz",
+            "integrity": "sha512-GAwkz0AihzY5bkwIY5QDR+LvsRQgB/B+1foMPvi0FZPMl5fjD7ICiznUiBdLYMH1QYe6vqu4gWYytZOccLouFw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@babel/types": "^7.9.6"
+            },
+            "engines": {
+                "node": ">= 10.0.0"
+            }
+        },
+        "node_modules/badgen": {
+            "version": "3.3.2",
+            "resolved": "https://registry.npmjs.org/badgen/-/badgen-3.3.2.tgz",
+            "integrity": "sha512-fbQwK9norfdzbdsoPwbLIAmgBXDGEme3jeIyqPAH7o6vp9lmuLHS7uXULvOiQ6XnMLkYNG4gDjILf74hgtTAug==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/balanced-match": {
             "version": "1.0.2",
             "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
@@ -2312,6 +2490,20 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/blamer": {
+            "version": "1.0.7",
+            "resolved": "https://registry.npmjs.org/blamer/-/blamer-1.0.7.tgz",
+            "integrity": "sha512-GbBStl/EVlSWkiJQBZps3H1iARBrC7vt++Jb/TTmCNu/jZ04VW7tSN1nScbFXBUy1AN+jzeL7Zep9sbQxLhXKA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "execa": "^4.0.0",
+                "which": "^2.0.2"
+            },
+            "engines": {
+                "node": ">=8.9"
+            }
+        },
         "node_modules/boolbase": {
             "version": "1.0.0",
             "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
@@ -2329,6 +2521,19 @@
                 "balanced-match": "^1.0.0"
             }
         },
+        "node_modules/braces": {
+            "version": "3.0.3",
+            "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
+            "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "fill-range": "^7.1.1"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
         "node_modules/browserslist": {
             "version": "4.28.1",
             "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz",
@@ -2363,6 +2568,47 @@
                 "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
             }
         },
+        "node_modules/bytes": {
+            "version": "3.1.2",
+            "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
+            "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.8"
+            }
+        },
+        "node_modules/call-bind-apply-helpers": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+            "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "es-errors": "^1.3.0",
+                "function-bind": "^1.1.2"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/call-bound": {
+            "version": "1.0.4",
+            "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
+            "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "call-bind-apply-helpers": "^1.0.2",
+                "get-intrinsic": "^1.3.0"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
         "node_modules/caniuse-lite": {
             "version": "1.0.30001779",
             "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001779.tgz",
@@ -2391,6 +2637,32 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/character-parser": {
+            "version": "2.2.0",
+            "resolved": "https://registry.npmjs.org/character-parser/-/character-parser-2.2.0.tgz",
+            "integrity": "sha512-+UqJQjFEFaTAs3bNsF2j2kEN1baG/zghZbdqoYEDxGZtJo9LBzl1A+m0D4n3qKx8N2FNv8/Xp6yV9mQmBuptaw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "is-regex": "^1.0.3"
+            }
+        },
+        "node_modules/cli-table3": {
+            "version": "0.6.5",
+            "resolved": "https://registry.npmjs.org/cli-table3/-/cli-table3-0.6.5.tgz",
+            "integrity": "sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "string-width": "^4.2.0"
+            },
+            "engines": {
+                "node": "10.* || >= 12.*"
+            },
+            "optionalDependencies": {
+                "@colors/colors": "1.5.0"
+            }
+        },
         "node_modules/colorette": {
             "version": "1.4.0",
             "resolved": "https://registry.npmjs.org/colorette/-/colorette-1.4.0.tgz",
@@ -2398,6 +2670,37 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/colors": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz",
+            "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.1.90"
+            }
+        },
+        "node_modules/commander": {
+            "version": "5.1.0",
+            "resolved": "https://registry.npmjs.org/commander/-/commander-5.1.0.tgz",
+            "integrity": "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 6"
+            }
+        },
+        "node_modules/constantinople": {
+            "version": "4.0.1",
+            "resolved": "https://registry.npmjs.org/constantinople/-/constantinople-4.0.1.tgz",
+            "integrity": "sha512-vCrqcSIq4//Gx74TXXCGnHpulY1dskqLTFGDmhrGxzeXL8lF8kvXv6mpNWlJj1uD4DW23D4ljAqbY4RRaaUZIw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@babel/parser": "^7.6.0",
+                "@babel/types": "^7.6.1"
+            }
+        },
         "node_modules/convert-source-map": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -2419,6 +2722,21 @@
                 "url": "https://opencollective.com/express"
             }
         },
+        "node_modules/cross-spawn": {
+            "version": "7.0.6",
+            "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+            "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "path-key": "^3.1.0",
+                "shebang-command": "^2.0.0",
+                "which": "^2.0.1"
+            },
+            "engines": {
+                "node": ">= 8"
+            }
+        },
         "node_modules/css-select": {
             "version": "5.2.2",
             "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz",
@@ -2477,6 +2795,13 @@
                 "node": ">=8"
             }
         },
+        "node_modules/doctypes": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/doctypes/-/doctypes-1.1.0.tgz",
+            "integrity": "sha512-LLBi6pEqS6Do3EKQ3J0NqHWV5hhb78Pi8vvESYwyOy2c31ZEZVdtitdzsQsKb7878PEERhzUk0ftqGhG6Mz+pQ==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/dom-serializer": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
@@ -2536,6 +2861,21 @@
                 "url": "https://github.com/fb55/domutils?sponsor=1"
             }
         },
+        "node_modules/dunder-proto": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+            "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "call-bind-apply-helpers": "^1.0.1",
+                "es-errors": "^1.3.0",
+                "gopd": "^1.2.0"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
         "node_modules/electron-to-chromium": {
             "version": "1.5.313",
             "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.313.tgz",
@@ -2543,6 +2883,23 @@
             "dev": true,
             "license": "ISC"
         },
+        "node_modules/emoji-regex": {
+            "version": "8.0.0",
+            "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+            "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/end-of-stream": {
+            "version": "1.4.5",
+            "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+            "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "once": "^1.4.0"
+            }
+        },
         "node_modules/entities": {
             "version": "4.5.0",
             "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
@@ -2566,6 +2923,39 @@
                 "url": "https://github.com/sponsors/antfu"
             }
         },
+        "node_modules/es-define-property": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+            "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/es-errors": {
+            "version": "1.3.0",
+            "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+            "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/es-object-atoms": {
+            "version": "1.1.1",
+            "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
+            "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "es-errors": "^1.3.0"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
         "node_modules/esbuild": {
             "version": "0.27.3",
             "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
@@ -2625,6 +3015,37 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/eventemitter3": {
+            "version": "5.0.4",
+            "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
+            "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/execa": {
+            "version": "4.1.0",
+            "resolved": "https://registry.npmjs.org/execa/-/execa-4.1.0.tgz",
+            "integrity": "sha512-j5W0//W7f8UxAn8hXVnwG8tLwdiUy4FJLcSupCg6maBYZDpyBvTApK7KyuI4bKj8KOh1r2YH+6ucuYtJv1bTZA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "cross-spawn": "^7.0.0",
+                "get-stream": "^5.0.0",
+                "human-signals": "^1.1.1",
+                "is-stream": "^2.0.0",
+                "merge-stream": "^2.0.0",
+                "npm-run-path": "^4.0.0",
+                "onetime": "^5.1.0",
+                "signal-exit": "^3.0.2",
+                "strip-final-newline": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "funding": {
+                "url": "https://github.com/sindresorhus/execa?sponsor=1"
+            }
+        },
         "node_modules/fast-deep-equal": {
             "version": "3.1.3",
             "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -2632,6 +3053,33 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/fast-glob": {
+            "version": "3.3.3",
+            "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz",
+            "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@nodelib/fs.stat": "^2.0.2",
+                "@nodelib/fs.walk": "^1.2.3",
+                "glob-parent": "^5.1.2",
+                "merge2": "^1.3.0",
+                "micromatch": "^4.0.8"
+            },
+            "engines": {
+                "node": ">=8.6.0"
+            }
+        },
+        "node_modules/fastq": {
+            "version": "1.20.1",
+            "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz",
+            "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "reusify": "^1.0.4"
+            }
+        },
         "node_modules/fdir": {
             "version": "6.5.0",
             "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -2650,6 +3098,34 @@
                 }
             }
         },
+        "node_modules/fill-range": {
+            "version": "7.1.1",
+            "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
+            "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "to-regex-range": "^5.0.1"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/fs-extra": {
+            "version": "11.3.5",
+            "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.5.tgz",
+            "integrity": "sha512-eKpRKAovdpZtR1WopLHxlBWvAgPny3c4gX1G5Jhwmmw4XJj0ifSD5qB5TOo8hmA0wlRKDAOAhEE1yVPgs6Fgcg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "graceful-fs": "^4.2.0",
+                "jsonfile": "^6.0.1",
+                "universalify": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=14.14"
+            }
+        },
         "node_modules/fsevents": {
             "version": "2.3.3",
             "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -2665,6 +3141,16 @@
                 "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
             }
         },
+        "node_modules/function-bind": {
+            "version": "1.1.2",
+            "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+            "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
         "node_modules/gensync": {
             "version": "1.0.0-beta.2",
             "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
@@ -2675,15 +3161,145 @@
                 "node": ">=6.9.0"
             }
         },
-        "node_modules/he": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz",
-            "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==",
+        "node_modules/get-intrinsic": {
+            "version": "1.3.0",
+            "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+            "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
             "dev": true,
             "license": "MIT",
-            "bin": {
-                "he": "bin/he"
-            }
+            "dependencies": {
+                "call-bind-apply-helpers": "^1.0.2",
+                "es-define-property": "^1.0.1",
+                "es-errors": "^1.3.0",
+                "es-object-atoms": "^1.1.1",
+                "function-bind": "^1.1.2",
+                "get-proto": "^1.0.1",
+                "gopd": "^1.2.0",
+                "has-symbols": "^1.1.0",
+                "hasown": "^2.0.2",
+                "math-intrinsics": "^1.1.0"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/get-proto": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+            "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "dunder-proto": "^1.0.1",
+                "es-object-atoms": "^1.0.0"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/get-stream": {
+            "version": "5.2.0",
+            "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
+            "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pump": "^3.0.0"
+            },
+            "engines": {
+                "node": ">=8"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/glob-parent": {
+            "version": "5.1.2",
+            "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+            "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "is-glob": "^4.0.1"
+            },
+            "engines": {
+                "node": ">= 6"
+            }
+        },
+        "node_modules/gopd": {
+            "version": "1.2.0",
+            "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+            "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/graceful-fs": {
+            "version": "4.2.11",
+            "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
+            "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
+            "dev": true,
+            "license": "ISC"
+        },
+        "node_modules/has-symbols": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+            "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/has-tostringtag": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+            "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "has-symbols": "^1.0.3"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/hasown": {
+            "version": "2.0.3",
+            "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
+            "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "function-bind": "^1.1.2"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/he": {
+            "version": "1.2.0",
+            "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz",
+            "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==",
+            "dev": true,
+            "license": "MIT",
+            "bin": {
+                "he": "bin/he"
+            }
         },
         "node_modules/https-proxy-agent": {
             "version": "7.0.6",
@@ -2699,6 +3315,16 @@
                 "node": ">= 14"
             }
         },
+        "node_modules/human-signals": {
+            "version": "1.1.1",
+            "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-1.1.1.tgz",
+            "integrity": "sha512-SEQu7vl8KjNL2eoGBLF3+wAjpsNfA9XMlXAYj/3EdaNfAlxKthD1xjEQfGOUhllCGGJVNY34bRr6lPINhNjyZw==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=8.12.0"
+            }
+        },
         "node_modules/index-to-position": {
             "version": "1.2.0",
             "resolved": "https://registry.npmjs.org/index-to-position/-/index-to-position-1.2.0.tgz",
@@ -2712,6 +3338,122 @@
                 "url": "https://github.com/sponsors/sindresorhus"
             }
         },
+        "node_modules/is-core-module": {
+            "version": "2.16.2",
+            "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.16.2.tgz",
+            "integrity": "sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "hasown": "^2.0.3"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/is-expression": {
+            "version": "4.0.0",
+            "resolved": "https://registry.npmjs.org/is-expression/-/is-expression-4.0.0.tgz",
+            "integrity": "sha512-zMIXX63sxzG3XrkHkrAPvm/OVZVSCPNkwMHU8oTX7/U3AL78I0QXCEICXUM13BIa8TYGZ68PiTKfQz3yaTNr4A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "acorn": "^7.1.1",
+                "object-assign": "^4.1.1"
+            }
+        },
+        "node_modules/is-extglob": {
+            "version": "2.1.1",
+            "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+            "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/is-fullwidth-code-point": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+            "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/is-glob": {
+            "version": "4.0.3",
+            "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+            "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "is-extglob": "^2.1.1"
+            },
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/is-number": {
+            "version": "7.0.0",
+            "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
+            "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.12.0"
+            }
+        },
+        "node_modules/is-promise": {
+            "version": "2.2.2",
+            "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-2.2.2.tgz",
+            "integrity": "sha512-+lP4/6lKUBfQjZ2pdxThZvLUAafmZb8OAxFb8XXtiQmS35INgr85hdOGoEs124ez1FCnZJt6jau/T+alh58QFQ==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/is-regex": {
+            "version": "1.2.1",
+            "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.2.1.tgz",
+            "integrity": "sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "call-bound": "^1.0.2",
+                "gopd": "^1.2.0",
+                "has-tostringtag": "^1.0.2",
+                "hasown": "^2.0.2"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/is-stream": {
+            "version": "2.0.1",
+            "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
+            "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/isexe": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+            "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+            "dev": true,
+            "license": "ISC"
+        },
         "node_modules/js-levenshtein": {
             "version": "1.1.6",
             "resolved": "https://registry.npmjs.org/js-levenshtein/-/js-levenshtein-1.1.6.tgz",
@@ -2722,6 +3464,13 @@
                 "node": ">=0.10.0"
             }
         },
+        "node_modules/js-stringify": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/js-stringify/-/js-stringify-1.0.2.tgz",
+            "integrity": "sha512-rtS5ATOo2Q5k1G+DADISilDA6lv79zIiwFd6CcjuIxGKLFm5C+RLImRscVap9k55i+MOZwgliw+NejvkLuGD5g==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/js-tokens": {
             "version": "4.0.0",
             "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -2742,6 +3491,39 @@
                 "js-yaml": "bin/js-yaml.js"
             }
         },
+        "node_modules/jscpd": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/jscpd/-/jscpd-4.2.2.tgz",
+            "integrity": "sha512-zmoSXtG5Dsgo3QHhnsA06okqnKu3DlYBeAuD7MRnNQoNiL13UgBBh28pEEhe0tyR4yqYXk4Q3GAFoHx5cY+oDw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jscpd/badge-reporter": "4.2.2",
+                "@jscpd/core": "4.2.2",
+                "@jscpd/finder": "4.2.2",
+                "@jscpd/html-reporter": "4.2.2",
+                "@jscpd/tokenizer": "4.2.2",
+                "colors": "^1.4.0",
+                "commander": "^5.0.0",
+                "fs-extra": "^11.2.0",
+                "jscpd-sarif-reporter": "4.2.2"
+            },
+            "bin": {
+                "jscpd": "bin/jscpd"
+            }
+        },
+        "node_modules/jscpd-sarif-reporter": {
+            "version": "4.2.2",
+            "resolved": "https://registry.npmjs.org/jscpd-sarif-reporter/-/jscpd-sarif-reporter-4.2.2.tgz",
+            "integrity": "sha512-qpLhFZ6pVJcIjvEcUVRxnsrQuTbRY7bBnAgzXY9th0mL1uYhb1ii+SkMcBrBchH23vFfZu/9EG4lIxLCGfEpCQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "colors": "^1.4.0",
+                "fs-extra": "^11.2.0",
+                "node-sarif-builder": "^3.4.0"
+            }
+        },
         "node_modules/jsesc": {
             "version": "3.1.0",
             "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -2775,6 +3557,30 @@
                 "node": ">=6"
             }
         },
+        "node_modules/jsonfile": {
+            "version": "6.2.1",
+            "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
+            "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "universalify": "^2.0.0"
+            },
+            "optionalDependencies": {
+                "graceful-fs": "^4.1.6"
+            }
+        },
+        "node_modules/jstransformer": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/jstransformer/-/jstransformer-1.0.0.tgz",
+            "integrity": "sha512-C9YK3Rf8q6VAPDCCU9fnqo3mAfOH6vUGnMcP4AQAYIEpWtfGLpwOTmZ+igtdK5y+VvI2n3CyYSzy4Qh34eq24A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "is-promise": "^2.0.0",
+                "promise": "^7.0.1"
+            }
+        },
         "node_modules/kleur": {
             "version": "4.1.5",
             "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
@@ -3085,6 +3891,84 @@
                 "@jridgewell/sourcemap-codec": "^1.5.5"
             }
         },
+        "node_modules/markdown-table": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-2.0.0.tgz",
+            "integrity": "sha512-Ezda85ToJUBhM6WGaG6veasyym+Tbs3cMAw/ZhOPqXiYsr0jgocBV3j3nx+4lk47plLlIqjwuTm/ywVI+zjJ/A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "repeat-string": "^1.0.0"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/wooorm"
+            }
+        },
+        "node_modules/math-intrinsics": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+            "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            }
+        },
+        "node_modules/merge-stream": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
+            "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/merge2": {
+            "version": "1.4.1",
+            "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
+            "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 8"
+            }
+        },
+        "node_modules/micromatch": {
+            "version": "4.0.8",
+            "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
+            "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "braces": "^3.0.3",
+                "picomatch": "^2.3.1"
+            },
+            "engines": {
+                "node": ">=8.6"
+            }
+        },
+        "node_modules/micromatch/node_modules/picomatch": {
+            "version": "2.3.2",
+            "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+            "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8.6"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/jonschlinkert"
+            }
+        },
+        "node_modules/mimic-fn": {
+            "version": "2.1.0",
+            "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
+            "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
         "node_modules/miniflare": {
             "version": "4.20260515.0",
             "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260515.0.tgz",
@@ -3163,6 +4047,33 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/node-sarif-builder": {
+            "version": "3.4.0",
+            "resolved": "https://registry.npmjs.org/node-sarif-builder/-/node-sarif-builder-3.4.0.tgz",
+            "integrity": "sha512-tGnJW6OKRii9u/b2WiUViTJS+h7Apxx17qsMUjsUeNDiMMX5ZFf8F8Fcz7PAQ6omvOxHZtvDTmOYKJQwmfpjeg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@types/sarif": "^2.1.7",
+                "fs-extra": "^11.1.1"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/npm-run-path": {
+            "version": "4.0.1",
+            "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz",
+            "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "path-key": "^3.0.0"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
         "node_modules/nth-check": {
             "version": "2.1.1",
             "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz",
@@ -3176,6 +4087,42 @@
                 "url": "https://github.com/fb55/nth-check?sponsor=1"
             }
         },
+        "node_modules/object-assign": {
+            "version": "4.1.1",
+            "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+            "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/once": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+            "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "wrappy": "1"
+            }
+        },
+        "node_modules/onetime": {
+            "version": "5.1.2",
+            "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
+            "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "mimic-fn": "^2.1.0"
+            },
+            "engines": {
+                "node": ">=6"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/openapi-typescript": {
             "version": "7.13.0",
             "resolved": "https://registry.npmjs.org/openapi-typescript/-/openapi-typescript-7.13.0.tgz",
@@ -3215,6 +4162,23 @@
                 "url": "https://github.com/sponsors/sindresorhus"
             }
         },
+        "node_modules/path-key": {
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+            "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/path-parse": {
+            "version": "1.0.7",
+            "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz",
+            "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/path-to-regexp": {
             "version": "6.3.0",
             "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz",
@@ -3298,6 +4262,194 @@
                 "url": "https://opencollective.com/preact"
             }
         },
+        "node_modules/promise": {
+            "version": "7.3.1",
+            "resolved": "https://registry.npmjs.org/promise/-/promise-7.3.1.tgz",
+            "integrity": "sha512-nolQXZ/4L+bP/UGlkfaIujX9BKxGwmQ9OT4mOt5yvy8iK1h3wqTEJCijzGANTCCl9nWjY41juyAn2K3Q1hLLTg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "asap": "~2.0.3"
+            }
+        },
+        "node_modules/pug": {
+            "version": "3.0.4",
+            "resolved": "https://registry.npmjs.org/pug/-/pug-3.0.4.tgz",
+            "integrity": "sha512-kFfq5mMzrS7+wrl5pLJzZEzemx34OQ0w4SARfhy/3yxTlhbstsudDwJzhf1hP02yHzbjoVMSXUj/Sz6RNfMyXg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pug-code-gen": "^3.0.4",
+                "pug-filters": "^4.0.0",
+                "pug-lexer": "^5.0.1",
+                "pug-linker": "^4.0.0",
+                "pug-load": "^3.0.0",
+                "pug-parser": "^6.0.0",
+                "pug-runtime": "^3.0.1",
+                "pug-strip-comments": "^2.0.0"
+            }
+        },
+        "node_modules/pug-attrs": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/pug-attrs/-/pug-attrs-3.0.0.tgz",
+            "integrity": "sha512-azINV9dUtzPMFQktvTXciNAfAuVh/L/JCl0vtPCwvOA21uZrC08K/UnmrL+SXGEVc1FwzjW62+xw5S/uaLj6cA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "constantinople": "^4.0.1",
+                "js-stringify": "^1.0.2",
+                "pug-runtime": "^3.0.0"
+            }
+        },
+        "node_modules/pug-code-gen": {
+            "version": "3.0.4",
+            "resolved": "https://registry.npmjs.org/pug-code-gen/-/pug-code-gen-3.0.4.tgz",
+            "integrity": "sha512-6okWYIKdasTyXICyEtvobmTZAVX57JkzgzIi4iRJlin8kmhG+Xry2dsus+Mun/nGCn6F2U49haHI5mkELXB14g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "constantinople": "^4.0.1",
+                "doctypes": "^1.1.0",
+                "js-stringify": "^1.0.2",
+                "pug-attrs": "^3.0.0",
+                "pug-error": "^2.1.0",
+                "pug-runtime": "^3.0.1",
+                "void-elements": "^3.1.0",
+                "with": "^7.0.0"
+            }
+        },
+        "node_modules/pug-error": {
+            "version": "2.1.0",
+            "resolved": "https://registry.npmjs.org/pug-error/-/pug-error-2.1.0.tgz",
+            "integrity": "sha512-lv7sU9e5Jk8IeUheHata6/UThZ7RK2jnaaNztxfPYUY+VxZyk/ePVaNZ/vwmH8WqGvDz3LrNYt/+gA55NDg6Pg==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/pug-filters": {
+            "version": "4.0.0",
+            "resolved": "https://registry.npmjs.org/pug-filters/-/pug-filters-4.0.0.tgz",
+            "integrity": "sha512-yeNFtq5Yxmfz0f9z2rMXGw/8/4i1cCFecw/Q7+D0V2DdtII5UvqE12VaZ2AY7ri6o5RNXiweGH79OCq+2RQU4A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "constantinople": "^4.0.1",
+                "jstransformer": "1.0.0",
+                "pug-error": "^2.0.0",
+                "pug-walk": "^2.0.0",
+                "resolve": "^1.15.1"
+            }
+        },
+        "node_modules/pug-lexer": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/pug-lexer/-/pug-lexer-5.0.1.tgz",
+            "integrity": "sha512-0I6C62+keXlZPZkOJeVam9aBLVP2EnbeDw3An+k0/QlqdwH6rv8284nko14Na7c0TtqtogfWXcRoFE4O4Ff20w==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "character-parser": "^2.2.0",
+                "is-expression": "^4.0.0",
+                "pug-error": "^2.0.0"
+            }
+        },
+        "node_modules/pug-linker": {
+            "version": "4.0.0",
+            "resolved": "https://registry.npmjs.org/pug-linker/-/pug-linker-4.0.0.tgz",
+            "integrity": "sha512-gjD1yzp0yxbQqnzBAdlhbgoJL5qIFJw78juN1NpTLt/mfPJ5VgC4BvkoD3G23qKzJtIIXBbcCt6FioLSFLOHdw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pug-error": "^2.0.0",
+                "pug-walk": "^2.0.0"
+            }
+        },
+        "node_modules/pug-load": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/pug-load/-/pug-load-3.0.0.tgz",
+            "integrity": "sha512-OCjTEnhLWZBvS4zni/WUMjH2YSUosnsmjGBB1An7CsKQarYSWQ0GCVyd4eQPMFJqZ8w9xgs01QdiZXKVjk92EQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "object-assign": "^4.1.1",
+                "pug-walk": "^2.0.0"
+            }
+        },
+        "node_modules/pug-parser": {
+            "version": "6.0.0",
+            "resolved": "https://registry.npmjs.org/pug-parser/-/pug-parser-6.0.0.tgz",
+            "integrity": "sha512-ukiYM/9cH6Cml+AOl5kETtM9NR3WulyVP2y4HOU45DyMim1IeP/OOiyEWRr6qk5I5klpsBnbuHpwKmTx6WURnw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pug-error": "^2.0.0",
+                "token-stream": "1.0.0"
+            }
+        },
+        "node_modules/pug-runtime": {
+            "version": "3.0.1",
+            "resolved": "https://registry.npmjs.org/pug-runtime/-/pug-runtime-3.0.1.tgz",
+            "integrity": "sha512-L50zbvrQ35TkpHwv0G6aLSuueDRwc/97XdY8kL3tOT0FmhgG7UypU3VztfV/LATAvmUfYi4wNxSajhSAeNN+Kg==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/pug-strip-comments": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/pug-strip-comments/-/pug-strip-comments-2.0.0.tgz",
+            "integrity": "sha512-zo8DsDpH7eTkPHCXFeAk1xZXJbyoTfdPlNR0bK7rpOMuhBYb0f5qUVCO1xlsitYd3w5FQTK7zpNVKb3rZoUrrQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "pug-error": "^2.0.0"
+            }
+        },
+        "node_modules/pug-walk": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/pug-walk/-/pug-walk-2.0.0.tgz",
+            "integrity": "sha512-yYELe9Q5q9IQhuvqsZNwA5hfPkMJ8u92bQLIMcsMxf/VADjNtEYptU+inlufAFYcWdHlwNfZOEnOOQrZrcyJCQ==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/pump": {
+            "version": "3.0.4",
+            "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+            "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "end-of-stream": "^1.1.0",
+                "once": "^1.3.1"
+            }
+        },
+        "node_modules/queue-microtask": {
+            "version": "1.2.3",
+            "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
+            "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==",
+            "dev": true,
+            "funding": [
+                {
+                    "type": "github",
+                    "url": "https://github.com/sponsors/feross"
+                },
+                {
+                    "type": "patreon",
+                    "url": "https://www.patreon.com/feross"
+                },
+                {
+                    "type": "consulting",
+                    "url": "https://feross.org/support"
+                }
+            ],
+            "license": "MIT"
+        },
+        "node_modules/repeat-string": {
+            "version": "1.6.1",
+            "resolved": "https://registry.npmjs.org/repeat-string/-/repeat-string-1.6.1.tgz",
+            "integrity": "sha512-PV0dzCYDNfRi1jCDbJzpW7jNNDRuCOG/jI5ctQcGKt/clZD+YcPS3yIlWuTJMmESC8aevCFmWJy5wjAFgNqN6w==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10"
+            }
+        },
         "node_modules/require-from-string": {
             "version": "2.0.2",
             "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
@@ -3308,6 +4460,39 @@
                 "node": ">=0.10.0"
             }
         },
+        "node_modules/resolve": {
+            "version": "1.22.12",
+            "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.12.tgz",
+            "integrity": "sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "es-errors": "^1.3.0",
+                "is-core-module": "^2.16.1",
+                "path-parse": "^1.0.7",
+                "supports-preserve-symlinks-flag": "^1.0.0"
+            },
+            "bin": {
+                "resolve": "bin/resolve"
+            },
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
+        "node_modules/reusify": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
+            "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "iojs": ">=1.0.0",
+                "node": ">=0.10.0"
+            }
+        },
         "node_modules/rolldown": {
             "version": "1.0.1",
             "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.1.tgz",
@@ -3342,6 +4527,30 @@
                 "@rolldown/binding-win32-x64-msvc": "1.0.1"
             }
         },
+        "node_modules/run-parallel": {
+            "version": "1.2.0",
+            "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
+            "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==",
+            "dev": true,
+            "funding": [
+                {
+                    "type": "github",
+                    "url": "https://github.com/sponsors/feross"
+                },
+                {
+                    "type": "patreon",
+                    "url": "https://www.patreon.com/feross"
+                },
+                {
+                    "type": "consulting",
+                    "url": "https://feross.org/support"
+                }
+            ],
+            "license": "MIT",
+            "dependencies": {
+                "queue-microtask": "^1.2.2"
+            }
+        },
         "node_modules/semver": {
             "version": "6.3.1",
             "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
@@ -3410,6 +4619,36 @@
                 "node": ">=10"
             }
         },
+        "node_modules/shebang-command": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+            "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "shebang-regex": "^3.0.0"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/shebang-regex": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+            "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/signal-exit": {
+            "version": "3.0.7",
+            "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+            "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+            "dev": true,
+            "license": "ISC"
+        },
         "node_modules/simple-code-frame": {
             "version": "1.3.0",
             "resolved": "https://registry.npmjs.org/simple-code-frame/-/simple-code-frame-1.3.0.tgz",
@@ -3440,6 +4679,13 @@
                 "node": ">=0.10.0"
             }
         },
+        "node_modules/spark-md5": {
+            "version": "3.0.2",
+            "resolved": "https://registry.npmjs.org/spark-md5/-/spark-md5-3.0.2.tgz",
+            "integrity": "sha512-wcFzz9cDfbuqe0FZzfi2or1sgyIrsDwmPwfZC4hiNidPdPINjeUwNfv5kldczoEAcjl9Y1L3SM7Uz2PUEQzxQw==",
+            "dev": true,
+            "license": "(WTFPL OR MIT)"
+        },
         "node_modules/stack-trace": {
             "version": "1.0.0-pre2",
             "resolved": "https://registry.npmjs.org/stack-trace/-/stack-trace-1.0.0-pre2.tgz",
@@ -3450,6 +4696,44 @@
                 "node": ">=16"
             }
         },
+        "node_modules/string-width": {
+            "version": "4.2.3",
+            "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+            "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "emoji-regex": "^8.0.0",
+                "is-fullwidth-code-point": "^3.0.0",
+                "strip-ansi": "^6.0.1"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/strip-ansi": {
+            "version": "6.0.1",
+            "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+            "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "ansi-regex": "^5.0.1"
+            },
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/strip-final-newline": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz",
+            "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
         "node_modules/supports-color": {
             "version": "10.2.2",
             "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz",
@@ -3463,6 +4747,19 @@
                 "url": "https://github.com/chalk/supports-color?sponsor=1"
             }
         },
+        "node_modules/supports-preserve-symlinks-flag": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz",
+            "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 0.4"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/ljharb"
+            }
+        },
         "node_modules/tinyglobby": {
             "version": "0.2.16",
             "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
@@ -3480,6 +4777,26 @@
                 "url": "https://github.com/sponsors/SuperchupuDev"
             }
         },
+        "node_modules/to-regex-range": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
+            "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "is-number": "^7.0.0"
+            },
+            "engines": {
+                "node": ">=8.0"
+            }
+        },
+        "node_modules/token-stream": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/token-stream/-/token-stream-1.0.0.tgz",
+            "integrity": "sha512-VSsyNPPW74RpHwR8Fc21uubwHY7wMDeJLys2IX5zJNih+OnAnaifKHo+1LHT7DAdloQ7apeaaWg8l7qnf/TnEg==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/tslib": {
             "version": "2.8.1",
             "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
@@ -3535,6 +4852,16 @@
                 "pathe": "^2.0.3"
             }
         },
+        "node_modules/universalify": {
+            "version": "2.0.1",
+            "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
+            "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">= 10.0.0"
+            }
+        },
         "node_modules/update-browserslist-db": {
             "version": "1.2.3",
             "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -3669,6 +4996,48 @@
                 "vite": "5.x || 6.x || 7.x || 8.x"
             }
         },
+        "node_modules/void-elements": {
+            "version": "3.1.0",
+            "resolved": "https://registry.npmjs.org/void-elements/-/void-elements-3.1.0.tgz",
+            "integrity": "sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/which": {
+            "version": "2.0.2",
+            "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+            "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+            "dev": true,
+            "license": "ISC",
+            "dependencies": {
+                "isexe": "^2.0.0"
+            },
+            "bin": {
+                "node-which": "bin/node-which"
+            },
+            "engines": {
+                "node": ">= 8"
+            }
+        },
+        "node_modules/with": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/with/-/with-7.0.2.tgz",
+            "integrity": "sha512-RNGKj82nUPg3g5ygxkQl0R937xLyho1J24ItRCBTr/m1YnZkzJy1hUiHUJrc/VlsDQzsCnInEGSg3bci0Lmd4w==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@babel/parser": "^7.9.6",
+                "@babel/types": "^7.9.6",
+                "assert-never": "^1.2.1",
+                "babel-walk": "3.0.0-canary-5"
+            },
+            "engines": {
+                "node": ">= 10.0.0"
+            }
+        },
         "node_modules/workerd": {
             "version": "1.20260515.1",
             "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260515.1.tgz",
@@ -3725,6 +5094,13 @@
                 }
             }
         },
+        "node_modules/wrappy": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+            "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+            "dev": true,
+            "license": "ISC"
+        },
         "node_modules/ws": {
             "version": "8.18.0",
             "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.0.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 4c94bdd..f106820 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,10 +6,11 @@
     "scripts": {
         "dev": "npm run gen:types && vite",
         "gen:types": "openapi-typescript --root-types --root-types-no-schema-prefix --output src/types.generated.ts api/openapi.yaml",
-        "build:demo": "node scripts/write_demo_build_info.js && biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build --mode demo",
-        "build": "biome check && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build && node scripts/embed_frontend.js",
+        "build:demo": "node scripts/write_demo_build_info.js && biome check && jscpd src/ && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build --mode demo",
+        "build": "biome check && jscpd src/ && npm run gen:types && node scripts/check_api_paths.js && tsc --noEmit && vite build && node scripts/embed_frontend.js",
         "preview": "vite preview",
         "check": "biome check",
+        "dupes": "jscpd src/",
         "fix": "biome check --write",
         "fix:unsafe": "biome check --write --unsafe"
     },
@@ -19,6 +20,7 @@
     "devDependencies": {
         "@biomejs/biome": "2.4.15",
         "@preact/preset-vite": "2.10.5",
+        "jscpd": "4.2.2",
         "openapi-typescript": "7.13.0",
         "typescript": "6.0.3",
         "vite": "8.0.13",
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index e19621f..5385710 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -83,10 +83,10 @@ async function fetchSessionData(filename: string): Promise<MapData[]> {
     return parseMapData(raw);
 }
 
-function importSession(file: File, onProgress: (pct: number) => void): Promise<void> {
+function uploadFile(url: string, file: File, onProgress: (pct: number) => void): Promise<void> {
     return new Promise((resolve, reject) => {
         const xhr = new XMLHttpRequest();
-        xhr.open("POST", "/api/history/import");
+        xhr.open("POST", url);
         xhr.upload.addEventListener("progress", (e) => {
             if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
         });
@@ -110,31 +110,12 @@ function importSession(file: File, onProgress: (pct: number) => void): Promise<v
     });
 }
 
+function importSession(file: File, onProgress: (pct: number) => void): Promise<void> {
+    return uploadFile("/api/history/import", file, onProgress);
+}
+
 function uploadFirmware(file: File, md5: string, onProgress: (pct: number) => void): Promise<void> {
-    return new Promise((resolve, reject) => {
-        const xhr = new XMLHttpRequest();
-        xhr.open("POST", `/api/firmware/update?hash=${md5}`);
-        xhr.upload.addEventListener("progress", (e) => {
-            if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
-        });
-        xhr.addEventListener("load", () => {
-            if (xhr.status >= 200 && xhr.status < 300) {
-                resolve();
-            } else {
-                try {
-                    const data = JSON.parse(xhr.responseText);
-                    reject(new Error(data.error || `${xhr.status} ${xhr.statusText}`));
-                } catch {
-                    reject(new Error(`${xhr.status} ${xhr.statusText}`));
-                }
-            }
-        });
-        xhr.addEventListener("error", () => reject(new Error("Network error during upload")));
-        xhr.addEventListener("abort", () => reject(new Error("Upload aborted")));
-        const form = new FormData();
-        form.append("file", file);
-        xhr.send(form);
-    });
+    return uploadFile(`/api/firmware/update?hash=${md5}`, file, onProgress);
 }
 
 export const api = {
diff --git a/frontend/src/hooks/use-poll.ts b/frontend/src/hooks/use-poll.ts
new file mode 100644
index 0000000..73ce271
--- /dev/null
+++ b/frontend/src/hooks/use-poll.ts
@@ -0,0 +1,57 @@
+import { useEffect, useRef } from "preact/hooks";
+
+// Non-overlapping poll loop with visibility awareness.
+// When enabled, calls callback(), waits at least intervalMs after it
+// completes, then repeats. Pauses when the tab is hidden and resumes
+// immediately on return. Never overlaps requests.
+export function usePoll(callback: () => Promise<void>, intervalMs: number, enabled: boolean, initialDelayMs = 0): void {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+
+    useEffect(() => {
+        if (!enabled) return;
+
+        let active = true;
+        let timer: ReturnType<typeof setTimeout>;
+        let polling = false;
+
+        const poll = async () => {
+            if (document.hidden) return;
+            polling = true;
+            const start = Date.now();
+            try {
+                await callbackRef.current();
+            } catch {
+                // Silently ignore poll errors
+            }
+            polling = false;
+            if (active && !document.hidden) {
+                const elapsed = Date.now() - start;
+                const delay = Math.max(0, intervalMs - elapsed);
+                timer = setTimeout(poll, delay);
+            }
+        };
+
+        const onVisibilityChange = () => {
+            if (!active) return;
+            if (document.hidden) {
+                clearTimeout(timer);
+            } else if (!polling) {
+                poll();
+            }
+        };
+
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        if (initialDelayMs > 0) {
+            timer = setTimeout(poll, initialDelayMs);
+        } else {
+            poll();
+        }
+
+        return () => {
+            active = false;
+            clearTimeout(timer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [intervalMs, enabled, initialDelayMs]);
+}
diff --git a/frontend/src/views/history.tsx b/frontend/src/views/history.tsx
index 9294af9..1928308 100644
--- a/frontend/src/views/history.tsx
+++ b/frontend/src/views/history.tsx
@@ -5,6 +5,7 @@ import { ConfirmDialog } from "../components/confirm-dialog";
 import { ErrorBannerStack, useErrorStack } from "../components/error-banner";
 import { Icon } from "../components/icon";
 import { useNavigate, usePath } from "../components/router";
+import { usePoll } from "../hooks/use-poll";
 import type { HistoryFileInfo, MapData } from "../types";
 import { normalizeError } from "../utils";
 import { HistoryItemView } from "./history/item";
@@ -58,27 +59,22 @@ export function HistoryView() {
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
     // Poll list + active recording session map (every 5s while recording)
-    useEffect(() => {
-        if (!hasRecording) return;
-        const interval = setInterval(async () => {
-            try {
-                const fileList = await api.getHistoryList();
-                setFiles(sortByDateDesc(fileList));
+    usePoll(
+        async () => {
+            const fileList = await api.getHistoryList();
+            setFiles(sortByDateDesc(fileList));
 
-                // If the detail view shows the recording session, refresh its map
-                if (selectedName) {
-                    const file = fileList.find((f) => f.name === selectedName);
-                    if (file?.recording) {
-                        const maps = await api.getHistorySession(file.name);
-                        if (maps.length > 0) setSelectedMap(maps[0]);
-                    }
+            if (selectedName) {
+                const file = fileList.find((f) => f.name === selectedName);
+                if (file?.recording) {
+                    const maps = await api.getHistorySession(file.name);
+                    if (maps.length > 0) setSelectedMap(maps[0]);
                 }
-            } catch {
-                // Silently ignore poll errors
             }
-        }, 5000);
-        return () => clearInterval(interval);
-    }, [hasRecording, selectedName]);
+        },
+        5000,
+        hasRecording,
+    );
 
     // Fetch full session data when URL points to a file
     useEffect(() => {
diff --git a/frontend/src/views/settings.tsx b/frontend/src/views/settings.tsx
index accfef5..841e68f 100644
--- a/frontend/src/views/settings.tsx
+++ b/frontend/src/views/settings.tsx
@@ -24,6 +24,7 @@ import { ErrorBannerStack, useErrorStack } from "../components/error-banner";
 import { Icon } from "../components/icon";
 import { useNavigate } from "../components/router";
 import { useDirtyGuard } from "../hooks/use-dirty-guard";
+import { usePoll } from "../hooks/use-poll";
 import { usePolling } from "../hooks/use-polling";
 import type { FirmwareVersion, SystemData, UserSettingsData } from "../types";
 import { normalizeError } from "../utils";
@@ -194,43 +195,39 @@ export function SettingsView({ theme, onThemeChange, firmware }: SettingsViewPro
     const [showRobotRestartConfirm, setShowRobotRestartConfirm] = useState(false);
     const [showRobotShutdownConfirm, setShowRobotShutdownConfirm] = useState(false);
     const [robotRestarting, setRobotRestarting] = useState(false);
-    const robotRestartPollTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const [robotRestartPolling, setRobotRestartPolling] = useState(false);
     const robotRestartTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
 
     useEffect(() => {
         return () => {
-            if (robotRestartPollTimer.current) clearTimeout(robotRestartPollTimer.current);
             if (robotRestartTimeout.current) clearTimeout(robotRestartTimeout.current);
         };
     }, []);
 
+    usePoll(
+        async () => {
+            await api.getState();
+            if (robotRestartTimeout.current) clearTimeout(robotRestartTimeout.current);
+            robotRestartTimeout.current = null;
+            setRobotRestarting(false);
+            setRobotRestartPolling(false);
+        },
+        2000,
+        robotRestartPolling,
+        2000,
+    );
+
     const handleRobotRestart = useCallback(() => {
         setRobotRestarting(true);
 
         robotRestartTimeout.current = setTimeout(() => {
-            if (robotRestartPollTimer.current) clearTimeout(robotRestartPollTimer.current);
-            robotRestartPollTimer.current = null;
-            robotRestartTimeout.current = null;
+            setRobotRestartPolling(false);
             setRobotRestarting(false);
             errorStack.push("Robot did not recover after restart — check physical connection");
         }, 30000);
 
         api.robotRestart()
-            .then(() => {
-                const poll = () => {
-                    api.getState()
-                        .then(() => {
-                            if (robotRestartTimeout.current) clearTimeout(robotRestartTimeout.current);
-                            robotRestartTimeout.current = null;
-                            robotRestartPollTimer.current = null;
-                            setRobotRestarting(false);
-                        })
-                        .catch(() => {
-                            robotRestartPollTimer.current = setTimeout(poll, 2000);
-                        });
-                };
-                robotRestartPollTimer.current = setTimeout(poll, 2000);
-            })
+            .then(() => setRobotRestartPolling(true))
             .catch((e: unknown) => {
                 if (robotRestartTimeout.current) clearTimeout(robotRestartTimeout.current);
                 robotRestartTimeout.current = null;
diff --git a/frontend/src/views/settings/use-reboot.ts b/frontend/src/views/settings/use-reboot.ts
index d2cb3ad..76a4398 100644
--- a/frontend/src/views/settings/use-reboot.ts
+++ b/frontend/src/views/settings/use-reboot.ts
@@ -1,40 +1,29 @@
-import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import { useCallback, useRef, useState } from "preact/hooks";
+import { usePoll } from "../../hooks/use-poll";
 import type { SystemData } from "../../types";
 
 export function useReboot(currentUptime: number) {
     const [rebooting, setRebooting] = useState(false);
-    const pollTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
     const uptimeBeforeReboot = useRef(0);
 
-    const pollUntilRebooted = useCallback(() => {
-        const poll = () => {
-            fetch("/api/system")
-                .then((res) => (res.ok ? res.json() : Promise.reject()))
-                .then((data: SystemData) => {
-                    if (data.uptime < uptimeBeforeReboot.current) {
-                        window.location.reload();
-                    } else {
-                        pollTimer.current = setTimeout(poll, 2000);
-                    }
-                })
-                .catch(() => {
-                    pollTimer.current = setTimeout(poll, 2000);
-                });
-        };
-        pollTimer.current = setTimeout(poll, 2000);
-    }, []);
-
-    useEffect(() => {
-        return () => {
-            if (pollTimer.current) clearTimeout(pollTimer.current);
-        };
-    }, []);
+    usePoll(
+        async () => {
+            const res = await fetch("/api/system");
+            if (!res.ok) throw new Error();
+            const data: SystemData = await res.json();
+            if (data.uptime < uptimeBeforeReboot.current) {
+                window.location.reload();
+            }
+        },
+        2000,
+        rebooting,
+        2000,
+    );
 
     const startRebootFlow = useCallback(() => {
         uptimeBeforeReboot.current = currentUptime;
         setRebooting(true);
-        pollUntilRebooted();
-    }, [currentUptime, pollUntilRebooted]);
+    }, [currentUptime]);
 
     return { rebooting, startRebootFlow };
 }

From 060d09bccef01dd9527db8c7f2457e5439b9e346 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?= <sonerkoksal@gmail.com>
Date: Mon, 18 May 2026 19:49:42 +0300
Subject: [PATCH 33/44] fix: rate limit demo probe paths

---
 frontend/mock/worker.js | 26 ++++++++++++++++++++++++++
 frontend/wrangler.toml  |  8 ++++++++
 2 files changed, 34 insertions(+)

diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 711bf6f..179ceb5 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -79,6 +79,23 @@ async function checkAnalyticsRateLimit(request, env) {
     });
 }
 
+async function checkProbePathRateLimit(request, env) {
+    if (!env.PROBE_PATH_RATE_LIMITER) return null;
+
+    const clientIP = request.headers.get("CF-Connecting-IP") || "anonymous";
+    const { success } = await env.PROBE_PATH_RATE_LIMITER.limit({ key: `probe-path:${clientIP}` });
+    if (success) return null;
+
+    return new Response(null, {
+        status: 429,
+        headers: { "Retry-After": "60" },
+    });
+}
+
+function isProbePath(pathname) {
+    return pathname.includes("/wp-");
+}
+
 async function readBodyWithLimit(request) {
     if (!request.body) return new Uint8Array();
 
@@ -404,6 +421,15 @@ async function serveAsset(request, env) {
 export default {
     async fetch(request, env) {
         const url = new URL(request.url);
+
+        if (isProbePath(url.pathname)) {
+            const rateLimited = await checkProbePathRateLimit(request, env);
+            if (rateLimited) return withSecurityHeaders(rateLimited);
+
+            // Do not fall through to the SPA asset fallback for obvious probe paths.
+            return withSecurityHeaders(new Response(null, { status: 404 }));
+        }
+
         if (request.method === "POST" && url.pathname === "/api/collect") {
             return withSecurityHeaders(await handleCollect(request, env));
         }
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index b962b60..730a7e4 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -24,6 +24,14 @@ namespace_id = "20260518"
   limit = 60
   period = 60
 
+[[ratelimits]]
+name = "PROBE_PATH_RATE_LIMITER"
+namespace_id = "20260519"
+
+  [ratelimits.simple]
+  limit = 1
+  period = 60
+
 [[routes]]
 pattern = "openneato-demo.renjfk.com"
 custom_domain = true

From 76ef8ab8d543eef77866886489df9854e31a2614 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Soner=20Ko=CC=88ksal?=
 <15015690+renjfk@users.noreply.github.com>
Date: Mon, 18 May 2026 21:05:35 +0300
Subject: [PATCH 34/44] Revert demo probe-path rate limiter; WAF blocks wp-* at
 edge

---
 frontend/mock/worker.js | 26 --------------------------
 frontend/wrangler.toml  |  8 --------
 2 files changed, 34 deletions(-)

diff --git a/frontend/mock/worker.js b/frontend/mock/worker.js
index 179ceb5..711bf6f 100644
--- a/frontend/mock/worker.js
+++ b/frontend/mock/worker.js
@@ -79,23 +79,6 @@ async function checkAnalyticsRateLimit(request, env) {
     });
 }
 
-async function checkProbePathRateLimit(request, env) {
-    if (!env.PROBE_PATH_RATE_LIMITER) return null;
-
-    const clientIP = request.headers.get("CF-Connecting-IP") || "anonymous";
-    const { success } = await env.PROBE_PATH_RATE_LIMITER.limit({ key: `probe-path:${clientIP}` });
-    if (success) return null;
-
-    return new Response(null, {
-        status: 429,
-        headers: { "Retry-After": "60" },
-    });
-}
-
-function isProbePath(pathname) {
-    return pathname.includes("/wp-");
-}
-
 async function readBodyWithLimit(request) {
     if (!request.body) return new Uint8Array();
 
@@ -421,15 +404,6 @@ async function serveAsset(request, env) {
 export default {
     async fetch(request, env) {
         const url = new URL(request.url);
-
-        if (isProbePath(url.pathname)) {
-            const rateLimited = await checkProbePathRateLimit(request, env);
-            if (rateLimited) return withSecurityHeaders(rateLimited);
-
-            // Do not fall through to the SPA asset fallback for obvious probe paths.
-            return withSecurityHeaders(new Response(null, { status: 404 }));
-        }
-
         if (request.method === "POST" && url.pathname === "/api/collect") {
             return withSecurityHeaders(await handleCollect(request, env));
         }
diff --git a/frontend/wrangler.toml b/frontend/wrangler.toml
index 730a7e4..b962b60 100644
--- a/frontend/wrangler.toml
+++ b/frontend/wrangler.toml
@@ -24,14 +24,6 @@ namespace_id = "20260518"
   limit = 60
   period = 60
 
-[[ratelimits]]
-name = "PROBE_PATH_RATE_LIMITER"
-namespace_id = "20260519"
-
-  [ratelimits.simple]
-  limit = 1
-  period = 60
-
 [[routes]]
 pattern = "openneato-demo.renjfk.com"
 custom_domain = true

From 242011706b9e917ad8622abcc3ea415dc9294c10 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 12:37:48 -0400
Subject: [PATCH 35/44] feat(ha): surface upstream-merge features as HA
 entities
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New switches:
  * notify_on_start — was missing despite firmware/frontend having it (fork PR #2)
  * ap_fallback_on_disconnect — upstream #110 captive-portal AP fallback

- New text entities for full ntfy config from HA UI:
  * ntfy_topic, ntfy_server, ntfy_token

- manifest.json: 1.10 -> 1.11
- CHANGELOG: document additions and deferred items (zeroconf disabled because
  firmware only advertises _http._tcp; About metadata not surfaced yet)
- .gitignore: ignore Python __pycache__/*.pyc
---
 .gitignore                                |  2 ++
 custom_components/openneato/CHANGELOG.md  | 32 +++++++++++++++++++++++
 custom_components/openneato/manifest.json |  2 +-
 custom_components/openneato/strings.json  |  7 ++++-
 custom_components/openneato/switch.py     | 20 ++++++++++++++
 custom_components/openneato/text.py       | 27 +++++++++++++++++++
 6 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 746ef71..8c96012 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
 .pio
 .cache
+__pycache__/
+*.pyc
 compile_commands.json
 firmware/compile_commands.json
 firmware/src/web_assets.h
diff --git a/custom_components/openneato/CHANGELOG.md b/custom_components/openneato/CHANGELOG.md
index deeca28..aa3181d 100644
--- a/custom_components/openneato/CHANGELOG.md
+++ b/custom_components/openneato/CHANGELOG.md
@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.11
+
+### Added
+- **`notify_on_start` switch** — surfaces fork PR #2's "notify on cleaning
+  started" setting (`ntfyOnStart`). Firmware + frontend already supported
+  the toggle; the matching HA entity was missing, so the switch row sat
+  among `notify_on_done`/`error`/`alert`/`docking` with no `start` peer.
+- **`ap_fallback_on_disconnect` switch** — upstream firmware #110 added
+  an `apFallbackOnDisconnect` setting that brings up the captive-portal
+  AP automatically when WiFi STA drops. Now configurable from HA.
+- **`ntfy_topic`, `ntfy_server`, `ntfy_token` text entities** — full ntfy
+  push-notification configuration is now editable from HA, no need to
+  open the device web UI. Empty topic disables notifications; empty
+  server defaults to `ntfy.sh`; empty token is unauthenticated.
+
+### Not done (deliberate deferral)
+- **Upstream About metadata not surfaced** — firmware commit bb7b541
+  added `name`, `repositoryUrl`, `license`, `model` fields to
+  `/api/firmware/version`. Threading `repository_url` through every
+  entity constructor for nine platforms (vacuum, sensor, switch,
+  binary_sensor, number, button, camera, select, text) just to set a
+  device-info attribute was too invasive for the value it adds, and the
+  `name` field already matches our hardcoded `manufacturer="OpenNeato"`.
+  A cleaner future approach is a dedicated diagnostic sensor that
+  exposes the full About payload as attributes.
+- **Zeroconf discovery not added** — `manifest.json` was eligible for a
+  `zeroconf` entry, but the firmware (`wifi_manager.cpp`) currently only
+  registers the generic `_http._tcp` service. Claiming that service for
+  the OpenNeato integration would match every random HTTP device on the
+  LAN. When the firmware advertises a dedicated service type (e.g.
+  `_openneato._tcp`), wire this up.
+
 ## 1.10
 
 ### Fixed
diff --git a/custom_components/openneato/manifest.json b/custom_components/openneato/manifest.json
index 57ce71b..e781d26 100644
--- a/custom_components/openneato/manifest.json
+++ b/custom_components/openneato/manifest.json
@@ -7,5 +7,5 @@
   "documentation": "https://github.com/renjfk/OpenNeato",
   "iot_class": "local_polling",
   "requirements": [],
-  "version": "1.10"
+  "version": "1.11"
 }
diff --git a/custom_components/openneato/strings.json b/custom_components/openneato/strings.json
index 3858450..9684e3b 100644
--- a/custom_components/openneato/strings.json
+++ b/custom_components/openneato/strings.json
@@ -71,10 +71,12 @@
       "warning_sounds": { "name": "Warning sounds" },
       "stealth_led": { "name": "Stealth LED" },
       "notifications_enabled": { "name": "Notifications" },
+      "notify_on_start": { "name": "Notify on clean start" },
       "notify_on_done": { "name": "Notify on clean done" },
       "notify_on_error": { "name": "Notify on error" },
       "notify_on_alert": { "name": "Notify on alert" },
       "notify_on_docking": { "name": "Notify on docking" },
+      "ap_fallback_on_disconnect": { "name": "WiFi AP fallback" },
       "remote_syslog": { "name": "Remote syslog" }
     },
     "button": {
@@ -100,7 +102,10 @@
       "navigation_mode": { "name": "Navigation mode" }
     },
     "text": {
-      "syslog_ip": { "name": "Syslog server IP" }
+      "syslog_ip": { "name": "Syslog server IP" },
+      "ntfy_topic": { "name": "Notification topic" },
+      "ntfy_server": { "name": "Notification server" },
+      "ntfy_token": { "name": "Notification token" }
     }
   }
 }
diff --git a/custom_components/openneato/switch.py b/custom_components/openneato/switch.py
index 5066bf1..16b4fce 100644
--- a/custom_components/openneato/switch.py
+++ b/custom_components/openneato/switch.py
@@ -131,6 +131,16 @@ class OpenNeatoSwitchEntityDescription(SwitchEntityDescription):
         icon="mdi:bell",
         entity_category=EntityCategory.CONFIG,
     ),
+    OpenNeatoSwitchEntityDescription(
+        key="notify_on_start",
+        translation_key="notify_on_start",
+        name="Notify on clean start",
+        section="settings",
+        field="ntfyOnStart",
+        settings_field="ntfyOnStart",
+        icon="mdi:bell-outline",
+        entity_category=EntityCategory.CONFIG,
+    ),
     OpenNeatoSwitchEntityDescription(
         key="notify_on_done",
         translation_key="notify_on_done",
@@ -171,6 +181,16 @@ class OpenNeatoSwitchEntityDescription(SwitchEntityDescription):
         icon="mdi:bell-plus",
         entity_category=EntityCategory.CONFIG,
     ),
+    OpenNeatoSwitchEntityDescription(
+        key="ap_fallback_on_disconnect",
+        translation_key="ap_fallback_on_disconnect",
+        name="WiFi AP fallback",
+        section="settings",
+        field="apFallbackOnDisconnect",
+        settings_field="apFallbackOnDisconnect",
+        icon="mdi:wifi-strength-alert-outline",
+        entity_category=EntityCategory.CONFIG,
+    ),
     OpenNeatoSwitchEntityDescription(
         key="remote_syslog",
         translation_key="remote_syslog",
diff --git a/custom_components/openneato/text.py b/custom_components/openneato/text.py
index a1fabfe..e0e252a 100644
--- a/custom_components/openneato/text.py
+++ b/custom_components/openneato/text.py
@@ -40,6 +40,33 @@ class OpenNeatoTextEntityDescription(TextEntityDescription):
         native_max=15,
         pattern=r"^(\d{1,3}\.){3}\d{1,3}$|^$",
     ),
+    OpenNeatoTextEntityDescription(
+        key="ntfy_topic",
+        translation_key="ntfy_topic",
+        name="Notification topic",
+        section="settings",
+        settings_field="ntfyTopic",
+        icon="mdi:bell-cog",
+        entity_category=EntityCategory.CONFIG,
+    ),
+    OpenNeatoTextEntityDescription(
+        key="ntfy_server",
+        translation_key="ntfy_server",
+        name="Notification server",
+        section="settings",
+        settings_field="ntfyServer",
+        icon="mdi:server",
+        entity_category=EntityCategory.CONFIG,
+    ),
+    OpenNeatoTextEntityDescription(
+        key="ntfy_token",
+        translation_key="ntfy_token",
+        name="Notification token",
+        section="settings",
+        settings_field="ntfyToken",
+        icon="mdi:key",
+        entity_category=EntityCategory.CONFIG,
+    ),
 )
 
 

From 9870ca620f005f4fa58641ccb941a0da1273e920 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 12:44:03 -0400
Subject: [PATCH 36/44] fix(api): add /api/sensors to OpenAPI spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This fork's web server registers GET /api/sensors (returning DigitalSensorData
— dustbin, bumpers, wheel lift, DC jack) for the HA integration. Upstream's
check_api_paths script flags route surface drift, so the spec needs the
endpoint + schema to keep `npm run build` green.
---
 frontend/api/openapi.yaml | 62 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/frontend/api/openapi.yaml b/frontend/api/openapi.yaml
index 6d2aa6e..9aa7357 100644
--- a/frontend/api/openapi.yaml
+++ b/frontend/api/openapi.yaml
@@ -137,6 +137,24 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /api/sensors:
+    get:
+      tags:
+        - Sensors
+      summary: Get digital sensor data (dustbin, bumpers, wheel lift, DC jack)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DigitalSensorData"
+        "504":
+          description: robot timeout
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
   /api/state:
     get:
       tags:
@@ -1015,6 +1033,50 @@ components:
         - cumulativeBatteryCycles
         - cumulativeCleaningTimeSeconds
         - validationCode
+    DigitalSensorData:
+      type: object
+      properties:
+        dcJackIn:
+          type: boolean
+          description: True when the external DC barrel jack is plugged in
+        dustbinIn:
+          type: boolean
+          description: True when the dustbin is seated
+        leftWheelExtended:
+          type: boolean
+          description: True when the left drive wheel is lifted off the ground
+        rightWheelExtended:
+          type: boolean
+          description: True when the right drive wheel is lifted off the ground
+        lSideBit:
+          type: boolean
+          description: Left side bumper triggered
+        lFrontBit:
+          type: boolean
+          description: Left front bumper triggered
+        lLdsBit:
+          type: boolean
+          description: Left LDS guard bumper triggered
+        rSideBit:
+          type: boolean
+          description: Right side bumper triggered
+        rFrontBit:
+          type: boolean
+          description: Right front bumper triggered
+        rLdsBit:
+          type: boolean
+          description: Right LDS guard bumper triggered
+      required:
+        - dcJackIn
+        - dustbinIn
+        - leftWheelExtended
+        - rightWheelExtended
+        - lSideBit
+        - lFrontBit
+        - lLdsBit
+        - rSideBit
+        - rFrontBit
+        - rLdsBit
     MotorData:
       type: object
       properties:

From 35bc12057fe17605deaa62066332c4190c301810 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 12:52:44 -0400
Subject: [PATCH 37/44] docs(readme): document the HA integration

Reddit follow-up: u/leicas was asked to surface the HACS integration in the
fork's README. The README was the upstream version verbatim and never
mentioned the integration that's been the fork's value-add since 1.0.0.

New section covers install via HACS, the full entity inventory (vacuum,
2 cameras, sensors, binary_sensors, switches, text, numbers, select,
buttons), coordinator resilience guarantees, ntfy/custom-server tips,
and per-version highlights (links to custom_components/openneato/CHANGELOG.md
for the full log).
---
 README.md | 454 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 269 insertions(+), 185 deletions(-)

diff --git a/README.md b/README.md
index 3f694f5..00a09c9 100644
--- a/README.md
+++ b/README.md
@@ -1,185 +1,269 @@
-[![CI](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Latest Release](https://img.shields.io/github/v/release/renjfk/OpenNeato)](https://github.com/renjfk/OpenNeato/releases/latest)
-[![Downloads](https://img.shields.io/github/downloads/renjfk/OpenNeato/total)](https://github.com/renjfk/OpenNeato/releases)
-
-<p align="center">
- <img width="192" alt="OpenNeato Icon" src="frontend/public/icon-192.png">
-</p>
-
-# OpenNeato
-
-Open-source replacement for Neato's discontinued cloud and mobile app. An ESP32 bridge communicates with
-Botvac robots (D3-D7) over UART and exposes a local web UI over WiFi — no cloud, no app, no account required.
-
-> [!NOTE]
-> This is an early beta - things may break, rough edges are expected, and the API may change.
-> If you run into problems, a [Discussion](https://github.com/renjfk/OpenNeato/discussions)
-> or [issue](https://github.com/renjfk/OpenNeato/issues) is always welcome.
-
-> [!IMPORTANT]
-> **Now in development:**
-[Guided Clean - zone cleaning, no-go lines, and map-based navigation](https://github.com/renjfk/OpenNeato/issues/68).
->
-> Select zones on a previously recorded map, draw no-go lines, and let the robot clean exactly where you want.
-> Follow the issue for progress updates and sub-task tracking.
-
-> [!TIP]
-> Want to get a feel for OpenNeato without hardware? Open the [live demo](https://openneato-demo.renjfk.com/).
-> Demo states can be selected with `?scenario=...`; see [mock scenarios](docs/mock-scenarios.md).
-
-|                Dashboard                 |                  Manual Drive                  |                    Cleaning History                    |
-|:----------------------------------------:|:----------------------------------------------:|:------------------------------------------------------:|
-| ![Dashboard](screenshots/dashboard.webp) | ![Manual Drive](screenshots/manual-drive.webp) | ![Cleaning History](screenshots/cleaning-history.webp) |
-
-|                Clean Map                 |                Schedule                |                Settings                |
-|:----------------------------------------:|:--------------------------------------:|:--------------------------------------:|
-| ![Clean Map](screenshots/clean-map.webp) | ![Schedule](screenshots/schedule.webp) | ![Settings](screenshots/settings.webp) |
-
-## Motivation
-
-Neato shut down their cloud services and mobile app, leaving perfectly functional robot vacuums without remote
-control or scheduling. OpenNeato brings them back to life with a small ESP32 board wired to the robot's debug
-port, giving you a local web interface that works without any external dependencies.
-
-## Features
-
-- **Dashboard** with live robot status, battery level, cleaning state, WiFi signal, and storage usage
-- **House and spot cleaning** with pause/resume/stop/dock controls that adapt to the current state
-- **Manual driving mode** with a virtual joystick, live LIDAR map visualization, motor toggles (brush, vacuum, side
-  brush), bumper/wheel-lift/stall safety warnings
-- **Live cleaning map** — watch the robot's path during an active cleaning session in the History view, rendered on a
-  canvas with coverage overlay
-- **7-day cleaning scheduler** with two slots per day, managed entirely on the ESP32 (doesn't use the robot's built-in
-  schedule commands)
-- **Cleaning history** with recorded robot paths rendered as coverage maps, session stats like duration, distance, area
-  covered, and battery usage; individual session import/export for backup and restore
-- **Push notifications** via [ntfy.sh](https://ntfy.sh); get notified when cleaning is done, an error occurs, a
-  maintenance alert triggers, or the robot docks; fully optional, configurable per event
-- **OTA firmware updates** from the browser with SHA-256 download verification (against published `checksums.txt`), MD5
-  transfer integrity, dual-partition layout with auto-rollback, and automatic new version notifications when a release
-  is available on GitHub
-- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto),
-  battery diagnostics (cycle count, voltage, temperature, and a "New Battery" calibration trigger), and more
-- **Event logging** with configurable log levels (off/info/debug), compressed JSONL files on SPIFFS, browsable and
-  downloadable from the UI; optional remote syslog (UDP) for long-running diagnostics without flash wear; logging is
-  off by default
-- **Factory reset** via 5-second button hold on the ESP32 or from the settings page
-- **Robot clock sync** — pushes NTP time to the robot automatically, re-syncs every 4 hours
-- **Flash tool** — standalone CLI that auto-detects the USB port, downloads the correct firmware from GitHub Releases,
-  and flashes with zero prerequisites
-- **Safety watchdog** — auto-stops wheels in manual mode if the browser disconnects; task and heap watchdogs restart the
-  ESP32 on hangs
-- **Crash recovery** — orphaned cleaning sessions after unexpected reboots are automatically recovered with full stats
-
-The frontend is a lightweight SPA that gets gzipped and embedded directly into the firmware binary, so a single
-OTA update covers both firmware and UI. Mobile-friendly, dark theme by default.
-
-## Supported Robots
-
-Neato Botvac D3 through D7. D8/D9/D10 are NOT supported (different board, password-locked serial port).
-
-## Installation
-
-### Requirements
-
-- ESP32-C3, ESP32-S3, or original ESP32 board with **4 MB flash** (any dev board with USB and exposed GPIOs)
-
-### Quick Start
-
-1. Download the latest release from the [Releases](https://github.com/renjfk/OpenNeato/releases) page
-2. Flash the ESP32 using the flash tool (auto-detects your chip type):
-   ```bash
-   openneato-flash
-   ```
-3. Configure your home WiFi via the serial menu (opens automatically after flashing)
-4. Wire the ESP32 to your robot's debug port
-5. Open the web UI at `http://neato.local` or the IP shown in the serial monitor
-
-For detailed instructions and troubleshooting, see the [User Guide](docs/user-guide.md).
-
-### Building from Source
-
-Requires [Node.js](https://nodejs.org/) 22+, [PlatformIO CLI](https://platformio.org/install/cli),
-and [Go](https://go.dev/) 1.26+.
-
-```bash
-git clone https://github.com/renjfk/OpenNeato.git
-cd OpenNeato
-
-# Build frontend (generates web_assets.h)
-cd frontend && npm ci && npm run build && cd ..
-
-# Build firmware
-pio run -e c3-release
-
-# Build flash tool
-cd flash && go build -o openneato-flash . && cd ..
-```
-
-## Contributing
-
-OpenNeato is open to contributions and ideas! Whether you're a developer wanting to add features or a user with
-suggestions, your input is valuable.
-
-The most useful contributions are testing prereleases on your hardware, filing clear bug reports, and opening PRs.
-If you'd rather just say thanks, there's a [Ko-fi](https://ko-fi.com/renjfk). Optional, doesn't influence the
-roadmap, the project stays free and community-driven either way.
-
-> [!TIP]
-> Before opening an issue, consider starting a [Discussion](https://github.com/renjfk/OpenNeato/discussions) first —
-> many questions, setup troubles, and ideas are easier to resolve through conversation.
-
-> [!IMPORTANT]
-> For anything beyond a small bug fix, please open an issue
-> or [Discussion](https://github.com/renjfk/OpenNeato/discussions) first to align on the design before writing code.
-> This is an embedded project with tight resource constraints (single-core MCU, 320 KB RAM, 1.6 MB flash per OTA slot)
-> and strict architectural rules (non-blocking event loop, zero external dependencies). A quick design conversation
-> upfront avoids large rewrites during review.
-
-### Issue Conventions
-
-When creating issues, please follow our simple naming convention:
-
-**Format:** `type: brief description`
-
-#### Issue Types
-
-- `feat:` - New features or functionality
-- `fix:` - Bug fixes
-- `enhance:` - Improvements to existing features
-- `chore:` - Maintenance tasks, dependencies, cleanup
-- `docs:` - Documentation updates
-- `build:` - Build system, CI/CD changes
-
-#### Examples
-
-- `feat: add CSV export functionality`
-- `fix: app crashes when importing large files`
-- `enhance: improve data loading performance`
-- `chore: update dependencies to latest versions`
-- `docs: update README with installation instructions`
-- `build: update Xcode project settings`
-
-#### Guidelines
-
-- Use lowercase for the description
-- Be specific and actionable
-- Keep under 60 characters
-- No period at the end
-
-## Development
-
-For frontend development without hardware, use the mock API scenarios documented in
-[`docs/mock-scenarios.md`](docs/mock-scenarios.md). The same `?scenario=...` URLs work in local Vite dev and the
-Cloudflare demo.
-
-### Release Process
-
-Manual releases via opencode; see [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
-
-Prereleases can be triggered from any PR by commenting `/prerelease` (collaborators only).
-
-## License
-
-This project is licensed under the [MIT License](LICENSE).
+[![CI](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Latest Release](https://img.shields.io/github/v/release/renjfk/OpenNeato)](https://github.com/renjfk/OpenNeato/releases/latest)
+[![Downloads](https://img.shields.io/github/downloads/renjfk/OpenNeato/total)](https://github.com/renjfk/OpenNeato/releases)
+
+<p align="center">
+ <img width="192" alt="OpenNeato Icon" src="frontend/public/icon-192.png">
+</p>
+
+# OpenNeato
+
+Open-source replacement for Neato's discontinued cloud and mobile app. An ESP32 bridge communicates with
+Botvac robots (D3-D7) over UART and exposes a local web UI over WiFi — no cloud, no app, no account required.
+
+> [!NOTE]
+> This is an early beta - things may break, rough edges are expected, and the API may change.
+> If you run into problems, a [Discussion](https://github.com/renjfk/OpenNeato/discussions)
+> or [issue](https://github.com/renjfk/OpenNeato/issues) is always welcome.
+
+> [!IMPORTANT]
+> **Now in development:**
+[Guided Clean - zone cleaning, no-go lines, and map-based navigation](https://github.com/renjfk/OpenNeato/issues/68).
+>
+> Select zones on a previously recorded map, draw no-go lines, and let the robot clean exactly where you want.
+> Follow the issue for progress updates and sub-task tracking.
+
+> [!TIP]
+> Want to get a feel for OpenNeato without hardware? Open the [live demo](https://openneato-demo.renjfk.com/).
+> Demo states can be selected with `?scenario=...`; see [mock scenarios](docs/mock-scenarios.md).
+
+|                Dashboard                 |                  Manual Drive                  |                    Cleaning History                    |
+|:----------------------------------------:|:----------------------------------------------:|:------------------------------------------------------:|
+| ![Dashboard](screenshots/dashboard.webp) | ![Manual Drive](screenshots/manual-drive.webp) | ![Cleaning History](screenshots/cleaning-history.webp) |
+
+|                Clean Map                 |                Schedule                |                Settings                |
+|:----------------------------------------:|:--------------------------------------:|:--------------------------------------:|
+| ![Clean Map](screenshots/clean-map.webp) | ![Schedule](screenshots/schedule.webp) | ![Settings](screenshots/settings.webp) |
+
+## Motivation
+
+Neato shut down their cloud services and mobile app, leaving perfectly functional robot vacuums without remote
+control or scheduling. OpenNeato brings them back to life with a small ESP32 board wired to the robot's debug
+port, giving you a local web interface that works without any external dependencies.
+
+## Features
+
+- **Dashboard** with live robot status, battery level, cleaning state, WiFi signal, and storage usage
+- **House and spot cleaning** with pause/resume/stop/dock controls that adapt to the current state
+- **Manual driving mode** with a virtual joystick, live LIDAR map visualization, motor toggles (brush, vacuum, side
+  brush), bumper/wheel-lift/stall safety warnings
+- **Live cleaning map** — watch the robot's path during an active cleaning session in the History view, rendered on a
+  canvas with coverage overlay
+- **7-day cleaning scheduler** with two slots per day, managed entirely on the ESP32 (doesn't use the robot's built-in
+  schedule commands)
+- **Cleaning history** with recorded robot paths rendered as coverage maps, session stats like duration, distance, area
+  covered, and battery usage; individual session import/export for backup and restore
+- **Push notifications** via [ntfy.sh](https://ntfy.sh); get notified when cleaning is done, an error occurs, a
+  maintenance alert triggers, or the robot docks; fully optional, configurable per event
+- **OTA firmware updates** from the browser with SHA-256 download verification (against published `checksums.txt`), MD5
+  transfer integrity, dual-partition layout with auto-rollback, and automatic new version notifications when a release
+  is available on GitHub
+- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto),
+  battery diagnostics (cycle count, voltage, temperature, and a "New Battery" calibration trigger), and more
+- **Event logging** with configurable log levels (off/info/debug), compressed JSONL files on SPIFFS, browsable and
+  downloadable from the UI; optional remote syslog (UDP) for long-running diagnostics without flash wear; logging is
+  off by default
+- **Factory reset** via 5-second button hold on the ESP32 or from the settings page
+- **Robot clock sync** — pushes NTP time to the robot automatically, re-syncs every 4 hours
+- **Flash tool** — standalone CLI that auto-detects the USB port, downloads the correct firmware from GitHub Releases,
+  and flashes with zero prerequisites
+- **Safety watchdog** — auto-stops wheels in manual mode if the browser disconnects; task and heap watchdogs restart the
+  ESP32 on hangs
+- **Crash recovery** — orphaned cleaning sessions after unexpected reboots are automatically recovered with full stats
+
+The frontend is a lightweight SPA that gets gzipped and embedded directly into the firmware binary, so a single
+OTA update covers both firmware and UI. Mobile-friendly, dark theme by default.
+
+## Home Assistant Integration
+
+This fork ships a HACS-installable Home Assistant custom integration in
+[`custom_components/openneato/`](custom_components/openneato/). Once installed it discovers your OpenNeato bridge
+by IP/hostname and exposes the robot as a full HA device — no YAML, no extra add-ons.
+
+> [!NOTE]
+> The HA integration is the primary differentiator of this fork. The firmware, frontend, and flash tool track
+> upstream [`renjfk/OpenNeato`](https://github.com/renjfk/OpenNeato) closely. If you only want the standalone web
+> UI, use upstream directly.
+
+### Install via HACS
+
+1. In HACS, add this fork as a **custom repository**: `https://github.com/Leicas/OpenNeato` (category:
+   *Integration*).
+2. Search for **OpenNeato** in HACS and install.
+3. Restart Home Assistant.
+4. **Settings → Devices & Services → Add Integration → OpenNeato** and enter the bridge hostname or IP
+   (e.g. `neato.local` or `192.168.1.42`).
+
+The integration polls `/api/*` over your LAN every 5 seconds (`local_polling`). No cloud round-trip, no
+external dependencies. Requires firmware `1.0+`; battery diagnostics need firmware `0.13+` (upstream PR #121).
+
+### What you get
+
+A single device with the following entity groups:
+
+- **Vacuum** (`vacuum.openneato_<name>`) — start/stop/pause/dock/locate/spot-clean, battery level, status,
+  fan speed presets (Eco/Auto/Intense), error reporting. Works with all the standard vacuum cards.
+- **Cameras** — `LIDAR map` (live 360° scan during cleaning) and `Cleaning replay` (animated GIF time-lapse
+  of the most recent completed session). Both are standard HA camera entities, compatible with
+  picture-entity, picture-glance, and vacuum-card.
+- **Sensors** — battery level/voltage/current/temperature, battery cycle count, cumulative cleaning time,
+  WiFi RSSI, free heap, storage used, uptime, motor RPMs, error code/message, plus "last clean" stats
+  (duration, area covered, distance, battery used, mode, end time) pulled from the on-device history.
+- **Binary sensors** — charging, external power, battery over-temp, battery failure, empty fuel, error
+  active, NTP synced, dustbin seated, left/right wheel lifted, dock contact.
+- **Switches** — eco mode, intense clean, bin-full detect, wall follower, schedule on/off, button-click
+  sounds, melodies, warnings, stealth LED, remote syslog, WiFi AP fallback, and per-event push
+  notifications (start/done/error/alert/docking).
+- **Text** — syslog server IP, ntfy topic, ntfy server, ntfy token (full push-notification config from HA).
+- **Numbers** — brush RPM, vacuum speed, side-brush power, stall threshold.
+- **Select** — navigation mode (Normal / Gentle / Deep / Quick).
+- **Buttons** — restart bridge, restart robot, shutdown robot, locate, clear errors, format filesystem
+  (diagnostic, disabled by default), **new battery** (resets fuel-gauge calibration after a physical pack
+  swap, disabled by default for safety).
+
+Every entity is translated via `strings.json`, and diagnostic-class entities (voltages, currents, raw
+sensor states) are tagged so they cluster cleanly under HA's Diagnostic section.
+
+### Notes for setup
+
+- **Camera entities and vacuum-card** — the `LIDAR map` camera self-manages a 2 s `/api/lidar` poll only
+  while the robot is actively cleaning, so it doesn't add load to the coordinator's 5 s cycle. When idle,
+  both cameras fall back to the most recent completed cleaning map.
+- **Coordinator resilience** — the integration tolerates a single hung endpoint without going into
+  "requires attention" state. State / charger / system are critical; anything else (errors, motors,
+  history) falls back to the last known value during transient ESP32 serial hangs.
+- **No Pillow declared dependency** — map rendering uses Pillow which already ships with HA Core, so the
+  integration's `manifest.json` keeps `"requirements": []`. Nothing extra to install.
+- **ntfy + custom servers** — point `ntfy_server` at a self-hosted instance and `ntfy_token` at a Bearer
+  token for authenticated push. Empty server defaults to `ntfy.sh`; empty token is unauthenticated.
+
+### Version history
+
+Full per-version notes live in [`custom_components/openneato/CHANGELOG.md`](custom_components/openneato/CHANGELOG.md).
+Highlights:
+
+- **1.11** — added `notify_on_start` and `ap_fallback_on_disconnect` switches; ntfy topic/server/token text
+  entities for full HA-side push config.
+- **1.10** — battery diagnostics (current, voltage, cycles, cumulative cleaning time) on top of firmware
+  PR #121, `New battery` calibration button, UTF-8-tolerant `/api/version` parsing.
+- **1.9** — fixed cameras stuck on the idle placeholder (`get_encoding()` crash on streamed bodies).
+- **1.6** — `Cleaning replay` camera (animated GIF time-lapse), `/api/history` corruption-tolerant parsing,
+  history filename validation + 2 MB response cap (LAN-MITM mitigation).
+- **1.3** — `LIDAR map` camera ported from the frontend renderer; self-managed polling.
+- **1.2** — last-clean stats sensors; dropped Pillow from declared deps.
+
+### Reporting integration bugs
+
+Use this fork's [issue tracker](https://github.com/Leicas/OpenNeato/issues) for anything that lives under
+`custom_components/openneato/`. For firmware, frontend, or flash-tool issues, upstream
+[renjfk/OpenNeato](https://github.com/renjfk/OpenNeato/issues) is the right place.
+
+## Supported Robots
+
+Neato Botvac D3 through D7. D8/D9/D10 are NOT supported (different board, password-locked serial port).
+
+## Installation
+
+### Requirements
+
+- ESP32-C3, ESP32-S3, or original ESP32 board with **4 MB flash** (any dev board with USB and exposed GPIOs)
+
+### Quick Start
+
+1. Download the latest release from the [Releases](https://github.com/renjfk/OpenNeato/releases) page
+2. Flash the ESP32 using the flash tool (auto-detects your chip type):
+   ```bash
+   openneato-flash
+   ```
+3. Configure your home WiFi via the serial menu (opens automatically after flashing)
+4. Wire the ESP32 to your robot's debug port
+5. Open the web UI at `http://neato.local` or the IP shown in the serial monitor
+
+For detailed instructions and troubleshooting, see the [User Guide](docs/user-guide.md).
+
+### Building from Source
+
+Requires [Node.js](https://nodejs.org/) 22+, [PlatformIO CLI](https://platformio.org/install/cli),
+and [Go](https://go.dev/) 1.26+.
+
+```bash
+git clone https://github.com/renjfk/OpenNeato.git
+cd OpenNeato
+
+# Build frontend (generates web_assets.h)
+cd frontend && npm ci && npm run build && cd ..
+
+# Build firmware
+pio run -e c3-release
+
+# Build flash tool
+cd flash && go build -o openneato-flash . && cd ..
+```
+
+## Contributing
+
+OpenNeato is open to contributions and ideas! Whether you're a developer wanting to add features or a user with
+suggestions, your input is valuable.
+
+The most useful contributions are testing prereleases on your hardware, filing clear bug reports, and opening PRs.
+If you'd rather just say thanks, there's a [Ko-fi](https://ko-fi.com/renjfk). Optional, doesn't influence the
+roadmap, the project stays free and community-driven either way.
+
+> [!TIP]
+> Before opening an issue, consider starting a [Discussion](https://github.com/renjfk/OpenNeato/discussions) first —
+> many questions, setup troubles, and ideas are easier to resolve through conversation.
+
+> [!IMPORTANT]
+> For anything beyond a small bug fix, please open an issue
+> or [Discussion](https://github.com/renjfk/OpenNeato/discussions) first to align on the design before writing code.
+> This is an embedded project with tight resource constraints (single-core MCU, 320 KB RAM, 1.6 MB flash per OTA slot)
+> and strict architectural rules (non-blocking event loop, zero external dependencies). A quick design conversation
+> upfront avoids large rewrites during review.
+
+### Issue Conventions
+
+When creating issues, please follow our simple naming convention:
+
+**Format:** `type: brief description`
+
+#### Issue Types
+
+- `feat:` - New features or functionality
+- `fix:` - Bug fixes
+- `enhance:` - Improvements to existing features
+- `chore:` - Maintenance tasks, dependencies, cleanup
+- `docs:` - Documentation updates
+- `build:` - Build system, CI/CD changes
+
+#### Examples
+
+- `feat: add CSV export functionality`
+- `fix: app crashes when importing large files`
+- `enhance: improve data loading performance`
+- `chore: update dependencies to latest versions`
+- `docs: update README with installation instructions`
+- `build: update Xcode project settings`
+
+#### Guidelines
+
+- Use lowercase for the description
+- Be specific and actionable
+- Keep under 60 characters
+- No period at the end
+
+## Development
+
+For frontend development without hardware, use the mock API scenarios documented in
+[`docs/mock-scenarios.md`](docs/mock-scenarios.md). The same `?scenario=...` URLs work in local Vite dev and the
+Cloudflare demo.
+
+### Release Process
+
+Manual releases via opencode; see [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
+
+Prereleases can be triggered from any PR by commenting `/prerelease` (collaborators only).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

From a2daebd9f063334e5dc60bb50a6431294c25a161 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 12:55:24 -0400
Subject: [PATCH 38/44] docs(readme): foreground the HA-fork framing; normalize
 to LF

Repositions the README so the first thing a Reddit-linked visitor sees is
'this is a fork focused on the HA integration with minor firmware tweaks'.
The previous commit landed the HA section but the title, intro, and upstream
'Motivation'/'Features' headings still read as the upstream project verbatim.

Changes:
- Title -> 'OpenNeato - Home Assistant fork'
- Lead paragraph + IMPORTANT box: when to use this fork vs upstream; firmware
  changes here are minor and only exist to back the integration.
- 'Motivation' -> 'About the underlying project (upstream)' with a skip-ahead
  link to the HA section.
- 'Features' -> 'Upstream web UI features' (sub-heading) so reader knows the
  feature list describes upstream, not the fork's HA-specific surface.
- Bug-report routing: HA issues here, firmware/frontend/flash-tool upstream.
- Badges repointed: CI/release badges no longer pull from upstream.

Also: large insertion/deletion count is the LF normalization pass; the prior
commit landed CRLF on disk on Windows. Forcing LF here so future diffs stay
clean.
---
 README.md | 552 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 283 insertions(+), 269 deletions(-)

diff --git a/README.md b/README.md
index 00a09c9..8abb4d7 100644
--- a/README.md
+++ b/README.md
@@ -1,269 +1,283 @@
-[![CI](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/renjfk/OpenNeato/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Latest Release](https://img.shields.io/github/v/release/renjfk/OpenNeato)](https://github.com/renjfk/OpenNeato/releases/latest)
-[![Downloads](https://img.shields.io/github/downloads/renjfk/OpenNeato/total)](https://github.com/renjfk/OpenNeato/releases)
-
-<p align="center">
- <img width="192" alt="OpenNeato Icon" src="frontend/public/icon-192.png">
-</p>
-
-# OpenNeato
-
-Open-source replacement for Neato's discontinued cloud and mobile app. An ESP32 bridge communicates with
-Botvac robots (D3-D7) over UART and exposes a local web UI over WiFi — no cloud, no app, no account required.
-
-> [!NOTE]
-> This is an early beta - things may break, rough edges are expected, and the API may change.
-> If you run into problems, a [Discussion](https://github.com/renjfk/OpenNeato/discussions)
-> or [issue](https://github.com/renjfk/OpenNeato/issues) is always welcome.
-
-> [!IMPORTANT]
-> **Now in development:**
-[Guided Clean - zone cleaning, no-go lines, and map-based navigation](https://github.com/renjfk/OpenNeato/issues/68).
->
-> Select zones on a previously recorded map, draw no-go lines, and let the robot clean exactly where you want.
-> Follow the issue for progress updates and sub-task tracking.
-
-> [!TIP]
-> Want to get a feel for OpenNeato without hardware? Open the [live demo](https://openneato-demo.renjfk.com/).
-> Demo states can be selected with `?scenario=...`; see [mock scenarios](docs/mock-scenarios.md).
-
-|                Dashboard                 |                  Manual Drive                  |                    Cleaning History                    |
-|:----------------------------------------:|:----------------------------------------------:|:------------------------------------------------------:|
-| ![Dashboard](screenshots/dashboard.webp) | ![Manual Drive](screenshots/manual-drive.webp) | ![Cleaning History](screenshots/cleaning-history.webp) |
-
-|                Clean Map                 |                Schedule                |                Settings                |
-|:----------------------------------------:|:--------------------------------------:|:--------------------------------------:|
-| ![Clean Map](screenshots/clean-map.webp) | ![Schedule](screenshots/schedule.webp) | ![Settings](screenshots/settings.webp) |
-
-## Motivation
-
-Neato shut down their cloud services and mobile app, leaving perfectly functional robot vacuums without remote
-control or scheduling. OpenNeato brings them back to life with a small ESP32 board wired to the robot's debug
-port, giving you a local web interface that works without any external dependencies.
-
-## Features
-
-- **Dashboard** with live robot status, battery level, cleaning state, WiFi signal, and storage usage
-- **House and spot cleaning** with pause/resume/stop/dock controls that adapt to the current state
-- **Manual driving mode** with a virtual joystick, live LIDAR map visualization, motor toggles (brush, vacuum, side
-  brush), bumper/wheel-lift/stall safety warnings
-- **Live cleaning map** — watch the robot's path during an active cleaning session in the History view, rendered on a
-  canvas with coverage overlay
-- **7-day cleaning scheduler** with two slots per day, managed entirely on the ESP32 (doesn't use the robot's built-in
-  schedule commands)
-- **Cleaning history** with recorded robot paths rendered as coverage maps, session stats like duration, distance, area
-  covered, and battery usage; individual session import/export for backup and restore
-- **Push notifications** via [ntfy.sh](https://ntfy.sh); get notified when cleaning is done, an error occurs, a
-  maintenance alert triggers, or the robot docks; fully optional, configurable per event
-- **OTA firmware updates** from the browser with SHA-256 download verification (against published `checksums.txt`), MD5
-  transfer integrity, dual-partition layout with auto-rollback, and automatic new version notifications when a release
-  is available on GitHub
-- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto),
-  battery diagnostics (cycle count, voltage, temperature, and a "New Battery" calibration trigger), and more
-- **Event logging** with configurable log levels (off/info/debug), compressed JSONL files on SPIFFS, browsable and
-  downloadable from the UI; optional remote syslog (UDP) for long-running diagnostics without flash wear; logging is
-  off by default
-- **Factory reset** via 5-second button hold on the ESP32 or from the settings page
-- **Robot clock sync** — pushes NTP time to the robot automatically, re-syncs every 4 hours
-- **Flash tool** — standalone CLI that auto-detects the USB port, downloads the correct firmware from GitHub Releases,
-  and flashes with zero prerequisites
-- **Safety watchdog** — auto-stops wheels in manual mode if the browser disconnects; task and heap watchdogs restart the
-  ESP32 on hangs
-- **Crash recovery** — orphaned cleaning sessions after unexpected reboots are automatically recovered with full stats
-
-The frontend is a lightweight SPA that gets gzipped and embedded directly into the firmware binary, so a single
-OTA update covers both firmware and UI. Mobile-friendly, dark theme by default.
-
-## Home Assistant Integration
-
-This fork ships a HACS-installable Home Assistant custom integration in
-[`custom_components/openneato/`](custom_components/openneato/). Once installed it discovers your OpenNeato bridge
-by IP/hostname and exposes the robot as a full HA device — no YAML, no extra add-ons.
-
-> [!NOTE]
-> The HA integration is the primary differentiator of this fork. The firmware, frontend, and flash tool track
-> upstream [`renjfk/OpenNeato`](https://github.com/renjfk/OpenNeato) closely. If you only want the standalone web
-> UI, use upstream directly.
-
-### Install via HACS
-
-1. In HACS, add this fork as a **custom repository**: `https://github.com/Leicas/OpenNeato` (category:
-   *Integration*).
-2. Search for **OpenNeato** in HACS and install.
-3. Restart Home Assistant.
-4. **Settings → Devices & Services → Add Integration → OpenNeato** and enter the bridge hostname or IP
-   (e.g. `neato.local` or `192.168.1.42`).
-
-The integration polls `/api/*` over your LAN every 5 seconds (`local_polling`). No cloud round-trip, no
-external dependencies. Requires firmware `1.0+`; battery diagnostics need firmware `0.13+` (upstream PR #121).
-
-### What you get
-
-A single device with the following entity groups:
-
-- **Vacuum** (`vacuum.openneato_<name>`) — start/stop/pause/dock/locate/spot-clean, battery level, status,
-  fan speed presets (Eco/Auto/Intense), error reporting. Works with all the standard vacuum cards.
-- **Cameras** — `LIDAR map` (live 360° scan during cleaning) and `Cleaning replay` (animated GIF time-lapse
-  of the most recent completed session). Both are standard HA camera entities, compatible with
-  picture-entity, picture-glance, and vacuum-card.
-- **Sensors** — battery level/voltage/current/temperature, battery cycle count, cumulative cleaning time,
-  WiFi RSSI, free heap, storage used, uptime, motor RPMs, error code/message, plus "last clean" stats
-  (duration, area covered, distance, battery used, mode, end time) pulled from the on-device history.
-- **Binary sensors** — charging, external power, battery over-temp, battery failure, empty fuel, error
-  active, NTP synced, dustbin seated, left/right wheel lifted, dock contact.
-- **Switches** — eco mode, intense clean, bin-full detect, wall follower, schedule on/off, button-click
-  sounds, melodies, warnings, stealth LED, remote syslog, WiFi AP fallback, and per-event push
-  notifications (start/done/error/alert/docking).
-- **Text** — syslog server IP, ntfy topic, ntfy server, ntfy token (full push-notification config from HA).
-- **Numbers** — brush RPM, vacuum speed, side-brush power, stall threshold.
-- **Select** — navigation mode (Normal / Gentle / Deep / Quick).
-- **Buttons** — restart bridge, restart robot, shutdown robot, locate, clear errors, format filesystem
-  (diagnostic, disabled by default), **new battery** (resets fuel-gauge calibration after a physical pack
-  swap, disabled by default for safety).
-
-Every entity is translated via `strings.json`, and diagnostic-class entities (voltages, currents, raw
-sensor states) are tagged so they cluster cleanly under HA's Diagnostic section.
-
-### Notes for setup
-
-- **Camera entities and vacuum-card** — the `LIDAR map` camera self-manages a 2 s `/api/lidar` poll only
-  while the robot is actively cleaning, so it doesn't add load to the coordinator's 5 s cycle. When idle,
-  both cameras fall back to the most recent completed cleaning map.
-- **Coordinator resilience** — the integration tolerates a single hung endpoint without going into
-  "requires attention" state. State / charger / system are critical; anything else (errors, motors,
-  history) falls back to the last known value during transient ESP32 serial hangs.
-- **No Pillow declared dependency** — map rendering uses Pillow which already ships with HA Core, so the
-  integration's `manifest.json` keeps `"requirements": []`. Nothing extra to install.
-- **ntfy + custom servers** — point `ntfy_server` at a self-hosted instance and `ntfy_token` at a Bearer
-  token for authenticated push. Empty server defaults to `ntfy.sh`; empty token is unauthenticated.
-
-### Version history
-
-Full per-version notes live in [`custom_components/openneato/CHANGELOG.md`](custom_components/openneato/CHANGELOG.md).
-Highlights:
-
-- **1.11** — added `notify_on_start` and `ap_fallback_on_disconnect` switches; ntfy topic/server/token text
-  entities for full HA-side push config.
-- **1.10** — battery diagnostics (current, voltage, cycles, cumulative cleaning time) on top of firmware
-  PR #121, `New battery` calibration button, UTF-8-tolerant `/api/version` parsing.
-- **1.9** — fixed cameras stuck on the idle placeholder (`get_encoding()` crash on streamed bodies).
-- **1.6** — `Cleaning replay` camera (animated GIF time-lapse), `/api/history` corruption-tolerant parsing,
-  history filename validation + 2 MB response cap (LAN-MITM mitigation).
-- **1.3** — `LIDAR map` camera ported from the frontend renderer; self-managed polling.
-- **1.2** — last-clean stats sensors; dropped Pillow from declared deps.
-
-### Reporting integration bugs
-
-Use this fork's [issue tracker](https://github.com/Leicas/OpenNeato/issues) for anything that lives under
-`custom_components/openneato/`. For firmware, frontend, or flash-tool issues, upstream
-[renjfk/OpenNeato](https://github.com/renjfk/OpenNeato/issues) is the right place.
-
-## Supported Robots
-
-Neato Botvac D3 through D7. D8/D9/D10 are NOT supported (different board, password-locked serial port).
-
-## Installation
-
-### Requirements
-
-- ESP32-C3, ESP32-S3, or original ESP32 board with **4 MB flash** (any dev board with USB and exposed GPIOs)
-
-### Quick Start
-
-1. Download the latest release from the [Releases](https://github.com/renjfk/OpenNeato/releases) page
-2. Flash the ESP32 using the flash tool (auto-detects your chip type):
-   ```bash
-   openneato-flash
-   ```
-3. Configure your home WiFi via the serial menu (opens automatically after flashing)
-4. Wire the ESP32 to your robot's debug port
-5. Open the web UI at `http://neato.local` or the IP shown in the serial monitor
-
-For detailed instructions and troubleshooting, see the [User Guide](docs/user-guide.md).
-
-### Building from Source
-
-Requires [Node.js](https://nodejs.org/) 22+, [PlatformIO CLI](https://platformio.org/install/cli),
-and [Go](https://go.dev/) 1.26+.
-
-```bash
-git clone https://github.com/renjfk/OpenNeato.git
-cd OpenNeato
-
-# Build frontend (generates web_assets.h)
-cd frontend && npm ci && npm run build && cd ..
-
-# Build firmware
-pio run -e c3-release
-
-# Build flash tool
-cd flash && go build -o openneato-flash . && cd ..
-```
-
-## Contributing
-
-OpenNeato is open to contributions and ideas! Whether you're a developer wanting to add features or a user with
-suggestions, your input is valuable.
-
-The most useful contributions are testing prereleases on your hardware, filing clear bug reports, and opening PRs.
-If you'd rather just say thanks, there's a [Ko-fi](https://ko-fi.com/renjfk). Optional, doesn't influence the
-roadmap, the project stays free and community-driven either way.
-
-> [!TIP]
-> Before opening an issue, consider starting a [Discussion](https://github.com/renjfk/OpenNeato/discussions) first —
-> many questions, setup troubles, and ideas are easier to resolve through conversation.
-
-> [!IMPORTANT]
-> For anything beyond a small bug fix, please open an issue
-> or [Discussion](https://github.com/renjfk/OpenNeato/discussions) first to align on the design before writing code.
-> This is an embedded project with tight resource constraints (single-core MCU, 320 KB RAM, 1.6 MB flash per OTA slot)
-> and strict architectural rules (non-blocking event loop, zero external dependencies). A quick design conversation
-> upfront avoids large rewrites during review.
-
-### Issue Conventions
-
-When creating issues, please follow our simple naming convention:
-
-**Format:** `type: brief description`
-
-#### Issue Types
-
-- `feat:` - New features or functionality
-- `fix:` - Bug fixes
-- `enhance:` - Improvements to existing features
-- `chore:` - Maintenance tasks, dependencies, cleanup
-- `docs:` - Documentation updates
-- `build:` - Build system, CI/CD changes
-
-#### Examples
-
-- `feat: add CSV export functionality`
-- `fix: app crashes when importing large files`
-- `enhance: improve data loading performance`
-- `chore: update dependencies to latest versions`
-- `docs: update README with installation instructions`
-- `build: update Xcode project settings`
-
-#### Guidelines
-
-- Use lowercase for the description
-- Be specific and actionable
-- Keep under 60 characters
-- No period at the end
-
-## Development
-
-For frontend development without hardware, use the mock API scenarios documented in
-[`docs/mock-scenarios.md`](docs/mock-scenarios.md). The same `?scenario=...` URLs work in local Vite dev and the
-Cloudflare demo.
-
-### Release Process
-
-Manual releases via opencode; see [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
-
-Prereleases can be triggered from any PR by commenting `/prerelease` (collaborators only).
-
-## License
-
-This project is licensed under the [MIT License](LICENSE).
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Latest Release](https://img.shields.io/github/v/release/Leicas/OpenNeato)](https://github.com/Leicas/OpenNeato/releases/latest)
+[![Upstream](https://img.shields.io/badge/upstream-renjfk%2FOpenNeato-blue)](https://github.com/renjfk/OpenNeato)
+
+<p align="center">
+ <img width="192" alt="OpenNeato Icon" src="frontend/public/icon-192.png">
+</p>
+
+# OpenNeato — Home Assistant fork
+
+**This is a [Leicas/OpenNeato](https://github.com/Leicas/OpenNeato) fork focused on the Home Assistant
+integration.** The HACS-installable integration under
+[`custom_components/openneato/`](custom_components/openneato/) is the reason this fork exists — it turns the
+upstream ESP32 bridge into a full HA device with vacuum / camera / sensor / switch / button entities, no YAML.
+
+> [!IMPORTANT]
+> **If you want the standalone web UI**, use upstream [renjfk/OpenNeato](https://github.com/renjfk/OpenNeato)
+> directly — it has the original maintainer, the release cadence, and the live demo.
+>
+> **Use this fork if** you run Home Assistant and want the robot exposed as a first-class HA device. Firmware
+> changes in this fork are minor and exist only to support the integration (e.g. `/api/sensors`,
+> `/api/history` hardening, ntfy server/token/on-start extensions). The firmware, frontend, and flash tool
+> otherwise track upstream closely.
+
+The upstream project is an open-source replacement for Neato's discontinued cloud and mobile app: an ESP32
+bridge that talks to Botvac robots (D3-D7) over UART and exposes a local web UI over WiFi — no cloud, no app,
+no account required.
+
+> [!NOTE]
+> Both upstream and this fork are early beta. Rough edges are expected. For HA-integration bugs, open an
+> [issue here](https://github.com/Leicas/OpenNeato/issues); for firmware/frontend/flash-tool bugs, file
+> against [upstream](https://github.com/renjfk/OpenNeato/issues).
+
+> [!TIP]
+> Want to get a feel for the underlying web UI without hardware? Open the upstream
+> [live demo](https://openneato-demo.renjfk.com/). Demo states can be selected with `?scenario=...`; see
+> [mock scenarios](docs/mock-scenarios.md).
+
+|                Dashboard                 |                  Manual Drive                  |                    Cleaning History                    |
+|:----------------------------------------:|:----------------------------------------------:|:------------------------------------------------------:|
+| ![Dashboard](screenshots/dashboard.webp) | ![Manual Drive](screenshots/manual-drive.webp) | ![Cleaning History](screenshots/cleaning-history.webp) |
+
+|                Clean Map                 |                Schedule                |                Settings                |
+|:----------------------------------------:|:--------------------------------------:|:--------------------------------------:|
+| ![Clean Map](screenshots/clean-map.webp) | ![Schedule](screenshots/schedule.webp) | ![Settings](screenshots/settings.webp) |
+
+## About the underlying project (upstream)
+
+The sections below describe the upstream [renjfk/OpenNeato](https://github.com/renjfk/OpenNeato) project that
+this fork builds on — the ESP32 bridge firmware, standalone web UI, and flash tool. **None of this is unique
+to this fork**; it's reproduced here so HA users have full context on what's running behind the integration.
+If you only want the HA bits, you can skip ahead to the [Home Assistant section](#home-assistant-integration)
+below.
+
+Neato shut down their cloud services and mobile app, leaving perfectly functional robot vacuums without remote
+control or scheduling. OpenNeato brings them back to life with a small ESP32 board wired to the robot's debug
+port, giving you a local web interface that works without any external dependencies.
+
+### Upstream web UI features
+
+- **Dashboard** with live robot status, battery level, cleaning state, WiFi signal, and storage usage
+- **House and spot cleaning** with pause/resume/stop/dock controls that adapt to the current state
+- **Manual driving mode** with a virtual joystick, live LIDAR map visualization, motor toggles (brush, vacuum, side
+  brush), bumper/wheel-lift/stall safety warnings
+- **Live cleaning map** — watch the robot's path during an active cleaning session in the History view, rendered on a
+  canvas with coverage overlay
+- **7-day cleaning scheduler** with two slots per day, managed entirely on the ESP32 (doesn't use the robot's built-in
+  schedule commands)
+- **Cleaning history** with recorded robot paths rendered as coverage maps, session stats like duration, distance, area
+  covered, and battery usage; individual session import/export for backup and restore
+- **Push notifications** via [ntfy.sh](https://ntfy.sh); get notified when cleaning is done, an error occurs, a
+  maintenance alert triggers, or the robot docks; fully optional, configurable per event
+- **OTA firmware updates** from the browser with SHA-256 download verification (against published `checksums.txt`), MD5
+  transfer integrity, dual-partition layout with auto-rollback, and automatic new version notifications when a release
+  is available on GitHub
+- **Settings page** for hostname, timezone, motor presets, notification topics, UART pins, theme (dark/light/auto),
+  battery diagnostics (cycle count, voltage, temperature, and a "New Battery" calibration trigger), and more
+- **Event logging** with configurable log levels (off/info/debug), compressed JSONL files on SPIFFS, browsable and
+  downloadable from the UI; optional remote syslog (UDP) for long-running diagnostics without flash wear; logging is
+  off by default
+- **Factory reset** via 5-second button hold on the ESP32 or from the settings page
+- **Robot clock sync** — pushes NTP time to the robot automatically, re-syncs every 4 hours
+- **Flash tool** — standalone CLI that auto-detects the USB port, downloads the correct firmware from GitHub Releases,
+  and flashes with zero prerequisites
+- **Safety watchdog** — auto-stops wheels in manual mode if the browser disconnects; task and heap watchdogs restart the
+  ESP32 on hangs
+- **Crash recovery** — orphaned cleaning sessions after unexpected reboots are automatically recovered with full stats
+
+The frontend is a lightweight SPA that gets gzipped and embedded directly into the firmware binary, so a single
+OTA update covers both firmware and UI. Mobile-friendly, dark theme by default.
+
+## Home Assistant Integration
+
+This fork ships a HACS-installable Home Assistant custom integration in
+[`custom_components/openneato/`](custom_components/openneato/). Once installed it discovers your OpenNeato bridge
+by IP/hostname and exposes the robot as a full HA device — no YAML, no extra add-ons.
+
+> [!NOTE]
+> The HA integration is the primary differentiator of this fork. The firmware, frontend, and flash tool track
+> upstream [`renjfk/OpenNeato`](https://github.com/renjfk/OpenNeato) closely. If you only want the standalone web
+> UI, use upstream directly.
+
+### Install via HACS
+
+1. In HACS, add this fork as a **custom repository**: `https://github.com/Leicas/OpenNeato` (category:
+   *Integration*).
+2. Search for **OpenNeato** in HACS and install.
+3. Restart Home Assistant.
+4. **Settings → Devices & Services → Add Integration → OpenNeato** and enter the bridge hostname or IP
+   (e.g. `neato.local` or `192.168.1.42`).
+
+The integration polls `/api/*` over your LAN every 5 seconds (`local_polling`). No cloud round-trip, no
+external dependencies. Requires firmware `1.0+`; battery diagnostics need firmware `0.13+` (upstream PR #121).
+
+### What you get
+
+A single device with the following entity groups:
+
+- **Vacuum** (`vacuum.openneato_<name>`) — start/stop/pause/dock/locate/spot-clean, battery level, status,
+  fan speed presets (Eco/Auto/Intense), error reporting. Works with all the standard vacuum cards.
+- **Cameras** — `LIDAR map` (live 360° scan during cleaning) and `Cleaning replay` (animated GIF time-lapse
+  of the most recent completed session). Both are standard HA camera entities, compatible with
+  picture-entity, picture-glance, and vacuum-card.
+- **Sensors** — battery level/voltage/current/temperature, battery cycle count, cumulative cleaning time,
+  WiFi RSSI, free heap, storage used, uptime, motor RPMs, error code/message, plus "last clean" stats
+  (duration, area covered, distance, battery used, mode, end time) pulled from the on-device history.
+- **Binary sensors** — charging, external power, battery over-temp, battery failure, empty fuel, error
+  active, NTP synced, dustbin seated, left/right wheel lifted, dock contact.
+- **Switches** — eco mode, intense clean, bin-full detect, wall follower, schedule on/off, button-click
+  sounds, melodies, warnings, stealth LED, remote syslog, WiFi AP fallback, and per-event push
+  notifications (start/done/error/alert/docking).
+- **Text** — syslog server IP, ntfy topic, ntfy server, ntfy token (full push-notification config from HA).
+- **Numbers** — brush RPM, vacuum speed, side-brush power, stall threshold.
+- **Select** — navigation mode (Normal / Gentle / Deep / Quick).
+- **Buttons** — restart bridge, restart robot, shutdown robot, locate, clear errors, format filesystem
+  (diagnostic, disabled by default), **new battery** (resets fuel-gauge calibration after a physical pack
+  swap, disabled by default for safety).
+
+Every entity is translated via `strings.json`, and diagnostic-class entities (voltages, currents, raw
+sensor states) are tagged so they cluster cleanly under HA's Diagnostic section.
+
+### Notes for setup
+
+- **Camera entities and vacuum-card** — the `LIDAR map` camera self-manages a 2 s `/api/lidar` poll only
+  while the robot is actively cleaning, so it doesn't add load to the coordinator's 5 s cycle. When idle,
+  both cameras fall back to the most recent completed cleaning map.
+- **Coordinator resilience** — the integration tolerates a single hung endpoint without going into
+  "requires attention" state. State / charger / system are critical; anything else (errors, motors,
+  history) falls back to the last known value during transient ESP32 serial hangs.
+- **No Pillow declared dependency** — map rendering uses Pillow which already ships with HA Core, so the
+  integration's `manifest.json` keeps `"requirements": []`. Nothing extra to install.
+- **ntfy + custom servers** — point `ntfy_server` at a self-hosted instance and `ntfy_token` at a Bearer
+  token for authenticated push. Empty server defaults to `ntfy.sh`; empty token is unauthenticated.
+
+### Version history
+
+Full per-version notes live in [`custom_components/openneato/CHANGELOG.md`](custom_components/openneato/CHANGELOG.md).
+Highlights:
+
+- **1.11** — added `notify_on_start` and `ap_fallback_on_disconnect` switches; ntfy topic/server/token text
+  entities for full HA-side push config.
+- **1.10** — battery diagnostics (current, voltage, cycles, cumulative cleaning time) on top of firmware
+  PR #121, `New battery` calibration button, UTF-8-tolerant `/api/version` parsing.
+- **1.9** — fixed cameras stuck on the idle placeholder (`get_encoding()` crash on streamed bodies).
+- **1.6** — `Cleaning replay` camera (animated GIF time-lapse), `/api/history` corruption-tolerant parsing,
+  history filename validation + 2 MB response cap (LAN-MITM mitigation).
+- **1.3** — `LIDAR map` camera ported from the frontend renderer; self-managed polling.
+- **1.2** — last-clean stats sensors; dropped Pillow from declared deps.
+
+### Reporting integration bugs
+
+Use this fork's [issue tracker](https://github.com/Leicas/OpenNeato/issues) for anything that lives under
+`custom_components/openneato/`. For firmware, frontend, or flash-tool issues, upstream
+[renjfk/OpenNeato](https://github.com/renjfk/OpenNeato/issues) is the right place.
+
+## Supported Robots
+
+Neato Botvac D3 through D7. D8/D9/D10 are NOT supported (different board, password-locked serial port).
+
+## Installation
+
+### Requirements
+
+- ESP32-C3, ESP32-S3, or original ESP32 board with **4 MB flash** (any dev board with USB and exposed GPIOs)
+
+### Quick Start
+
+1. Download the latest release from the [Releases](https://github.com/renjfk/OpenNeato/releases) page
+2. Flash the ESP32 using the flash tool (auto-detects your chip type):
+   ```bash
+   openneato-flash
+   ```
+3. Configure your home WiFi via the serial menu (opens automatically after flashing)
+4. Wire the ESP32 to your robot's debug port
+5. Open the web UI at `http://neato.local` or the IP shown in the serial monitor
+
+For detailed instructions and troubleshooting, see the [User Guide](docs/user-guide.md).
+
+### Building from Source
+
+Requires [Node.js](https://nodejs.org/) 22+, [PlatformIO CLI](https://platformio.org/install/cli),
+and [Go](https://go.dev/) 1.26+.
+
+```bash
+git clone https://github.com/renjfk/OpenNeato.git
+cd OpenNeato
+
+# Build frontend (generates web_assets.h)
+cd frontend && npm ci && npm run build && cd ..
+
+# Build firmware
+pio run -e c3-release
+
+# Build flash tool
+cd flash && go build -o openneato-flash . && cd ..
+```
+
+## Contributing
+
+OpenNeato is open to contributions and ideas! Whether you're a developer wanting to add features or a user with
+suggestions, your input is valuable.
+
+The most useful contributions are testing prereleases on your hardware, filing clear bug reports, and opening PRs.
+If you'd rather just say thanks, there's a [Ko-fi](https://ko-fi.com/renjfk). Optional, doesn't influence the
+roadmap, the project stays free and community-driven either way.
+
+> [!TIP]
+> Before opening an issue, consider starting a [Discussion](https://github.com/renjfk/OpenNeato/discussions) first —
+> many questions, setup troubles, and ideas are easier to resolve through conversation.
+
+> [!IMPORTANT]
+> For anything beyond a small bug fix, please open an issue
+> or [Discussion](https://github.com/renjfk/OpenNeato/discussions) first to align on the design before writing code.
+> This is an embedded project with tight resource constraints (single-core MCU, 320 KB RAM, 1.6 MB flash per OTA slot)
+> and strict architectural rules (non-blocking event loop, zero external dependencies). A quick design conversation
+> upfront avoids large rewrites during review.
+
+### Issue Conventions
+
+When creating issues, please follow our simple naming convention:
+
+**Format:** `type: brief description`
+
+#### Issue Types
+
+- `feat:` - New features or functionality
+- `fix:` - Bug fixes
+- `enhance:` - Improvements to existing features
+- `chore:` - Maintenance tasks, dependencies, cleanup
+- `docs:` - Documentation updates
+- `build:` - Build system, CI/CD changes
+
+#### Examples
+
+- `feat: add CSV export functionality`
+- `fix: app crashes when importing large files`
+- `enhance: improve data loading performance`
+- `chore: update dependencies to latest versions`
+- `docs: update README with installation instructions`
+- `build: update Xcode project settings`
+
+#### Guidelines
+
+- Use lowercase for the description
+- Be specific and actionable
+- Keep under 60 characters
+- No period at the end
+
+## Development
+
+For frontend development without hardware, use the mock API scenarios documented in
+[`docs/mock-scenarios.md`](docs/mock-scenarios.md). The same `?scenario=...` URLs work in local Vite dev and the
+Cloudflare demo.
+
+### Release Process
+
+Manual releases via opencode; see [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
+
+Prereleases can be triggered from any PR by commenting `/prerelease` (collaborators only).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

From cf0d6908062324f56428d151e67af5cb87cb998f Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:02:09 -0400
Subject: [PATCH 39/44] style(firmware): clang-format pass on fork-added
 sources (CI gate)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI's clang-format check failed against the fork's firmware sources — these
files had never been clang-formatted (the verification ran on Windows where
clang-format isn't on PATH, so the check_format script silently skipped).
Running 'python scripts/check_format.py --fix' under an ad-hoc clang-format
22 (installed in .venv-cf via uv) brought 4 files into compliance:
neato_serial.cpp, notification_manager.{cpp,h}, web_server.cpp — each just
collapsing a 2-line statement onto one because ColumnLimit=120 allows it.

Most of the diff stat is line-ending normalization: the fork files were
CRLF on disk and clang-format outputs LF (no LineEnding override in the
.clang-format config). 'git diff -w' shows the real code delta is 13 lines
across 4 files; the remaining ~6600 'changes' are pure CRLF -> LF.

Files touched: cleaning_history.{cpp,h}, neato_serial.cpp,
notification_manager.{cpp,h}, system_manager.cpp, web_server.cpp.
---
 firmware/src/cleaning_history.cpp     | 2598 ++++++++++++-------------
 firmware/src/cleaning_history.h       |  396 ++--
 firmware/src/neato_serial.cpp         | 1587 ++++++++-------
 firmware/src/notification_manager.cpp |  472 ++---
 firmware/src/notification_manager.h   |  117 +-
 firmware/src/system_manager.cpp       |  386 ++--
 firmware/src/web_server.cpp           | 1077 +++++-----
 7 files changed, 3315 insertions(+), 3318 deletions(-)

diff --git a/firmware/src/cleaning_history.cpp b/firmware/src/cleaning_history.cpp
index b68e7ed..25477a3 100644
--- a/firmware/src/cleaning_history.cpp
+++ b/firmware/src/cleaning_history.cpp
@@ -1,1299 +1,1299 @@
-#include "cleaning_history.h"
-#include "json_fields.h"
-#include "neato_serial.h"
-#include "system_manager.h"
-#include <SPIFFS.h>
-#include <cmath>
-
-// Heatshrink decompression can drop a byte that merges two JSONL lines into
-// one, so substring matching isn't enough — validate the braces balance and
-// nothing trails the top-level object before embedding into /api/history.
-static bool isValidMetaLine(const String& line, const char* expectedTypePrefix) {
-    if (line.length() < 2 || line[0] != '{' || line[line.length() - 1] != '}')
-        return false;
-    if (line.indexOf(expectedTypePrefix) < 0)
-        return false;
-    int depth = 0;
-    bool inString = false;
-    bool escape = false;
-    for (size_t i = 0; i < line.length(); i++) {
-        char c = line[i];
-        if (escape) {
-            escape = false;
-            continue;
-        }
-        if (inString) {
-            if (c == '\\')
-                escape = true;
-            else if (c == '"')
-                inString = false;
-            continue;
-        }
-        if (c == '"')
-            inString = true;
-        else if (c == '{')
-            depth++;
-        else if (c == '}') {
-            depth--;
-            if (depth < 0)
-                return false;
-            // Reject trailing content after the top-level object closes
-            if (depth == 0 && i != line.length() - 1)
-                return false;
-        }
-    }
-    return depth == 0 && !inString;
-}
-
-CleaningHistory::CleaningHistory(NeatoSerial& neato, DataLogger& logger, SystemManager& sysMgr) :
-    LoopTask(HISTORY_INTERVAL_IDLE_MS), neato(neato), dataLogger(logger), systemManager(sysMgr) {
-    TaskRegistry::add(this);
-}
-
-void CleaningHistory::notifyCleanStart() {
-    if (collecting)
-        return; // Already recording
-    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
-}
-
-void CleaningHistory::tick() {
-    // Run incremental compression when a session just finished
-    if (compressing) {
-        if (compressStep()) {
-            // Compression done - remove raw source and cache metadata
-            compressSrc.close();
-            compressDst.close();
-            SPIFFS.remove(compressSrcPath);
-            LOG("HIST", "Compression done: %s", compressDstPath.c_str());
-
-            // Cache session/summary from memory (avoids decompressing on next list request)
-            String hsName = compressDstPath;
-            int lastSlash = hsName.lastIndexOf('/');
-            if (lastSlash >= 0)
-                hsName = hsName.substring(lastSlash + 1);
-            metaCache[hsName] = {pendingSessionJson, pendingSummaryJson};
-            pendingSessionJson = "";
-            pendingSummaryJson = "";
-
-            compressing = false;
-            setInterval(HISTORY_INTERVAL_IDLE_MS);
-        }
-        return;
-    }
-
-    if (fetchPending)
-        return;
-
-    if (collecting) {
-        // Periodically flush buffered pose snapshots to disk
-        if (!writeBuffer.empty() && millis() - lastFlushMs >= HISTORY_FLUSH_INTERVAL_MS) {
-            flushWriteBuffer();
-        }
-        collectSnapshot();
-    } else {
-        checkState();
-        enforceLimits();
-    }
-}
-
-// -- State watching (idle mode) ----------------------------------------------
-
-void CleaningHistory::checkState() {
-    fetchPending = true;
-    neato.getState([this](bool ok, const RobotState& state) {
-        fetchPending = false;
-        if (!ok)
-            return;
-
-        bool wasCleaning = isCleaningState(prevUiState);
-        bool nowCleaning = isCleaningState(state.uiState);
-
-        // CLEANINGSUSPENDED + Charging_Cleaning means the robot is on the dock
-        // recharging mid-clean and will resume automatically — treat as active
-        bool isMidCleanRecharge = isSuspendedState(state.uiState) && state.robotState.indexOf("Charging_Cleaning") >= 0;
-
-        // First poll after boot: if the robot is idle, finalize any orphan sessions
-        // left by a previous crash/reboot so they don't get merged into the next clean
-        if (prevUiState.isEmpty() && !nowCleaning && !isMidCleanRecharge && !recoveryAttempted) {
-            recoveryAttempted = true;
-            finalizeOrphanSessions();
-        }
-
-        if (!wasCleaning && (nowCleaning || isMidCleanRecharge) && !recoverCollection(state.uiState)) {
-            startCollection(state.uiState);
-        }
-
-        prevUiState = state.uiState;
-    });
-}
-
-bool CleaningHistory::isCleaningState(const String& uiState) {
-    return uiState.indexOf("HOUSECLEANINGRUNNING") >= 0 || uiState.indexOf("HOUSECLEANINGPAUSED") >= 0 ||
-           uiState.indexOf("SPOTCLEANINGRUNNING") >= 0 || uiState.indexOf("SPOTCLEANINGPAUSED") >= 0 ||
-           uiState.indexOf("MANUALCLEANING") >= 0;
-}
-
-bool CleaningHistory::isPausedState(const String& uiState) {
-    return uiState.indexOf("CLEANINGPAUSED") >= 0;
-}
-
-bool CleaningHistory::isDockingState(const String& uiState) {
-    return uiState.indexOf("DOCKING") >= 0;
-}
-
-bool CleaningHistory::isSuspendedState(const String& uiState) {
-    return uiState.indexOf("CLEANINGSUSPENDED") >= 0;
-}
-
-String CleaningHistory::cleanModeFromState(const String& uiState) {
-    if (uiState.indexOf("HOUSECLEANING") >= 0)
-        return "house";
-    if (uiState.indexOf("SPOTCLEANING") >= 0)
-        return "spot";
-    if (uiState.indexOf("MANUALCLEANING") >= 0)
-        return "manual";
-    return "unknown";
-}
-
-void CleaningHistory::resetSession() {
-    snapshotCount = 0;
-    rechargeCount = 0;
-    totalDistance = 0.0f;
-    totalRotation = 0.0f;
-    maxDistFromOrigin = 0.0f;
-    errorsDuringClean = 0;
-    prevHadError = false;
-    hasPrevPose = false;
-    prevX = 0.0f;
-    prevY = 0.0f;
-    prevTheta = 0.0f;
-    originX = 0.0f;
-    originY = 0.0f;
-    visitedCells.clear();
-    cleanMode = "";
-    sessionStartTime = 0;
-    batteryStart = -1;
-    recharging = false;
-    pendingSessionJson = "";
-    pendingSummaryJson = "";
-}
-
-void CleaningHistory::startCollection(const String& uiState) {
-    collecting = true;
-    resetSession();
-
-    cleanMode = cleanModeFromState(uiState);
-    sessionStartTime = systemManager.now();
-
-    // Create session file: /history/<epoch>.jsonl
-    activeFilePath = String(HISTORY_DIR) + "/" + String(static_cast<long>(sessionStartTime)) + ".jsonl";
-    activeFile = SPIFFS.open(activeFilePath, FILE_WRITE);
-    if (!activeFile) {
-        LOG("HIST", "Failed to create session file: %s", activeFilePath.c_str());
-        collecting = false;
-        return;
-    }
-
-    // Fetch battery level for session metadata, then write header
-    neato.getCharger([this](bool ok, const ChargerData& charger) {
-        if (ok) {
-            batteryStart = charger.fuelPercent;
-        }
-        writeSessionHeader();
-    });
-
-    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
-    LOG("HIST", "Collection started (mode: %s, file: %s)", cleanMode.c_str(), activeFilePath.c_str());
-    dataLogger.logGenericEvent("history_start", {{"mode", cleanMode, FIELD_STRING}});
-}
-
-void CleaningHistory::stopCollection() {
-    // Flush any buffered snapshots before writing summary
-    flushWriteBuffer();
-
-    // Discard sessions that are too short to produce a useful map
-    if (snapshotCount < HISTORY_MIN_SNAPSHOTS) {
-        if (activeFile) {
-            activeFile.close();
-        }
-        SPIFFS.remove(activeFilePath);
-
-        LOG("HIST", "Session discarded (%u snapshots < %d minimum)", snapshotCount, HISTORY_MIN_SNAPSHOTS);
-        dataLogger.logGenericEvent("history_discard", {{"snapshots", String(snapshotCount), FIELD_INT}});
-
-        // Mark stats invalid so NotificationManager doesn't enrich a "done"
-        // notification with stale data from the previous session.
-        lastCleanStats.valid = false;
-        lastCleanStats.sessionId = ++sessionCounter;
-
-        collecting = false;
-        recharging = false;
-        setInterval(HISTORY_INTERVAL_IDLE_MS);
-        return;
-    }
-
-    // Fetch final battery level for summary
-    neato.getCharger([this](bool ok, const ChargerData& charger) {
-        int batteryEnd = ok ? charger.fuelPercent : -1;
-
-        writeSessionSummary(batteryEnd);
-
-        // Close the raw file
-        if (activeFile) {
-            activeFile.close();
-        }
-
-        collecting = false;
-        recharging = false;
-        setInterval(HISTORY_INTERVAL_IDLE_MS);
-
-        float areaCovered = static_cast<float>(visitedCells.size()) * HISTORY_AREA_CELL_M * HISTORY_AREA_CELL_M;
-
-        // Snapshot stats for notification enrichment (survives resetSession).
-        // sessionId increments last so NotificationManager can detect that
-        // the async charger fetch above has finalized the stats.
-        time_t endTime = systemManager.now();
-        lastCleanStats.valid = true;
-        lastCleanStats.mode = cleanMode;
-        lastCleanStats.durationSec = (sessionStartTime > 0 && endTime > sessionStartTime)
-                                         ? static_cast<long>(endTime - sessionStartTime)
-                                         : 0;
-        lastCleanStats.areaCoveredM2 = areaCovered;
-        lastCleanStats.distanceM = totalDistance;
-        lastCleanStats.batteryStart = batteryStart;
-        lastCleanStats.batteryEnd = batteryEnd;
-        lastCleanStats.recharges = rechargeCount;
-        lastCleanStats.sessionId = ++sessionCounter;
-
-        LOG("HIST", "Collection stopped (%u snapshots, %.1fm², %d recharges)", snapshotCount, areaCovered,
-            rechargeCount);
-        dataLogger.logGenericEvent("history_stop", {{"snapshots", String(snapshotCount), FIELD_INT},
-                                                    {"area_m2", String(areaCovered, 1), FIELD_FLOAT},
-                                                    {"recharges", String(rechargeCount), FIELD_INT},
-                                                    {"battery_end", String(batteryEnd), FIELD_INT}});
-
-        // Start non-blocking compression: raw .jsonl -> .jsonl.hs
-        compressSrcPath = activeFilePath;
-        compressDstPath = activeFilePath + ".hs";
-        compressSrc = SPIFFS.open(compressSrcPath, FILE_READ);
-        compressDst = SPIFFS.open(compressDstPath, FILE_WRITE);
-        if (compressSrc && compressDst) {
-            heatshrink_encoder_reset(&compressEncoder);
-            compressInputDone = false;
-            compressing = true;
-            setInterval(HISTORY_COMPRESS_INTERVAL_MS);
-            LOG("HIST", "Starting compression: %s -> %s", compressSrcPath.c_str(), compressDstPath.c_str());
-        } else {
-            // Compression failed - keep raw file
-            if (compressSrc)
-                compressSrc.close();
-            if (compressDst)
-                compressDst.close();
-            LOG("HIST", "Compression setup failed, keeping raw file");
-        }
-    });
-}
-
-// -- Incremental compression (called from tick) ------------------------------
-
-bool CleaningHistory::compressStep() {
-    static const size_t CHUNK_SIZE = 512;
-    uint8_t inBuf[CHUNK_SIZE];
-    uint8_t outBuf[CHUNK_SIZE];
-
-    if (!compressInputDone) {
-        int bytesRead = compressSrc.read(inBuf, CHUNK_SIZE);
-        if (bytesRead <= 0) {
-            compressInputDone = true;
-        } else {
-            size_t offset = 0;
-            while (offset < static_cast<size_t>(bytesRead)) {
-                size_t sunk = 0;
-                HSE_sink_res sres =
-                        heatshrink_encoder_sink(&compressEncoder, inBuf + offset, bytesRead - offset, &sunk);
-                if (sres < 0) {
-                    LOG("HIST", "Heatshrink sink error");
-                    compressSrc.close();
-                    compressDst.close();
-                    SPIFFS.remove(compressDstPath);
-                    compressing = false;
-                    return true;
-                }
-                offset += sunk;
-
-                size_t outSz = 0;
-                HSE_poll_res pres;
-                do {
-                    pres = heatshrink_encoder_poll(&compressEncoder, outBuf, CHUNK_SIZE, &outSz);
-                    if (pres < 0) {
-                        LOG("HIST", "Heatshrink poll error");
-                        compressSrc.close();
-                        compressDst.close();
-                        SPIFFS.remove(compressDstPath);
-                        compressing = false;
-                        return true;
-                    }
-                    if (outSz > 0) {
-                        compressDst.write(outBuf, outSz);
-                    }
-                } while (pres == HSER_POLL_MORE);
-            }
-        }
-        return false;
-    }
-
-    // Input exhausted — finish encoding
-    HSE_finish_res fres = heatshrink_encoder_finish(&compressEncoder);
-    if (fres < 0) {
-        LOG("HIST", "Heatshrink finish error");
-        compressSrc.close();
-        compressDst.close();
-        SPIFFS.remove(compressDstPath);
-        compressing = false;
-        return true;
-    }
-
-    size_t outSz = 0;
-    HSE_poll_res pres;
-    do {
-        pres = heatshrink_encoder_poll(&compressEncoder, outBuf, CHUNK_SIZE, &outSz);
-        if (pres < 0) {
-            LOG("HIST", "Heatshrink poll error during finish");
-            compressSrc.close();
-            compressDst.close();
-            SPIFFS.remove(compressDstPath);
-            compressing = false;
-            return true;
-        }
-        if (outSz > 0) {
-            compressDst.write(outBuf, outSz);
-        }
-    } while (pres == HSER_POLL_MORE);
-
-    return (fres == HSER_FINISH_DONE);
-}
-
-// -- Session header/summary --------------------------------------------------
-
-void CleaningHistory::writeSessionHeader() {
-    std::vector<Field> fields = {{"type", "session", FIELD_STRING}, {"mode", cleanMode, FIELD_STRING}};
-    if (sessionStartTime > 0)
-        fields.push_back({"time", String(static_cast<long>(sessionStartTime)), FIELD_INT});
-    if (batteryStart >= 0)
-        fields.push_back({"battery", String(batteryStart), FIELD_INT});
-    String json = fieldsToJson(fields);
-    pendingSessionJson = json;
-    writeLine(json);
-}
-
-void CleaningHistory::writeSessionSummary(int batteryEnd) {
-    time_t endTime = systemManager.now();
-    long duration =
-            (sessionStartTime > 0 && endTime > sessionStartTime) ? static_cast<long>(endTime - sessionStartTime) : 0;
-    float areaCovered = static_cast<float>(visitedCells.size()) * HISTORY_AREA_CELL_M * HISTORY_AREA_CELL_M;
-    std::vector<Field> fields = {{"type", "summary", FIELD_STRING}};
-    if (endTime > 0)
-        fields.push_back({"time", String(static_cast<long>(endTime)), FIELD_INT});
-    fields.push_back({"duration", String(duration), FIELD_INT});
-    fields.push_back({"mode", cleanMode, FIELD_STRING});
-    fields.push_back({"recharges", String(rechargeCount), FIELD_INT});
-    fields.push_back({"snapshots", String(static_cast<int>(snapshotCount)), FIELD_INT});
-    fields.push_back({"distanceTraveled", String(totalDistance, 2), FIELD_FLOAT});
-    fields.push_back({"maxDistFromOrigin", String(maxDistFromOrigin, 2), FIELD_FLOAT});
-    fields.push_back({"totalRotation", String(totalRotation, 1), FIELD_FLOAT});
-    fields.push_back({"areaCovered", String(areaCovered, 2), FIELD_FLOAT});
-    fields.push_back({"errorsDuringClean", String(errorsDuringClean), FIELD_INT});
-    if (batteryStart >= 0)
-        fields.push_back({"batteryStart", String(batteryStart), FIELD_INT});
-    if (batteryEnd >= 0)
-        fields.push_back({"batteryEnd", String(batteryEnd), FIELD_INT});
-    String json = fieldsToJson(fields);
-    pendingSummaryJson = json;
-    writeLine(json);
-}
-
-// -- Buffered file writing ---------------------------------------------------
-// Pose snapshots accumulate in writeBuffer; flushed every HISTORY_FLUSH_INTERVAL_MS
-// or when the session ends (stopCollection / recovery). This reduces flash wear
-// from one write every 2s to one write every 30s during a cleaning session.
-// Session header, summary, and recharge markers flush immediately since they
-// are rare one-shot writes where crash safety matters.
-
-void CleaningHistory::writeLine(const String& line) {
-    if (!activeFile)
-        return;
-    activeFile.println(line);
-    activeFile.flush();
-}
-
-void CleaningHistory::bufferLine(const String& line) {
-    if (!activeFile)
-        return;
-    writeBuffer.push_back(line);
-}
-
-void CleaningHistory::flushWriteBuffer() {
-    if (writeBuffer.empty() || !activeFile)
-        return;
-    // Build a single string and write once to minimize SPIFFS COW metadata updates
-    String batch;
-    size_t total = 0;
-    for (const auto& line: writeBuffer) {
-        total += line.length() + 1;
-    }
-    batch.reserve(total);
-    for (const auto& line: writeBuffer) {
-        batch += line;
-        batch += '\n';
-    }
-    activeFile.write(reinterpret_cast<const uint8_t *>(batch.c_str()), batch.length());
-    activeFile.flush();
-    writeBuffer.clear();
-    lastFlushMs = millis();
-}
-
-// -- Snapshot collection (active mode) ---------------------------------------
-
-static bool parsePose(const String& raw, float& x, float& y, float& theta, float& time) {
-    int xPos = raw.indexOf("X=");
-    int yPos = raw.indexOf("Y=");
-    int tPos = raw.indexOf("Theta=");
-    int tmPos = raw.indexOf("Time=");
-    if (xPos < 0 || yPos < 0 || tPos < 0 || tmPos < 0)
-        return false;
-
-    x = raw.substring(xPos + 2).toFloat();
-    y = raw.substring(yPos + 2).toFloat();
-    theta = raw.substring(tPos + 6).toFloat();
-    time = raw.substring(tmPos + 5).toFloat();
-    return true;
-}
-
-// Parse a single JSONL line and update session accumulators (header, recharge, pose).
-// Returns true if the line was a session header.
-bool CleaningHistory::replayLine(const String& line) {
-    auto fields = fieldsFromJson(line);
-    if (fields.empty())
-        return false;
-
-    const Field *typeField = findField(fields, "type");
-    if (typeField && typeField->value == "session") {
-        const Field *modeField = findField(fields, "mode");
-        if (modeField && !modeField->value.isEmpty())
-            cleanMode = modeField->value;
-
-        const Field *timeField = findField(fields, "time");
-        if (timeField) {
-            long t = timeField->value.toInt();
-            if (t > 0)
-                sessionStartTime = static_cast<time_t>(t);
-        }
-
-        const Field *battField = findField(fields, "battery");
-        if (battField)
-            batteryStart = battField->value.toInt();
-        return true;
-    }
-
-    if (typeField && typeField->value == "recharge") {
-        rechargeCount++;
-        return false;
-    }
-
-    // Pose snapshot line
-    const Field *xf = findField(fields, "x");
-    const Field *yf = findField(fields, "y");
-    const Field *tf = findField(fields, "t");
-    if (xf && yf && tf) {
-        updateAccumulators(xf->value.toFloat(), yf->value.toFloat(), tf->value.toFloat());
-        snapshotCount++;
-    }
-    return false;
-}
-
-bool CleaningHistory::recoverCollection(const String& uiState) {
-    // Only attempt recovery once after boot — avoid scanning filesystem on every clean start
-    if (recoveryAttempted)
-        return false;
-    recoveryAttempted = true;
-
-    File root = SPIFFS.open(HISTORY_DIR);
-    if (!root || !root.isDirectory())
-        return false;
-
-    // Collect all history filenames (both .jsonl and .jsonl.hs) and sort descending
-    // (newest first). Then walk from newest to oldest: collect orphan .jsonl files
-    // until we hit a compressed .jsonl.hs — that marks a completed session boundary,
-    // so everything older belongs to previous cleans and should not be touched.
-    // Also clean up any raw .jsonl that has a .jsonl.hs counterpart (stale leftover).
-    std::vector<String> allFiles;
-    File entry = root.openNextFile();
-    while (entry) {
-        String path = String(entry.path());
-        if (path.endsWith(".jsonl") || path.endsWith(".jsonl.hs"))
-            allFiles.push_back(path);
-        entry = root.openNextFile();
-    }
-
-    std::sort(allFiles.begin(), allFiles.end(), [](const String& a, const String& b) { return a > b; });
-
-    std::vector<String> orphans;
-    for (const auto& path: allFiles) {
-        if (path.endsWith(".jsonl.hs")) {
-            // Hit a compressed file — this is the boundary of a completed session.
-            // Stop collecting; everything older is from previous cleans.
-            break;
-        }
-        // Raw .jsonl — check if a compressed copy exists (stale leftover)
-        if (SPIFFS.exists(path + ".hs")) {
-            SPIFFS.remove(path);
-            LOG("HIST", "Removed stale raw file: %s (compressed copy exists)", path.c_str());
-            continue;
-        }
-        // Check if it has a summary (completed but not yet compressed)
-        String firstLine, lastLine;
-        readFirstLastLines(path, false, firstLine, lastLine);
-        if (lastLine.indexOf("\"type\":\"summary\"") >= 0)
-            continue;
-        orphans.push_back(path);
-    }
-
-    if (orphans.empty())
-        return false;
-
-    // orphans are newest-first; reverse to get chronological order (oldest first)
-    std::reverse(orphans.begin(), orphans.end());
-
-    // The oldest orphan becomes the target; newer ones are merged into it then deleted
-    String targetPath = orphans[0];
-
-    if (orphans.size() > 1) {
-        File target = SPIFFS.open(targetPath, FILE_APPEND);
-        if (target) {
-            for (size_t i = 1; i < orphans.size(); i++) {
-                File src = SPIFFS.open(orphans[i], FILE_READ);
-                if (!src)
-                    continue;
-                while (src.available()) {
-                    String line = src.readStringUntil('\n');
-                    line.trim();
-                    if (line.isEmpty())
-                        continue;
-                    // Skip duplicate session headers from newer orphans
-                    if (line.indexOf("\"type\":\"session\"") >= 0)
-                        continue;
-                    target.println(line);
-                }
-                src.close();
-                SPIFFS.remove(orphans[i]);
-                LOG("HIST", "Merged orphan %s into %s", orphans[i].c_str(), targetPath.c_str());
-            }
-            target.flush();
-            target.close();
-        }
-    }
-
-    // Now replay the merged file to rebuild accumulators
-    resetSession();
-    cleanMode = cleanModeFromState(uiState);
-    activeFilePath = targetPath;
-
-    File recoveryFile = SPIFFS.open(targetPath, FILE_READ);
-    if (!recoveryFile)
-        return false;
-
-    bool hasSessionHeader = false;
-    while (recoveryFile.available()) {
-        String line = recoveryFile.readStringUntil('\n');
-        line.trim();
-        if (line.isEmpty())
-            continue;
-        if (replayLine(line))
-            hasSessionHeader = true;
-    }
-    recoveryFile.close();
-
-    // Fall back to extracting start time from the filename
-    if (sessionStartTime <= 0) {
-        String name = targetPath;
-        int slash = name.lastIndexOf('/');
-        if (slash >= 0)
-            name = name.substring(slash + 1);
-        int dot = name.indexOf('.');
-        if (dot > 0)
-            sessionStartTime = static_cast<time_t>(name.substring(0, dot).toInt());
-    }
-
-    activeFile = SPIFFS.open(activeFilePath, FILE_APPEND);
-    if (!activeFile) {
-        activeFilePath = "";
-        resetSession();
-        return false;
-    }
-
-    collecting = true;
-    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
-    LOG("HIST", "Recovered session: %s (%u snapshots, %zu orphans merged)", activeFilePath.c_str(), snapshotCount,
-        orphans.size());
-    dataLogger.logGenericEvent("history_recover", {{"path", activeFilePath, FIELD_STRING},
-                                                   {"snapshots", String(snapshotCount), FIELD_INT},
-                                                   {"orphans", String(static_cast<int>(orphans.size())), FIELD_INT}});
-
-    if (!hasSessionHeader) {
-        writeSessionHeader();
-    }
-    return true;
-}
-
-void CleaningHistory::finalizeOrphanSessions() {
-    // Called once at boot when the robot is idle. Finds orphan .jsonl files
-    // (no summary line, no compressed counterpart) and finalizes them: replay
-    // to compute summary stats, append summary line, then start compression.
-    File root = SPIFFS.open(HISTORY_DIR);
-    if (!root || !root.isDirectory())
-        return;
-
-    std::vector<String> allFiles;
-    File entry = root.openNextFile();
-    while (entry) {
-        String path = String(entry.path());
-        if (path.endsWith(".jsonl") || path.endsWith(".jsonl.hs"))
-            allFiles.push_back(path);
-        entry = root.openNextFile();
-    }
-
-    std::sort(allFiles.begin(), allFiles.end(), [](const String& a, const String& b) { return a > b; });
-
-    std::vector<String> orphans;
-    for (const auto& path: allFiles) {
-        if (path.endsWith(".jsonl.hs"))
-            break; // Completed session boundary
-        if (SPIFFS.exists(path + ".hs")) {
-            SPIFFS.remove(path);
-            continue;
-        }
-        String firstLine, lastLine;
-        readFirstLastLines(path, false, firstLine, lastLine);
-        if (lastLine.indexOf("\"type\":\"summary\"") >= 0)
-            continue;
-        orphans.push_back(path);
-    }
-
-    if (orphans.empty())
-        return;
-
-    // Finalize each orphan: replay to rebuild stats, write summary, compress
-    for (const auto& orphanPath: orphans) {
-        resetSession();
-
-        // Replay to rebuild accumulators
-        File f = SPIFFS.open(orphanPath, FILE_READ);
-        if (!f)
-            continue;
-        while (f.available()) {
-            String line = f.readStringUntil('\n');
-            line.trim();
-            if (line.isEmpty())
-                continue;
-            replayLine(line);
-        }
-        f.close();
-
-        // Extract start time from filename if not found in header
-        if (sessionStartTime <= 0) {
-            String name = orphanPath;
-            int slash = name.lastIndexOf('/');
-            if (slash >= 0)
-                name = name.substring(slash + 1);
-            int dot = name.indexOf('.');
-            if (dot > 0)
-                sessionStartTime = static_cast<time_t>(name.substring(0, dot).toInt());
-        }
-
-        // Open for append and write summary
-        activeFilePath = orphanPath;
-        activeFile = SPIFFS.open(orphanPath, FILE_APPEND);
-        if (!activeFile)
-            continue;
-
-        writeSessionSummary(-1); // Battery end unknown for interrupted sessions
-        activeFile.close();
-
-        LOG("HIST", "Finalized orphan: %s (%u snapshots)", orphanPath.c_str(), snapshotCount);
-        dataLogger.logGenericEvent("history_finalize", {{"path", orphanPath, FIELD_STRING},
-                                                        {"snapshots", String(snapshotCount), FIELD_INT}});
-
-        // Queue compression (only one at a time — first orphan wins, rest will
-        // be picked up on next boot or left as uncompressed)
-        if (!compressing) {
-            compressSrcPath = orphanPath;
-            compressDstPath = orphanPath + ".hs";
-            compressSrc = SPIFFS.open(compressSrcPath, FILE_READ);
-            compressDst = SPIFFS.open(compressDstPath, FILE_WRITE);
-            if (compressSrc && compressDst) {
-                heatshrink_encoder_reset(&compressEncoder);
-                compressInputDone = false;
-                compressing = true;
-                setInterval(HISTORY_COMPRESS_INTERVAL_MS);
-            } else {
-                if (compressSrc)
-                    compressSrc.close();
-                if (compressDst)
-                    compressDst.close();
-            }
-        }
-    }
-
-    activeFilePath = "";
-    activeFile = File();
-}
-
-void CleaningHistory::collectSnapshot() {
-    fetchPending = true;
-
-    neato.getState([this](bool stateOk, const RobotState& state) {
-        if (stateOk) {
-            prevUiState = state.uiState;
-
-            bool isDocking = isDockingState(state.uiState);
-            bool isCleaning = isCleaningState(state.uiState);
-            bool isSuspended = isSuspendedState(state.uiState);
-            bool isChargingMidClean = state.robotState.indexOf("Charging_Cleaning") >= 0;
-
-            // Mid-clean recharge: robot returns to base to charge before resuming.
-            // The UI state can be DOCKING (on the way back) or CLEANINGSUSPENDED
-            // (already on the dock and charging). Both combined with the
-            // Charging_Cleaning robot state indicate a recharge-and-resume cycle.
-            if ((isDocking || isSuspended) && isChargingMidClean) {
-                if (!recharging) {
-                    recharging = true;
-                    rechargeCount++;
-                    LOG("HIST", "Recharge #%d detected — pausing collection", rechargeCount);
-                    dataLogger.logGenericEvent("history_recharge_start", {{"count", String(rechargeCount), FIELD_INT}});
-
-                    if (hasPrevPose) {
-                        writeLine(fieldsToJson({{"type", "recharge", FIELD_STRING},
-                                                {"x", String(prevX, 3), FIELD_FLOAT},
-                                                {"y", String(prevY, 3), FIELD_FLOAT}}));
-                    }
-                }
-                fetchPending = false;
-                return;
-            }
-
-            if (recharging && isCleaning) {
-                recharging = false;
-                LOG("HIST", "Recharge done — resuming collection");
-                dataLogger.logGenericEvent("history_recharge_end", {});
-            }
-
-            if (!isCleaning && !isDocking && !isSuspended) {
-                fetchPending = false;
-                stopCollection();
-                return;
-            }
-
-            // Paused — keep session open but skip snapshot collection
-            if (isPausedState(state.uiState)) {
-                fetchPending = false;
-                return;
-            }
-        }
-
-        neato.getErr([this](bool errOk, const ErrorData& err) {
-            if (errOk) {
-                if (err.hasError && !prevHadError) {
-                    errorsDuringClean++;
-                }
-                prevHadError = err.hasError;
-            }
-
-            if (recharging) {
-                fetchPending = false;
-                return;
-            }
-
-            neato.getRobotPos(true, [this](bool posOk, const RobotPosData& pos) {
-                fetchPending = false;
-                if (!posOk)
-                    return;
-
-                float x, y, theta, time;
-                if (!parsePose(pos.raw, x, y, theta, time)) {
-                    LOG("HIST", "Failed to parse pose");
-                    return;
-                }
-
-                writeSnapshot(x, y, theta, time);
-            });
-        });
-    });
-}
-
-void CleaningHistory::updateAccumulators(float x, float y, float theta) {
-    if (!hasPrevPose) {
-        originX = x;
-        originY = y;
-        prevX = x;
-        prevY = y;
-        prevTheta = theta;
-        hasPrevPose = true;
-    } else {
-        float dx = x - prevX;
-        float dy = y - prevY;
-        totalDistance += sqrtf(dx * dx + dy * dy);
-
-        float dTheta = theta - prevTheta;
-        if (dTheta > 180.0f)
-            dTheta -= 360.0f;
-        if (dTheta < -180.0f)
-            dTheta += 360.0f;
-        totalRotation += fabsf(dTheta);
-
-        prevX = x;
-        prevY = y;
-        prevTheta = theta;
-    }
-
-    float dox = x - originX;
-    float doy = y - originY;
-    float distFromOrigin = sqrtf(dox * dox + doy * doy);
-    if (distFromOrigin > maxDistFromOrigin) {
-        maxDistFromOrigin = distFromOrigin;
-    }
-
-    int ix = static_cast<int>(floorf(x / HISTORY_AREA_CELL_M));
-    int iy = static_cast<int>(floorf(y / HISTORY_AREA_CELL_M));
-    uint32_t cellKey = (static_cast<uint32_t>(ix & 0xFFFF) << 16) | static_cast<uint32_t>(iy & 0xFFFF);
-    visitedCells.insert(cellKey);
-}
-
-void CleaningHistory::writeSnapshot(float x, float y, float theta, float time) {
-    // Localization resets to origin right before session ends — drop if the
-    // robot was far from origin (genuine return-to-base passes through gradually)
-    if (hasPrevPose && fabsf(x) < 0.001f && fabsf(y) < 0.001f && fabsf(theta) < 0.1f) {
-        float prevDist = sqrtf(prevX * prevX + prevY * prevY);
-        if (prevDist > 1.0f) {
-            return;
-        }
-    }
-
-    String line = "{\"x\":" + String(x, 3) + ",\"y\":" + String(y, 3) + ",\"t\":" + String(theta, 1) +
-                  ",\"ts\":" + String(time, 1) + "}";
-
-    updateAccumulators(x, y, theta);
-    bufferLine(line);
-    snapshotCount++;
-
-    if (snapshotCount % 10 == 0) {
-        LOG("HIST", "Snapshot #%u (%.1fm traveled, pose: %.2f,%.2f,%.0f)", snapshotCount, totalDistance, x, y, theta);
-    }
-}
-
-// -- Storage enforcement (mirrors DataLogger::enforceLimits) -----------------
-
-void CleaningHistory::enforceLimits() {
-    // Count session files, sum directory size, and find the oldest in one pass
-    int fileCount = 0;
-    size_t histDirBytes = 0;
-    String oldest;
-    File root = SPIFFS.open(HISTORY_DIR);
-    if (!root || !root.isDirectory())
-        return;
-
-    File entry = root.openNextFile();
-    while (entry) {
-        String name = String(entry.name());
-        histDirBytes += entry.size();
-        if (name.endsWith(".jsonl") || name.endsWith(".jsonl.hs")) {
-            fileCount++;
-            if (oldest.isEmpty() || name < oldest) {
-                oldest = name;
-            }
-        }
-        entry = root.openNextFile();
-    }
-
-    if (oldest.isEmpty())
-        return;
-
-    // History budget: total filesystem cap minus non-history data, floored at minimum reserve
-    size_t total = SPIFFS.totalBytes();
-    size_t globalCap = (total * HISTORY_MAX_FS_PERCENT) / 100;
-    size_t nonHistBytes = SPIFFS.usedBytes() > histDirBytes ? SPIFFS.usedBytes() - histDirBytes : 0;
-    size_t available = globalCap > nonHistBytes ? globalCap - nonHistBytes : 0;
-    size_t minReserved = (total * HISTORY_MIN_FS_PERCENT) / 100;
-    size_t histBudget = available > minReserved ? available : minReserved;
-
-    if (histDirBytes > histBudget || fileCount > HISTORY_MAX_FILES) {
-        String fullPath = String(HISTORY_DIR) + "/" + oldest;
-        LOG("HIST", "Limit: deleting %s (files=%d, histBytes=%u/%u)", fullPath.c_str(), fileCount, histDirBytes,
-            histBudget);
-        SPIFFS.remove(fullPath);
-        metaCache.erase(oldest);
-    }
-}
-
-// -- File management (for API) -----------------------------------------------
-
-void CleaningHistory::readFirstLastLines(const String& path, bool compressed, String& firstLine, String& lastLine) {
-    firstLine = "";
-    lastLine = "";
-
-    if (compressed) {
-        // Stream-decompress keeping only the first and last lines in memory
-        // to avoid buffering the entire file (large sessions can exceed 100KB
-        // decompressed which exhausts ESP32-C3 heap).
-        File f = SPIFFS.open(path, FILE_READ);
-        if (!f)
-            return;
-        CompressedLogReader reader(std::move(f));
-        uint8_t buf[256];
-        size_t n;
-        bool firstDone = false;
-        // Current incomplete line being assembled from chunks
-        String current;
-        while ((n = reader.read(buf, sizeof(buf))) > 0) {
-            for (size_t i = 0; i < n; i++) {
-                char c = static_cast<char>(buf[i]);
-                if (c == '\n') {
-                    current.trim();
-                    if (current.length() > 0) {
-                        if (!firstDone) {
-                            firstLine = current;
-                            firstDone = true;
-                        }
-                        // Always overwrite lastLine with the most recent non-empty line
-                        lastLine = current;
-                    }
-                    current = "";
-                } else {
-                    current += c;
-                }
-            }
-        }
-        // Handle final chunk without trailing newline
-        current.trim();
-        if (current.length() > 0) {
-            if (!firstDone) {
-                firstLine = current;
-            }
-            lastLine = current;
-        }
-    } else {
-        // Plain .jsonl — read first line directly, seek backward for last line
-        File f = SPIFFS.open(path, FILE_READ);
-        if (!f)
-            return;
-        // Read first line
-        firstLine = f.readStringUntil('\n');
-        firstLine.trim();
-        // Seek backward from end to find last line
-        size_t fileSize = f.size();
-        if (fileSize < 2) {
-            f.close();
-            return;
-        }
-        int pos = static_cast<int>(fileSize) - 2; // Skip trailing newline
-        while (pos >= 0) {
-            f.seek(pos);
-            char c = static_cast<char>(f.read());
-            if (c == '\n') {
-                break;
-            }
-            pos--;
-        }
-        // pos is at the newline before last line, or -1 if only one line
-        if (pos < 0) {
-            f.close();
-            return; // Only one line
-        }
-        f.seek(pos + 1);
-        lastLine = f.readStringUntil('\n');
-        lastLine.trim();
-        f.close();
-    }
-}
-
-std::vector<HistorySessionInfo> CleaningHistory::listSessions() {
-    std::vector<HistorySessionInfo> result;
-
-    File root = SPIFFS.open(HISTORY_DIR);
-    if (!root || !root.isDirectory())
-        return result;
-
-    File entry = root.openNextFile();
-    while (entry) {
-        String fullPath = String(entry.path());
-        String name = fullPath;
-        int lastSlash = name.lastIndexOf('/');
-        if (lastSlash >= 0)
-            name = name.substring(lastSlash + 1);
-
-        if (name.endsWith(".jsonl") || name.endsWith(".jsonl.hs")) {
-            // During compression both raw .jsonl and partial .jsonl.hs exist —
-            // skip both until compression finishes and the raw source is deleted
-            if (compressing && (fullPath == compressSrcPath || fullPath == compressDstPath)) {
-                entry = root.openNextFile();
-                continue;
-            }
-
-            // Skip the actively collecting file during disk enumeration.
-            // We will manually append it at the end to avoid thread-safety /
-            // concurrent modification issues with filesystem iterators.
-            if (collecting && fullPath == activeFilePath) {
-                entry = root.openNextFile();
-                continue;
-            }
-
-            HistorySessionInfo info;
-            info.name = name;
-            info.size = entry.size();
-            info.compressed = name.endsWith(".hs");
-
-            // Use cached metadata if available (avoids decompressing .hs files)
-            auto cached = metaCache.find(name);
-            if (cached != metaCache.end()) {
-                info.session = cached->second.session;
-                info.summary = cached->second.summary;
-            } else {
-                String firstLine, lastLine;
-                readFirstLastLines(fullPath, info.compressed, firstLine, lastLine);
-                if (isValidMetaLine(firstLine, "\"type\":\"session\"")) {
-                    info.session = firstLine;
-                }
-                if (isValidMetaLine(lastLine, "\"type\":\"summary\"")) {
-                    info.summary = lastLine;
-                }
-                // Cache for subsequent requests
-                metaCache[name] = {info.session, info.summary};
-            }
-
-            result.push_back(info);
-        }
-        entry = root.openNextFile();
-    }
-
-    // Always append the active session from memory to ensure exactly one entry
-    if (collecting && !activeFilePath.isEmpty()) {
-        String name = activeFilePath;
-        int lastSlash = name.lastIndexOf('/');
-        if (lastSlash >= 0)
-            name = name.substring(lastSlash + 1);
-
-        HistorySessionInfo info;
-        info.name = name;
-        info.size = activeFile ? activeFile.size() : 0;
-        info.compressed = false;
-        info.recording = true;
-
-        String sessionJson = "{\"type\":\"session\",\"mode\":\"" + cleanMode + "\"";
-        if (sessionStartTime > 0)
-            sessionJson += ",\"time\":" + String(static_cast<long>(sessionStartTime));
-        if (batteryStart >= 0)
-            sessionJson += ",\"battery\":" + String(batteryStart);
-        sessionJson += "}";
-        info.session = sessionJson;
-        // No summary for active session
-
-        result.push_back(info);
-    }
-
-    return result;
-}
-
-std::shared_ptr<LogReader> CleaningHistory::readSession(const String& filename) {
-    String path = String(HISTORY_DIR) + "/" + filename;
-
-    // Refuse to serve files involved in compression (partial .hs is corrupt)
-    if (compressing && (path == compressSrcPath || path == compressDstPath))
-        return nullptr;
-
-    if (!SPIFFS.exists(path))
-        return nullptr;
-
-    File f = SPIFFS.open(path, FILE_READ);
-    if (!f)
-        return nullptr;
-
-    if (filename.endsWith(".hs")) {
-        return std::make_shared<CompressedLogReader>(std::move(f));
-    }
-    return std::make_shared<PlainLogReader>(std::move(f));
-}
-
-bool CleaningHistory::deleteSession(const String& filename) {
-    String path = String(HISTORY_DIR) + "/" + filename;
-    if (!SPIFFS.exists(path))
-        return false;
-    metaCache.erase(filename);
-    return SPIFFS.remove(path);
-}
-
-void CleaningHistory::deleteAllSessions() {
-    File root = SPIFFS.open(HISTORY_DIR);
-    if (!root || !root.isDirectory())
-        return;
-
-    std::vector<String> paths;
-    File entry = root.openNextFile();
-    while (entry) {
-        paths.push_back(String(entry.path()));
-        entry = root.openNextFile();
-    }
-
-    for (const auto& p: paths) {
-        SPIFFS.remove(p);
-    }
-    metaCache.clear();
-    LOG("HIST", "Deleted %u session files", paths.size());
-}
-
-// -- Session import (compress-on-write from browser upload) -------------------
-
-bool CleaningHistory::beginImport(const String& filename) {
-    importError = "";
-
-    if (importing) {
-        importError = "Import already in progress";
-        return false;
-    }
-    if (collecting) {
-        importError = "Cannot import while recording";
-        return false;
-    }
-    if (compressing) {
-        importError = "Cannot import while compressing";
-        return false;
-    }
-
-    // Validate filename pattern: <digits>.jsonl
-    if (!filename.endsWith(".jsonl")) {
-        importError = "Invalid filename";
-        return false;
-    }
-
-    // Check for duplicate (both raw and compressed)
-    String rawPath = String(HISTORY_DIR) + "/" + filename;
-    String hsPath = rawPath + ".hs";
-    if (SPIFFS.exists(rawPath) || SPIFFS.exists(hsPath)) {
-        importError = "Session already exists";
-        return false;
-    }
-
-    // Open destination file for compressed output
-    importFilePath = hsPath;
-    importFile = SPIFFS.open(importFilePath, FILE_WRITE);
-    if (!importFile) {
-        importError = "Failed to create file";
-        importFilePath = "";
-        return false;
-    }
-
-    heatshrink_encoder_reset(&importEncoder);
-    importBytesReceived = 0;
-    importing = true;
-    LOG("HIST", "Import started: %s", importFilePath.c_str());
-    return true;
-}
-
-bool CleaningHistory::writeImportChunk(const uint8_t *data, size_t len) {
-    if (!importing || !importFile) {
-        importError = "No import in progress";
-        return false;
-    }
-
-    importBytesReceived += len;
-    if (importBytesReceived > HISTORY_IMPORT_MAX_BYTES) {
-        importError = "File too large";
-        importFile.close();
-        SPIFFS.remove(importFilePath);
-        importing = false;
-        return false;
-    }
-
-    static const size_t OUT_BUF_SIZE = 512;
-    uint8_t outBuf[OUT_BUF_SIZE];
-    size_t offset = 0;
-
-    while (offset < len) {
-        size_t sunk = 0;
-        HSE_sink_res sres = heatshrink_encoder_sink(&importEncoder, data + offset, len - offset, &sunk);
-        if (sres < 0) {
-            importError = "Compression error";
-            importFile.close();
-            SPIFFS.remove(importFilePath);
-            importing = false;
-            return false;
-        }
-        offset += sunk;
-
-        // Drain compressed output
-        size_t outSz = 0;
-        HSE_poll_res pres;
-        do {
-            pres = heatshrink_encoder_poll(&importEncoder, outBuf, OUT_BUF_SIZE, &outSz);
-            if (pres < 0) {
-                importError = "Compression error";
-                importFile.close();
-                SPIFFS.remove(importFilePath);
-                importing = false;
-                return false;
-            }
-            if (outSz > 0) {
-                importFile.write(outBuf, outSz);
-            }
-        } while (pres == HSER_POLL_MORE);
-    }
-    return true;
-}
-
-bool CleaningHistory::endImport() {
-    if (!importing || !importFile) {
-        importError = "No import in progress";
-        return false;
-    }
-
-    static const size_t OUT_BUF_SIZE = 512;
-    uint8_t outBuf[OUT_BUF_SIZE];
-
-    // Finish the encoder — may require multiple poll rounds
-    bool done = false;
-    while (!done) {
-        HSE_finish_res fres = heatshrink_encoder_finish(&importEncoder);
-        if (fres < 0) {
-            importError = "Compression finish error";
-            importFile.close();
-            SPIFFS.remove(importFilePath);
-            importing = false;
-            return false;
-        }
-        done = (fres == HSER_FINISH_DONE);
-
-        size_t outSz = 0;
-        HSE_poll_res pres;
-        do {
-            pres = heatshrink_encoder_poll(&importEncoder, outBuf, OUT_BUF_SIZE, &outSz);
-            if (pres < 0) {
-                importError = "Compression finish error";
-                importFile.close();
-                SPIFFS.remove(importFilePath);
-                importing = false;
-                return false;
-            }
-            if (outSz > 0) {
-                importFile.write(outBuf, outSz);
-            }
-        } while (pres == HSER_POLL_MORE);
-    }
-
-    importFile.close();
-    importing = false;
-    LOG("HIST", "Import complete: %s", importFilePath.c_str());
-    dataLogger.logGenericEvent("history_import", {{"path", importFilePath, FIELD_STRING}});
-
-    // Delete oldest sessions if storage budget exceeded
-    enforceLimits();
-
-    return true;
-}
+#include "cleaning_history.h"
+#include "json_fields.h"
+#include "neato_serial.h"
+#include "system_manager.h"
+#include <SPIFFS.h>
+#include <cmath>
+
+// Heatshrink decompression can drop a byte that merges two JSONL lines into
+// one, so substring matching isn't enough — validate the braces balance and
+// nothing trails the top-level object before embedding into /api/history.
+static bool isValidMetaLine(const String& line, const char *expectedTypePrefix) {
+    if (line.length() < 2 || line[0] != '{' || line[line.length() - 1] != '}')
+        return false;
+    if (line.indexOf(expectedTypePrefix) < 0)
+        return false;
+    int depth = 0;
+    bool inString = false;
+    bool escape = false;
+    for (size_t i = 0; i < line.length(); i++) {
+        char c = line[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (inString) {
+            if (c == '\\')
+                escape = true;
+            else if (c == '"')
+                inString = false;
+            continue;
+        }
+        if (c == '"')
+            inString = true;
+        else if (c == '{')
+            depth++;
+        else if (c == '}') {
+            depth--;
+            if (depth < 0)
+                return false;
+            // Reject trailing content after the top-level object closes
+            if (depth == 0 && i != line.length() - 1)
+                return false;
+        }
+    }
+    return depth == 0 && !inString;
+}
+
+CleaningHistory::CleaningHistory(NeatoSerial& neato, DataLogger& logger, SystemManager& sysMgr) :
+    LoopTask(HISTORY_INTERVAL_IDLE_MS), neato(neato), dataLogger(logger), systemManager(sysMgr) {
+    TaskRegistry::add(this);
+}
+
+void CleaningHistory::notifyCleanStart() {
+    if (collecting)
+        return; // Already recording
+    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
+}
+
+void CleaningHistory::tick() {
+    // Run incremental compression when a session just finished
+    if (compressing) {
+        if (compressStep()) {
+            // Compression done - remove raw source and cache metadata
+            compressSrc.close();
+            compressDst.close();
+            SPIFFS.remove(compressSrcPath);
+            LOG("HIST", "Compression done: %s", compressDstPath.c_str());
+
+            // Cache session/summary from memory (avoids decompressing on next list request)
+            String hsName = compressDstPath;
+            int lastSlash = hsName.lastIndexOf('/');
+            if (lastSlash >= 0)
+                hsName = hsName.substring(lastSlash + 1);
+            metaCache[hsName] = {pendingSessionJson, pendingSummaryJson};
+            pendingSessionJson = "";
+            pendingSummaryJson = "";
+
+            compressing = false;
+            setInterval(HISTORY_INTERVAL_IDLE_MS);
+        }
+        return;
+    }
+
+    if (fetchPending)
+        return;
+
+    if (collecting) {
+        // Periodically flush buffered pose snapshots to disk
+        if (!writeBuffer.empty() && millis() - lastFlushMs >= HISTORY_FLUSH_INTERVAL_MS) {
+            flushWriteBuffer();
+        }
+        collectSnapshot();
+    } else {
+        checkState();
+        enforceLimits();
+    }
+}
+
+// -- State watching (idle mode) ----------------------------------------------
+
+void CleaningHistory::checkState() {
+    fetchPending = true;
+    neato.getState([this](bool ok, const RobotState& state) {
+        fetchPending = false;
+        if (!ok)
+            return;
+
+        bool wasCleaning = isCleaningState(prevUiState);
+        bool nowCleaning = isCleaningState(state.uiState);
+
+        // CLEANINGSUSPENDED + Charging_Cleaning means the robot is on the dock
+        // recharging mid-clean and will resume automatically — treat as active
+        bool isMidCleanRecharge = isSuspendedState(state.uiState) && state.robotState.indexOf("Charging_Cleaning") >= 0;
+
+        // First poll after boot: if the robot is idle, finalize any orphan sessions
+        // left by a previous crash/reboot so they don't get merged into the next clean
+        if (prevUiState.isEmpty() && !nowCleaning && !isMidCleanRecharge && !recoveryAttempted) {
+            recoveryAttempted = true;
+            finalizeOrphanSessions();
+        }
+
+        if (!wasCleaning && (nowCleaning || isMidCleanRecharge) && !recoverCollection(state.uiState)) {
+            startCollection(state.uiState);
+        }
+
+        prevUiState = state.uiState;
+    });
+}
+
+bool CleaningHistory::isCleaningState(const String& uiState) {
+    return uiState.indexOf("HOUSECLEANINGRUNNING") >= 0 || uiState.indexOf("HOUSECLEANINGPAUSED") >= 0 ||
+           uiState.indexOf("SPOTCLEANINGRUNNING") >= 0 || uiState.indexOf("SPOTCLEANINGPAUSED") >= 0 ||
+           uiState.indexOf("MANUALCLEANING") >= 0;
+}
+
+bool CleaningHistory::isPausedState(const String& uiState) {
+    return uiState.indexOf("CLEANINGPAUSED") >= 0;
+}
+
+bool CleaningHistory::isDockingState(const String& uiState) {
+    return uiState.indexOf("DOCKING") >= 0;
+}
+
+bool CleaningHistory::isSuspendedState(const String& uiState) {
+    return uiState.indexOf("CLEANINGSUSPENDED") >= 0;
+}
+
+String CleaningHistory::cleanModeFromState(const String& uiState) {
+    if (uiState.indexOf("HOUSECLEANING") >= 0)
+        return "house";
+    if (uiState.indexOf("SPOTCLEANING") >= 0)
+        return "spot";
+    if (uiState.indexOf("MANUALCLEANING") >= 0)
+        return "manual";
+    return "unknown";
+}
+
+void CleaningHistory::resetSession() {
+    snapshotCount = 0;
+    rechargeCount = 0;
+    totalDistance = 0.0f;
+    totalRotation = 0.0f;
+    maxDistFromOrigin = 0.0f;
+    errorsDuringClean = 0;
+    prevHadError = false;
+    hasPrevPose = false;
+    prevX = 0.0f;
+    prevY = 0.0f;
+    prevTheta = 0.0f;
+    originX = 0.0f;
+    originY = 0.0f;
+    visitedCells.clear();
+    cleanMode = "";
+    sessionStartTime = 0;
+    batteryStart = -1;
+    recharging = false;
+    pendingSessionJson = "";
+    pendingSummaryJson = "";
+}
+
+void CleaningHistory::startCollection(const String& uiState) {
+    collecting = true;
+    resetSession();
+
+    cleanMode = cleanModeFromState(uiState);
+    sessionStartTime = systemManager.now();
+
+    // Create session file: /history/<epoch>.jsonl
+    activeFilePath = String(HISTORY_DIR) + "/" + String(static_cast<long>(sessionStartTime)) + ".jsonl";
+    activeFile = SPIFFS.open(activeFilePath, FILE_WRITE);
+    if (!activeFile) {
+        LOG("HIST", "Failed to create session file: %s", activeFilePath.c_str());
+        collecting = false;
+        return;
+    }
+
+    // Fetch battery level for session metadata, then write header
+    neato.getCharger([this](bool ok, const ChargerData& charger) {
+        if (ok) {
+            batteryStart = charger.fuelPercent;
+        }
+        writeSessionHeader();
+    });
+
+    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
+    LOG("HIST", "Collection started (mode: %s, file: %s)", cleanMode.c_str(), activeFilePath.c_str());
+    dataLogger.logGenericEvent("history_start", {{"mode", cleanMode, FIELD_STRING}});
+}
+
+void CleaningHistory::stopCollection() {
+    // Flush any buffered snapshots before writing summary
+    flushWriteBuffer();
+
+    // Discard sessions that are too short to produce a useful map
+    if (snapshotCount < HISTORY_MIN_SNAPSHOTS) {
+        if (activeFile) {
+            activeFile.close();
+        }
+        SPIFFS.remove(activeFilePath);
+
+        LOG("HIST", "Session discarded (%u snapshots < %d minimum)", snapshotCount, HISTORY_MIN_SNAPSHOTS);
+        dataLogger.logGenericEvent("history_discard", {{"snapshots", String(snapshotCount), FIELD_INT}});
+
+        // Mark stats invalid so NotificationManager doesn't enrich a "done"
+        // notification with stale data from the previous session.
+        lastCleanStats.valid = false;
+        lastCleanStats.sessionId = ++sessionCounter;
+
+        collecting = false;
+        recharging = false;
+        setInterval(HISTORY_INTERVAL_IDLE_MS);
+        return;
+    }
+
+    // Fetch final battery level for summary
+    neato.getCharger([this](bool ok, const ChargerData& charger) {
+        int batteryEnd = ok ? charger.fuelPercent : -1;
+
+        writeSessionSummary(batteryEnd);
+
+        // Close the raw file
+        if (activeFile) {
+            activeFile.close();
+        }
+
+        collecting = false;
+        recharging = false;
+        setInterval(HISTORY_INTERVAL_IDLE_MS);
+
+        float areaCovered = static_cast<float>(visitedCells.size()) * HISTORY_AREA_CELL_M * HISTORY_AREA_CELL_M;
+
+        // Snapshot stats for notification enrichment (survives resetSession).
+        // sessionId increments last so NotificationManager can detect that
+        // the async charger fetch above has finalized the stats.
+        time_t endTime = systemManager.now();
+        lastCleanStats.valid = true;
+        lastCleanStats.mode = cleanMode;
+        lastCleanStats.durationSec = (sessionStartTime > 0 && endTime > sessionStartTime)
+                                             ? static_cast<long>(endTime - sessionStartTime)
+                                             : 0;
+        lastCleanStats.areaCoveredM2 = areaCovered;
+        lastCleanStats.distanceM = totalDistance;
+        lastCleanStats.batteryStart = batteryStart;
+        lastCleanStats.batteryEnd = batteryEnd;
+        lastCleanStats.recharges = rechargeCount;
+        lastCleanStats.sessionId = ++sessionCounter;
+
+        LOG("HIST", "Collection stopped (%u snapshots, %.1fm², %d recharges)", snapshotCount, areaCovered,
+            rechargeCount);
+        dataLogger.logGenericEvent("history_stop", {{"snapshots", String(snapshotCount), FIELD_INT},
+                                                    {"area_m2", String(areaCovered, 1), FIELD_FLOAT},
+                                                    {"recharges", String(rechargeCount), FIELD_INT},
+                                                    {"battery_end", String(batteryEnd), FIELD_INT}});
+
+        // Start non-blocking compression: raw .jsonl -> .jsonl.hs
+        compressSrcPath = activeFilePath;
+        compressDstPath = activeFilePath + ".hs";
+        compressSrc = SPIFFS.open(compressSrcPath, FILE_READ);
+        compressDst = SPIFFS.open(compressDstPath, FILE_WRITE);
+        if (compressSrc && compressDst) {
+            heatshrink_encoder_reset(&compressEncoder);
+            compressInputDone = false;
+            compressing = true;
+            setInterval(HISTORY_COMPRESS_INTERVAL_MS);
+            LOG("HIST", "Starting compression: %s -> %s", compressSrcPath.c_str(), compressDstPath.c_str());
+        } else {
+            // Compression failed - keep raw file
+            if (compressSrc)
+                compressSrc.close();
+            if (compressDst)
+                compressDst.close();
+            LOG("HIST", "Compression setup failed, keeping raw file");
+        }
+    });
+}
+
+// -- Incremental compression (called from tick) ------------------------------
+
+bool CleaningHistory::compressStep() {
+    static const size_t CHUNK_SIZE = 512;
+    uint8_t inBuf[CHUNK_SIZE];
+    uint8_t outBuf[CHUNK_SIZE];
+
+    if (!compressInputDone) {
+        int bytesRead = compressSrc.read(inBuf, CHUNK_SIZE);
+        if (bytesRead <= 0) {
+            compressInputDone = true;
+        } else {
+            size_t offset = 0;
+            while (offset < static_cast<size_t>(bytesRead)) {
+                size_t sunk = 0;
+                HSE_sink_res sres =
+                        heatshrink_encoder_sink(&compressEncoder, inBuf + offset, bytesRead - offset, &sunk);
+                if (sres < 0) {
+                    LOG("HIST", "Heatshrink sink error");
+                    compressSrc.close();
+                    compressDst.close();
+                    SPIFFS.remove(compressDstPath);
+                    compressing = false;
+                    return true;
+                }
+                offset += sunk;
+
+                size_t outSz = 0;
+                HSE_poll_res pres;
+                do {
+                    pres = heatshrink_encoder_poll(&compressEncoder, outBuf, CHUNK_SIZE, &outSz);
+                    if (pres < 0) {
+                        LOG("HIST", "Heatshrink poll error");
+                        compressSrc.close();
+                        compressDst.close();
+                        SPIFFS.remove(compressDstPath);
+                        compressing = false;
+                        return true;
+                    }
+                    if (outSz > 0) {
+                        compressDst.write(outBuf, outSz);
+                    }
+                } while (pres == HSER_POLL_MORE);
+            }
+        }
+        return false;
+    }
+
+    // Input exhausted — finish encoding
+    HSE_finish_res fres = heatshrink_encoder_finish(&compressEncoder);
+    if (fres < 0) {
+        LOG("HIST", "Heatshrink finish error");
+        compressSrc.close();
+        compressDst.close();
+        SPIFFS.remove(compressDstPath);
+        compressing = false;
+        return true;
+    }
+
+    size_t outSz = 0;
+    HSE_poll_res pres;
+    do {
+        pres = heatshrink_encoder_poll(&compressEncoder, outBuf, CHUNK_SIZE, &outSz);
+        if (pres < 0) {
+            LOG("HIST", "Heatshrink poll error during finish");
+            compressSrc.close();
+            compressDst.close();
+            SPIFFS.remove(compressDstPath);
+            compressing = false;
+            return true;
+        }
+        if (outSz > 0) {
+            compressDst.write(outBuf, outSz);
+        }
+    } while (pres == HSER_POLL_MORE);
+
+    return (fres == HSER_FINISH_DONE);
+}
+
+// -- Session header/summary --------------------------------------------------
+
+void CleaningHistory::writeSessionHeader() {
+    std::vector<Field> fields = {{"type", "session", FIELD_STRING}, {"mode", cleanMode, FIELD_STRING}};
+    if (sessionStartTime > 0)
+        fields.push_back({"time", String(static_cast<long>(sessionStartTime)), FIELD_INT});
+    if (batteryStart >= 0)
+        fields.push_back({"battery", String(batteryStart), FIELD_INT});
+    String json = fieldsToJson(fields);
+    pendingSessionJson = json;
+    writeLine(json);
+}
+
+void CleaningHistory::writeSessionSummary(int batteryEnd) {
+    time_t endTime = systemManager.now();
+    long duration =
+            (sessionStartTime > 0 && endTime > sessionStartTime) ? static_cast<long>(endTime - sessionStartTime) : 0;
+    float areaCovered = static_cast<float>(visitedCells.size()) * HISTORY_AREA_CELL_M * HISTORY_AREA_CELL_M;
+    std::vector<Field> fields = {{"type", "summary", FIELD_STRING}};
+    if (endTime > 0)
+        fields.push_back({"time", String(static_cast<long>(endTime)), FIELD_INT});
+    fields.push_back({"duration", String(duration), FIELD_INT});
+    fields.push_back({"mode", cleanMode, FIELD_STRING});
+    fields.push_back({"recharges", String(rechargeCount), FIELD_INT});
+    fields.push_back({"snapshots", String(static_cast<int>(snapshotCount)), FIELD_INT});
+    fields.push_back({"distanceTraveled", String(totalDistance, 2), FIELD_FLOAT});
+    fields.push_back({"maxDistFromOrigin", String(maxDistFromOrigin, 2), FIELD_FLOAT});
+    fields.push_back({"totalRotation", String(totalRotation, 1), FIELD_FLOAT});
+    fields.push_back({"areaCovered", String(areaCovered, 2), FIELD_FLOAT});
+    fields.push_back({"errorsDuringClean", String(errorsDuringClean), FIELD_INT});
+    if (batteryStart >= 0)
+        fields.push_back({"batteryStart", String(batteryStart), FIELD_INT});
+    if (batteryEnd >= 0)
+        fields.push_back({"batteryEnd", String(batteryEnd), FIELD_INT});
+    String json = fieldsToJson(fields);
+    pendingSummaryJson = json;
+    writeLine(json);
+}
+
+// -- Buffered file writing ---------------------------------------------------
+// Pose snapshots accumulate in writeBuffer; flushed every HISTORY_FLUSH_INTERVAL_MS
+// or when the session ends (stopCollection / recovery). This reduces flash wear
+// from one write every 2s to one write every 30s during a cleaning session.
+// Session header, summary, and recharge markers flush immediately since they
+// are rare one-shot writes where crash safety matters.
+
+void CleaningHistory::writeLine(const String& line) {
+    if (!activeFile)
+        return;
+    activeFile.println(line);
+    activeFile.flush();
+}
+
+void CleaningHistory::bufferLine(const String& line) {
+    if (!activeFile)
+        return;
+    writeBuffer.push_back(line);
+}
+
+void CleaningHistory::flushWriteBuffer() {
+    if (writeBuffer.empty() || !activeFile)
+        return;
+    // Build a single string and write once to minimize SPIFFS COW metadata updates
+    String batch;
+    size_t total = 0;
+    for (const auto& line: writeBuffer) {
+        total += line.length() + 1;
+    }
+    batch.reserve(total);
+    for (const auto& line: writeBuffer) {
+        batch += line;
+        batch += '\n';
+    }
+    activeFile.write(reinterpret_cast<const uint8_t *>(batch.c_str()), batch.length());
+    activeFile.flush();
+    writeBuffer.clear();
+    lastFlushMs = millis();
+}
+
+// -- Snapshot collection (active mode) ---------------------------------------
+
+static bool parsePose(const String& raw, float& x, float& y, float& theta, float& time) {
+    int xPos = raw.indexOf("X=");
+    int yPos = raw.indexOf("Y=");
+    int tPos = raw.indexOf("Theta=");
+    int tmPos = raw.indexOf("Time=");
+    if (xPos < 0 || yPos < 0 || tPos < 0 || tmPos < 0)
+        return false;
+
+    x = raw.substring(xPos + 2).toFloat();
+    y = raw.substring(yPos + 2).toFloat();
+    theta = raw.substring(tPos + 6).toFloat();
+    time = raw.substring(tmPos + 5).toFloat();
+    return true;
+}
+
+// Parse a single JSONL line and update session accumulators (header, recharge, pose).
+// Returns true if the line was a session header.
+bool CleaningHistory::replayLine(const String& line) {
+    auto fields = fieldsFromJson(line);
+    if (fields.empty())
+        return false;
+
+    const Field *typeField = findField(fields, "type");
+    if (typeField && typeField->value == "session") {
+        const Field *modeField = findField(fields, "mode");
+        if (modeField && !modeField->value.isEmpty())
+            cleanMode = modeField->value;
+
+        const Field *timeField = findField(fields, "time");
+        if (timeField) {
+            long t = timeField->value.toInt();
+            if (t > 0)
+                sessionStartTime = static_cast<time_t>(t);
+        }
+
+        const Field *battField = findField(fields, "battery");
+        if (battField)
+            batteryStart = battField->value.toInt();
+        return true;
+    }
+
+    if (typeField && typeField->value == "recharge") {
+        rechargeCount++;
+        return false;
+    }
+
+    // Pose snapshot line
+    const Field *xf = findField(fields, "x");
+    const Field *yf = findField(fields, "y");
+    const Field *tf = findField(fields, "t");
+    if (xf && yf && tf) {
+        updateAccumulators(xf->value.toFloat(), yf->value.toFloat(), tf->value.toFloat());
+        snapshotCount++;
+    }
+    return false;
+}
+
+bool CleaningHistory::recoverCollection(const String& uiState) {
+    // Only attempt recovery once after boot — avoid scanning filesystem on every clean start
+    if (recoveryAttempted)
+        return false;
+    recoveryAttempted = true;
+
+    File root = SPIFFS.open(HISTORY_DIR);
+    if (!root || !root.isDirectory())
+        return false;
+
+    // Collect all history filenames (both .jsonl and .jsonl.hs) and sort descending
+    // (newest first). Then walk from newest to oldest: collect orphan .jsonl files
+    // until we hit a compressed .jsonl.hs — that marks a completed session boundary,
+    // so everything older belongs to previous cleans and should not be touched.
+    // Also clean up any raw .jsonl that has a .jsonl.hs counterpart (stale leftover).
+    std::vector<String> allFiles;
+    File entry = root.openNextFile();
+    while (entry) {
+        String path = String(entry.path());
+        if (path.endsWith(".jsonl") || path.endsWith(".jsonl.hs"))
+            allFiles.push_back(path);
+        entry = root.openNextFile();
+    }
+
+    std::sort(allFiles.begin(), allFiles.end(), [](const String& a, const String& b) { return a > b; });
+
+    std::vector<String> orphans;
+    for (const auto& path: allFiles) {
+        if (path.endsWith(".jsonl.hs")) {
+            // Hit a compressed file — this is the boundary of a completed session.
+            // Stop collecting; everything older is from previous cleans.
+            break;
+        }
+        // Raw .jsonl — check if a compressed copy exists (stale leftover)
+        if (SPIFFS.exists(path + ".hs")) {
+            SPIFFS.remove(path);
+            LOG("HIST", "Removed stale raw file: %s (compressed copy exists)", path.c_str());
+            continue;
+        }
+        // Check if it has a summary (completed but not yet compressed)
+        String firstLine, lastLine;
+        readFirstLastLines(path, false, firstLine, lastLine);
+        if (lastLine.indexOf("\"type\":\"summary\"") >= 0)
+            continue;
+        orphans.push_back(path);
+    }
+
+    if (orphans.empty())
+        return false;
+
+    // orphans are newest-first; reverse to get chronological order (oldest first)
+    std::reverse(orphans.begin(), orphans.end());
+
+    // The oldest orphan becomes the target; newer ones are merged into it then deleted
+    String targetPath = orphans[0];
+
+    if (orphans.size() > 1) {
+        File target = SPIFFS.open(targetPath, FILE_APPEND);
+        if (target) {
+            for (size_t i = 1; i < orphans.size(); i++) {
+                File src = SPIFFS.open(orphans[i], FILE_READ);
+                if (!src)
+                    continue;
+                while (src.available()) {
+                    String line = src.readStringUntil('\n');
+                    line.trim();
+                    if (line.isEmpty())
+                        continue;
+                    // Skip duplicate session headers from newer orphans
+                    if (line.indexOf("\"type\":\"session\"") >= 0)
+                        continue;
+                    target.println(line);
+                }
+                src.close();
+                SPIFFS.remove(orphans[i]);
+                LOG("HIST", "Merged orphan %s into %s", orphans[i].c_str(), targetPath.c_str());
+            }
+            target.flush();
+            target.close();
+        }
+    }
+
+    // Now replay the merged file to rebuild accumulators
+    resetSession();
+    cleanMode = cleanModeFromState(uiState);
+    activeFilePath = targetPath;
+
+    File recoveryFile = SPIFFS.open(targetPath, FILE_READ);
+    if (!recoveryFile)
+        return false;
+
+    bool hasSessionHeader = false;
+    while (recoveryFile.available()) {
+        String line = recoveryFile.readStringUntil('\n');
+        line.trim();
+        if (line.isEmpty())
+            continue;
+        if (replayLine(line))
+            hasSessionHeader = true;
+    }
+    recoveryFile.close();
+
+    // Fall back to extracting start time from the filename
+    if (sessionStartTime <= 0) {
+        String name = targetPath;
+        int slash = name.lastIndexOf('/');
+        if (slash >= 0)
+            name = name.substring(slash + 1);
+        int dot = name.indexOf('.');
+        if (dot > 0)
+            sessionStartTime = static_cast<time_t>(name.substring(0, dot).toInt());
+    }
+
+    activeFile = SPIFFS.open(activeFilePath, FILE_APPEND);
+    if (!activeFile) {
+        activeFilePath = "";
+        resetSession();
+        return false;
+    }
+
+    collecting = true;
+    setInterval(HISTORY_INTERVAL_ACTIVE_MS);
+    LOG("HIST", "Recovered session: %s (%u snapshots, %zu orphans merged)", activeFilePath.c_str(), snapshotCount,
+        orphans.size());
+    dataLogger.logGenericEvent("history_recover", {{"path", activeFilePath, FIELD_STRING},
+                                                   {"snapshots", String(snapshotCount), FIELD_INT},
+                                                   {"orphans", String(static_cast<int>(orphans.size())), FIELD_INT}});
+
+    if (!hasSessionHeader) {
+        writeSessionHeader();
+    }
+    return true;
+}
+
+void CleaningHistory::finalizeOrphanSessions() {
+    // Called once at boot when the robot is idle. Finds orphan .jsonl files
+    // (no summary line, no compressed counterpart) and finalizes them: replay
+    // to compute summary stats, append summary line, then start compression.
+    File root = SPIFFS.open(HISTORY_DIR);
+    if (!root || !root.isDirectory())
+        return;
+
+    std::vector<String> allFiles;
+    File entry = root.openNextFile();
+    while (entry) {
+        String path = String(entry.path());
+        if (path.endsWith(".jsonl") || path.endsWith(".jsonl.hs"))
+            allFiles.push_back(path);
+        entry = root.openNextFile();
+    }
+
+    std::sort(allFiles.begin(), allFiles.end(), [](const String& a, const String& b) { return a > b; });
+
+    std::vector<String> orphans;
+    for (const auto& path: allFiles) {
+        if (path.endsWith(".jsonl.hs"))
+            break; // Completed session boundary
+        if (SPIFFS.exists(path + ".hs")) {
+            SPIFFS.remove(path);
+            continue;
+        }
+        String firstLine, lastLine;
+        readFirstLastLines(path, false, firstLine, lastLine);
+        if (lastLine.indexOf("\"type\":\"summary\"") >= 0)
+            continue;
+        orphans.push_back(path);
+    }
+
+    if (orphans.empty())
+        return;
+
+    // Finalize each orphan: replay to rebuild stats, write summary, compress
+    for (const auto& orphanPath: orphans) {
+        resetSession();
+
+        // Replay to rebuild accumulators
+        File f = SPIFFS.open(orphanPath, FILE_READ);
+        if (!f)
+            continue;
+        while (f.available()) {
+            String line = f.readStringUntil('\n');
+            line.trim();
+            if (line.isEmpty())
+                continue;
+            replayLine(line);
+        }
+        f.close();
+
+        // Extract start time from filename if not found in header
+        if (sessionStartTime <= 0) {
+            String name = orphanPath;
+            int slash = name.lastIndexOf('/');
+            if (slash >= 0)
+                name = name.substring(slash + 1);
+            int dot = name.indexOf('.');
+            if (dot > 0)
+                sessionStartTime = static_cast<time_t>(name.substring(0, dot).toInt());
+        }
+
+        // Open for append and write summary
+        activeFilePath = orphanPath;
+        activeFile = SPIFFS.open(orphanPath, FILE_APPEND);
+        if (!activeFile)
+            continue;
+
+        writeSessionSummary(-1); // Battery end unknown for interrupted sessions
+        activeFile.close();
+
+        LOG("HIST", "Finalized orphan: %s (%u snapshots)", orphanPath.c_str(), snapshotCount);
+        dataLogger.logGenericEvent("history_finalize", {{"path", orphanPath, FIELD_STRING},
+                                                        {"snapshots", String(snapshotCount), FIELD_INT}});
+
+        // Queue compression (only one at a time — first orphan wins, rest will
+        // be picked up on next boot or left as uncompressed)
+        if (!compressing) {
+            compressSrcPath = orphanPath;
+            compressDstPath = orphanPath + ".hs";
+            compressSrc = SPIFFS.open(compressSrcPath, FILE_READ);
+            compressDst = SPIFFS.open(compressDstPath, FILE_WRITE);
+            if (compressSrc && compressDst) {
+                heatshrink_encoder_reset(&compressEncoder);
+                compressInputDone = false;
+                compressing = true;
+                setInterval(HISTORY_COMPRESS_INTERVAL_MS);
+            } else {
+                if (compressSrc)
+                    compressSrc.close();
+                if (compressDst)
+                    compressDst.close();
+            }
+        }
+    }
+
+    activeFilePath = "";
+    activeFile = File();
+}
+
+void CleaningHistory::collectSnapshot() {
+    fetchPending = true;
+
+    neato.getState([this](bool stateOk, const RobotState& state) {
+        if (stateOk) {
+            prevUiState = state.uiState;
+
+            bool isDocking = isDockingState(state.uiState);
+            bool isCleaning = isCleaningState(state.uiState);
+            bool isSuspended = isSuspendedState(state.uiState);
+            bool isChargingMidClean = state.robotState.indexOf("Charging_Cleaning") >= 0;
+
+            // Mid-clean recharge: robot returns to base to charge before resuming.
+            // The UI state can be DOCKING (on the way back) or CLEANINGSUSPENDED
+            // (already on the dock and charging). Both combined with the
+            // Charging_Cleaning robot state indicate a recharge-and-resume cycle.
+            if ((isDocking || isSuspended) && isChargingMidClean) {
+                if (!recharging) {
+                    recharging = true;
+                    rechargeCount++;
+                    LOG("HIST", "Recharge #%d detected — pausing collection", rechargeCount);
+                    dataLogger.logGenericEvent("history_recharge_start", {{"count", String(rechargeCount), FIELD_INT}});
+
+                    if (hasPrevPose) {
+                        writeLine(fieldsToJson({{"type", "recharge", FIELD_STRING},
+                                                {"x", String(prevX, 3), FIELD_FLOAT},
+                                                {"y", String(prevY, 3), FIELD_FLOAT}}));
+                    }
+                }
+                fetchPending = false;
+                return;
+            }
+
+            if (recharging && isCleaning) {
+                recharging = false;
+                LOG("HIST", "Recharge done — resuming collection");
+                dataLogger.logGenericEvent("history_recharge_end", {});
+            }
+
+            if (!isCleaning && !isDocking && !isSuspended) {
+                fetchPending = false;
+                stopCollection();
+                return;
+            }
+
+            // Paused — keep session open but skip snapshot collection
+            if (isPausedState(state.uiState)) {
+                fetchPending = false;
+                return;
+            }
+        }
+
+        neato.getErr([this](bool errOk, const ErrorData& err) {
+            if (errOk) {
+                if (err.hasError && !prevHadError) {
+                    errorsDuringClean++;
+                }
+                prevHadError = err.hasError;
+            }
+
+            if (recharging) {
+                fetchPending = false;
+                return;
+            }
+
+            neato.getRobotPos(true, [this](bool posOk, const RobotPosData& pos) {
+                fetchPending = false;
+                if (!posOk)
+                    return;
+
+                float x, y, theta, time;
+                if (!parsePose(pos.raw, x, y, theta, time)) {
+                    LOG("HIST", "Failed to parse pose");
+                    return;
+                }
+
+                writeSnapshot(x, y, theta, time);
+            });
+        });
+    });
+}
+
+void CleaningHistory::updateAccumulators(float x, float y, float theta) {
+    if (!hasPrevPose) {
+        originX = x;
+        originY = y;
+        prevX = x;
+        prevY = y;
+        prevTheta = theta;
+        hasPrevPose = true;
+    } else {
+        float dx = x - prevX;
+        float dy = y - prevY;
+        totalDistance += sqrtf(dx * dx + dy * dy);
+
+        float dTheta = theta - prevTheta;
+        if (dTheta > 180.0f)
+            dTheta -= 360.0f;
+        if (dTheta < -180.0f)
+            dTheta += 360.0f;
+        totalRotation += fabsf(dTheta);
+
+        prevX = x;
+        prevY = y;
+        prevTheta = theta;
+    }
+
+    float dox = x - originX;
+    float doy = y - originY;
+    float distFromOrigin = sqrtf(dox * dox + doy * doy);
+    if (distFromOrigin > maxDistFromOrigin) {
+        maxDistFromOrigin = distFromOrigin;
+    }
+
+    int ix = static_cast<int>(floorf(x / HISTORY_AREA_CELL_M));
+    int iy = static_cast<int>(floorf(y / HISTORY_AREA_CELL_M));
+    uint32_t cellKey = (static_cast<uint32_t>(ix & 0xFFFF) << 16) | static_cast<uint32_t>(iy & 0xFFFF);
+    visitedCells.insert(cellKey);
+}
+
+void CleaningHistory::writeSnapshot(float x, float y, float theta, float time) {
+    // Localization resets to origin right before session ends — drop if the
+    // robot was far from origin (genuine return-to-base passes through gradually)
+    if (hasPrevPose && fabsf(x) < 0.001f && fabsf(y) < 0.001f && fabsf(theta) < 0.1f) {
+        float prevDist = sqrtf(prevX * prevX + prevY * prevY);
+        if (prevDist > 1.0f) {
+            return;
+        }
+    }
+
+    String line = "{\"x\":" + String(x, 3) + ",\"y\":" + String(y, 3) + ",\"t\":" + String(theta, 1) +
+                  ",\"ts\":" + String(time, 1) + "}";
+
+    updateAccumulators(x, y, theta);
+    bufferLine(line);
+    snapshotCount++;
+
+    if (snapshotCount % 10 == 0) {
+        LOG("HIST", "Snapshot #%u (%.1fm traveled, pose: %.2f,%.2f,%.0f)", snapshotCount, totalDistance, x, y, theta);
+    }
+}
+
+// -- Storage enforcement (mirrors DataLogger::enforceLimits) -----------------
+
+void CleaningHistory::enforceLimits() {
+    // Count session files, sum directory size, and find the oldest in one pass
+    int fileCount = 0;
+    size_t histDirBytes = 0;
+    String oldest;
+    File root = SPIFFS.open(HISTORY_DIR);
+    if (!root || !root.isDirectory())
+        return;
+
+    File entry = root.openNextFile();
+    while (entry) {
+        String name = String(entry.name());
+        histDirBytes += entry.size();
+        if (name.endsWith(".jsonl") || name.endsWith(".jsonl.hs")) {
+            fileCount++;
+            if (oldest.isEmpty() || name < oldest) {
+                oldest = name;
+            }
+        }
+        entry = root.openNextFile();
+    }
+
+    if (oldest.isEmpty())
+        return;
+
+    // History budget: total filesystem cap minus non-history data, floored at minimum reserve
+    size_t total = SPIFFS.totalBytes();
+    size_t globalCap = (total * HISTORY_MAX_FS_PERCENT) / 100;
+    size_t nonHistBytes = SPIFFS.usedBytes() > histDirBytes ? SPIFFS.usedBytes() - histDirBytes : 0;
+    size_t available = globalCap > nonHistBytes ? globalCap - nonHistBytes : 0;
+    size_t minReserved = (total * HISTORY_MIN_FS_PERCENT) / 100;
+    size_t histBudget = available > minReserved ? available : minReserved;
+
+    if (histDirBytes > histBudget || fileCount > HISTORY_MAX_FILES) {
+        String fullPath = String(HISTORY_DIR) + "/" + oldest;
+        LOG("HIST", "Limit: deleting %s (files=%d, histBytes=%u/%u)", fullPath.c_str(), fileCount, histDirBytes,
+            histBudget);
+        SPIFFS.remove(fullPath);
+        metaCache.erase(oldest);
+    }
+}
+
+// -- File management (for API) -----------------------------------------------
+
+void CleaningHistory::readFirstLastLines(const String& path, bool compressed, String& firstLine, String& lastLine) {
+    firstLine = "";
+    lastLine = "";
+
+    if (compressed) {
+        // Stream-decompress keeping only the first and last lines in memory
+        // to avoid buffering the entire file (large sessions can exceed 100KB
+        // decompressed which exhausts ESP32-C3 heap).
+        File f = SPIFFS.open(path, FILE_READ);
+        if (!f)
+            return;
+        CompressedLogReader reader(std::move(f));
+        uint8_t buf[256];
+        size_t n;
+        bool firstDone = false;
+        // Current incomplete line being assembled from chunks
+        String current;
+        while ((n = reader.read(buf, sizeof(buf))) > 0) {
+            for (size_t i = 0; i < n; i++) {
+                char c = static_cast<char>(buf[i]);
+                if (c == '\n') {
+                    current.trim();
+                    if (current.length() > 0) {
+                        if (!firstDone) {
+                            firstLine = current;
+                            firstDone = true;
+                        }
+                        // Always overwrite lastLine with the most recent non-empty line
+                        lastLine = current;
+                    }
+                    current = "";
+                } else {
+                    current += c;
+                }
+            }
+        }
+        // Handle final chunk without trailing newline
+        current.trim();
+        if (current.length() > 0) {
+            if (!firstDone) {
+                firstLine = current;
+            }
+            lastLine = current;
+        }
+    } else {
+        // Plain .jsonl — read first line directly, seek backward for last line
+        File f = SPIFFS.open(path, FILE_READ);
+        if (!f)
+            return;
+        // Read first line
+        firstLine = f.readStringUntil('\n');
+        firstLine.trim();
+        // Seek backward from end to find last line
+        size_t fileSize = f.size();
+        if (fileSize < 2) {
+            f.close();
+            return;
+        }
+        int pos = static_cast<int>(fileSize) - 2; // Skip trailing newline
+        while (pos >= 0) {
+            f.seek(pos);
+            char c = static_cast<char>(f.read());
+            if (c == '\n') {
+                break;
+            }
+            pos--;
+        }
+        // pos is at the newline before last line, or -1 if only one line
+        if (pos < 0) {
+            f.close();
+            return; // Only one line
+        }
+        f.seek(pos + 1);
+        lastLine = f.readStringUntil('\n');
+        lastLine.trim();
+        f.close();
+    }
+}
+
+std::vector<HistorySessionInfo> CleaningHistory::listSessions() {
+    std::vector<HistorySessionInfo> result;
+
+    File root = SPIFFS.open(HISTORY_DIR);
+    if (!root || !root.isDirectory())
+        return result;
+
+    File entry = root.openNextFile();
+    while (entry) {
+        String fullPath = String(entry.path());
+        String name = fullPath;
+        int lastSlash = name.lastIndexOf('/');
+        if (lastSlash >= 0)
+            name = name.substring(lastSlash + 1);
+
+        if (name.endsWith(".jsonl") || name.endsWith(".jsonl.hs")) {
+            // During compression both raw .jsonl and partial .jsonl.hs exist —
+            // skip both until compression finishes and the raw source is deleted
+            if (compressing && (fullPath == compressSrcPath || fullPath == compressDstPath)) {
+                entry = root.openNextFile();
+                continue;
+            }
+
+            // Skip the actively collecting file during disk enumeration.
+            // We will manually append it at the end to avoid thread-safety /
+            // concurrent modification issues with filesystem iterators.
+            if (collecting && fullPath == activeFilePath) {
+                entry = root.openNextFile();
+                continue;
+            }
+
+            HistorySessionInfo info;
+            info.name = name;
+            info.size = entry.size();
+            info.compressed = name.endsWith(".hs");
+
+            // Use cached metadata if available (avoids decompressing .hs files)
+            auto cached = metaCache.find(name);
+            if (cached != metaCache.end()) {
+                info.session = cached->second.session;
+                info.summary = cached->second.summary;
+            } else {
+                String firstLine, lastLine;
+                readFirstLastLines(fullPath, info.compressed, firstLine, lastLine);
+                if (isValidMetaLine(firstLine, "\"type\":\"session\"")) {
+                    info.session = firstLine;
+                }
+                if (isValidMetaLine(lastLine, "\"type\":\"summary\"")) {
+                    info.summary = lastLine;
+                }
+                // Cache for subsequent requests
+                metaCache[name] = {info.session, info.summary};
+            }
+
+            result.push_back(info);
+        }
+        entry = root.openNextFile();
+    }
+
+    // Always append the active session from memory to ensure exactly one entry
+    if (collecting && !activeFilePath.isEmpty()) {
+        String name = activeFilePath;
+        int lastSlash = name.lastIndexOf('/');
+        if (lastSlash >= 0)
+            name = name.substring(lastSlash + 1);
+
+        HistorySessionInfo info;
+        info.name = name;
+        info.size = activeFile ? activeFile.size() : 0;
+        info.compressed = false;
+        info.recording = true;
+
+        String sessionJson = "{\"type\":\"session\",\"mode\":\"" + cleanMode + "\"";
+        if (sessionStartTime > 0)
+            sessionJson += ",\"time\":" + String(static_cast<long>(sessionStartTime));
+        if (batteryStart >= 0)
+            sessionJson += ",\"battery\":" + String(batteryStart);
+        sessionJson += "}";
+        info.session = sessionJson;
+        // No summary for active session
+
+        result.push_back(info);
+    }
+
+    return result;
+}
+
+std::shared_ptr<LogReader> CleaningHistory::readSession(const String& filename) {
+    String path = String(HISTORY_DIR) + "/" + filename;
+
+    // Refuse to serve files involved in compression (partial .hs is corrupt)
+    if (compressing && (path == compressSrcPath || path == compressDstPath))
+        return nullptr;
+
+    if (!SPIFFS.exists(path))
+        return nullptr;
+
+    File f = SPIFFS.open(path, FILE_READ);
+    if (!f)
+        return nullptr;
+
+    if (filename.endsWith(".hs")) {
+        return std::make_shared<CompressedLogReader>(std::move(f));
+    }
+    return std::make_shared<PlainLogReader>(std::move(f));
+}
+
+bool CleaningHistory::deleteSession(const String& filename) {
+    String path = String(HISTORY_DIR) + "/" + filename;
+    if (!SPIFFS.exists(path))
+        return false;
+    metaCache.erase(filename);
+    return SPIFFS.remove(path);
+}
+
+void CleaningHistory::deleteAllSessions() {
+    File root = SPIFFS.open(HISTORY_DIR);
+    if (!root || !root.isDirectory())
+        return;
+
+    std::vector<String> paths;
+    File entry = root.openNextFile();
+    while (entry) {
+        paths.push_back(String(entry.path()));
+        entry = root.openNextFile();
+    }
+
+    for (const auto& p: paths) {
+        SPIFFS.remove(p);
+    }
+    metaCache.clear();
+    LOG("HIST", "Deleted %u session files", paths.size());
+}
+
+// -- Session import (compress-on-write from browser upload) -------------------
+
+bool CleaningHistory::beginImport(const String& filename) {
+    importError = "";
+
+    if (importing) {
+        importError = "Import already in progress";
+        return false;
+    }
+    if (collecting) {
+        importError = "Cannot import while recording";
+        return false;
+    }
+    if (compressing) {
+        importError = "Cannot import while compressing";
+        return false;
+    }
+
+    // Validate filename pattern: <digits>.jsonl
+    if (!filename.endsWith(".jsonl")) {
+        importError = "Invalid filename";
+        return false;
+    }
+
+    // Check for duplicate (both raw and compressed)
+    String rawPath = String(HISTORY_DIR) + "/" + filename;
+    String hsPath = rawPath + ".hs";
+    if (SPIFFS.exists(rawPath) || SPIFFS.exists(hsPath)) {
+        importError = "Session already exists";
+        return false;
+    }
+
+    // Open destination file for compressed output
+    importFilePath = hsPath;
+    importFile = SPIFFS.open(importFilePath, FILE_WRITE);
+    if (!importFile) {
+        importError = "Failed to create file";
+        importFilePath = "";
+        return false;
+    }
+
+    heatshrink_encoder_reset(&importEncoder);
+    importBytesReceived = 0;
+    importing = true;
+    LOG("HIST", "Import started: %s", importFilePath.c_str());
+    return true;
+}
+
+bool CleaningHistory::writeImportChunk(const uint8_t *data, size_t len) {
+    if (!importing || !importFile) {
+        importError = "No import in progress";
+        return false;
+    }
+
+    importBytesReceived += len;
+    if (importBytesReceived > HISTORY_IMPORT_MAX_BYTES) {
+        importError = "File too large";
+        importFile.close();
+        SPIFFS.remove(importFilePath);
+        importing = false;
+        return false;
+    }
+
+    static const size_t OUT_BUF_SIZE = 512;
+    uint8_t outBuf[OUT_BUF_SIZE];
+    size_t offset = 0;
+
+    while (offset < len) {
+        size_t sunk = 0;
+        HSE_sink_res sres = heatshrink_encoder_sink(&importEncoder, data + offset, len - offset, &sunk);
+        if (sres < 0) {
+            importError = "Compression error";
+            importFile.close();
+            SPIFFS.remove(importFilePath);
+            importing = false;
+            return false;
+        }
+        offset += sunk;
+
+        // Drain compressed output
+        size_t outSz = 0;
+        HSE_poll_res pres;
+        do {
+            pres = heatshrink_encoder_poll(&importEncoder, outBuf, OUT_BUF_SIZE, &outSz);
+            if (pres < 0) {
+                importError = "Compression error";
+                importFile.close();
+                SPIFFS.remove(importFilePath);
+                importing = false;
+                return false;
+            }
+            if (outSz > 0) {
+                importFile.write(outBuf, outSz);
+            }
+        } while (pres == HSER_POLL_MORE);
+    }
+    return true;
+}
+
+bool CleaningHistory::endImport() {
+    if (!importing || !importFile) {
+        importError = "No import in progress";
+        return false;
+    }
+
+    static const size_t OUT_BUF_SIZE = 512;
+    uint8_t outBuf[OUT_BUF_SIZE];
+
+    // Finish the encoder — may require multiple poll rounds
+    bool done = false;
+    while (!done) {
+        HSE_finish_res fres = heatshrink_encoder_finish(&importEncoder);
+        if (fres < 0) {
+            importError = "Compression finish error";
+            importFile.close();
+            SPIFFS.remove(importFilePath);
+            importing = false;
+            return false;
+        }
+        done = (fres == HSER_FINISH_DONE);
+
+        size_t outSz = 0;
+        HSE_poll_res pres;
+        do {
+            pres = heatshrink_encoder_poll(&importEncoder, outBuf, OUT_BUF_SIZE, &outSz);
+            if (pres < 0) {
+                importError = "Compression finish error";
+                importFile.close();
+                SPIFFS.remove(importFilePath);
+                importing = false;
+                return false;
+            }
+            if (outSz > 0) {
+                importFile.write(outBuf, outSz);
+            }
+        } while (pres == HSER_POLL_MORE);
+    }
+
+    importFile.close();
+    importing = false;
+    LOG("HIST", "Import complete: %s", importFilePath.c_str());
+    dataLogger.logGenericEvent("history_import", {{"path", importFilePath, FIELD_STRING}});
+
+    // Delete oldest sessions if storage budget exceeded
+    enforceLimits();
+
+    return true;
+}
diff --git a/firmware/src/cleaning_history.h b/firmware/src/cleaning_history.h
index 12c987e..5db163f 100644
--- a/firmware/src/cleaning_history.h
+++ b/firmware/src/cleaning_history.h
@@ -1,198 +1,198 @@
-#ifndef CLEANING_HISTORY_H
-#define CLEANING_HISTORY_H
-
-#include <Arduino.h>
-#include <map>
-#include <memory>
-#include <set>
-#include "config.h"
-#include "data_logger.h"
-#include "neato_commands.h"
-
-class NeatoSerial;
-class SystemManager;
-
-// Last completed cleaning session stats — populated at end of each session,
-// read by NotificationManager to enrich "cleaning done" notifications.
-struct LastCleanStats {
-    bool valid = false;          // True after at least one completed session
-    String mode;                 // "house", "spot", or "manual"
-    long durationSec = 0;        // Cleaning duration in seconds
-    float areaCoveredM2 = 0.0f;  // Estimated area in square meters
-    float distanceM = 0.0f;      // Total distance traveled in meters
-    int batteryStart = -1;       // Battery % at session start
-    int batteryEnd = -1;         // Battery % at session end
-    int recharges = 0;           // Mid-clean recharge count
-    // Bumped every time a session is finalized (success or discard) so that
-    // NotificationManager can detect when stopCollection's async charger fetch
-    // has completed and the stats above reflect the just-ended session.
-    uint32_t sessionId = 0;
-};
-
-// Session metadata returned by listSessions() — includes the raw JSON of
-// the session header line and (if finished) the summary line so the frontend
-// can render list cards without fetching each file's full content.
-struct HistorySessionInfo {
-    String name; // Filename (e.g. "1771683615.jsonl.hs")
-    size_t size = 0; // File size in bytes
-    bool compressed = false;
-    bool recording = false; // True if this is the active recording session
-    String session; // Raw JSON of first line ({"type":"session",...})
-    String summary; // Raw JSON of last line ({"type":"summary",...}), empty if still recording
-};
-
-// Records robot pose data during autonomous cleaning runs and stores each
-// session as a JSONL file on SPIFFS. During collection, raw JSONL lines are
-// buffered and flushed to /history/<epoch>.jsonl. When cleaning ends, the
-// file is compressed to .jsonl.hs via incremental heatshrink encoding
-// (non-blocking, spread across tick() calls).
-//
-// Files are served through the same LogReader/CompressedLogReader/PlainLogReader
-// abstractions used by DataLogger, so the web server streaming code is identical.
-
-class CleaningHistory : public LoopTask {
-public:
-    CleaningHistory(NeatoSerial& neato, DataLogger& logger, SystemManager& sysMgr);
-
-    // -- File management (for API, mirrors DataLogger pattern) ----------------
-
-    std::vector<HistorySessionInfo> listSessions();
-    std::shared_ptr<LogReader> readSession(const String& filename);
-    bool deleteSession(const String& filename);
-    void deleteAllSessions();
-
-    // Last completed session stats (for notification enrichment)
-    const LastCleanStats& getLastCleanStats() const { return lastCleanStats; }
-
-    // Called by WebServer when a clean command is sent via API.
-    // Switches to active polling so collection starts immediately
-    // instead of waiting for the next idle-interval tick.
-    void notifyCleanStart();
-
-    // -- Session import (upload from browser, compress-on-write) ---------------
-    // Called by WebServer upload handler. Receives raw JSONL data from the browser,
-    // compresses it via heatshrink, and writes directly to /history/<name>.jsonl.hs.
-
-    // Prepare for import. Returns false with an error message if busy or file exists.
-    bool beginImport(const String& filename);
-    // Feed a chunk of raw JSONL data into the compressor and write to disk.
-    bool writeImportChunk(const uint8_t *data, size_t len);
-    // Finalize the encoder, flush remaining bytes, close file. Returns true on success.
-    bool endImport();
-    bool isImporting() const { return importing; }
-    const String& getImportError() const { return importError; }
-
-private:
-    void tick() override;
-
-    NeatoSerial& neato;
-    DataLogger& dataLogger;
-    SystemManager& systemManager;
-
-    // -- Last session stats (survives reset, updated at end of each session) --
-    LastCleanStats lastCleanStats;
-    uint32_t sessionCounter = 0; // Source of truth for lastCleanStats.sessionId
-
-    // -- State tracking ------------------------------------------------------
-    String prevUiState;
-    bool collecting = false;
-    bool recharging = false;
-    bool fetchPending = false;
-    bool recoveryAttempted = false; // Only try orphan recovery once after boot
-    size_t snapshotCount = 0;
-
-    // Active session file (open during collection, closed at end)
-    File activeFile;
-    String activeFilePath; // e.g. "/history/1771683615.jsonl"
-
-    // -- Session metadata ----------------------------------------------------
-    String cleanMode;
-    time_t sessionStartTime = 0;
-    int batteryStart = -1;
-
-    // -- Session accumulators ------------------------------------------------
-    int rechargeCount = 0;
-    float totalDistance = 0.0f;
-    float totalRotation = 0.0f;
-    float maxDistFromOrigin = 0.0f;
-    int errorsDuringClean = 0;
-    bool prevHadError = false;
-
-    // Previous pose for delta calculations
-    float prevX = 0.0f;
-    float prevY = 0.0f;
-    float prevTheta = 0.0f;
-    float originX = 0.0f;
-    float originY = 0.0f;
-    bool hasPrevPose = false;
-
-    // Coarse area coverage — set of visited grid cells
-    std::set<uint32_t> visitedCells;
-
-    // -- End-of-session compression (incremental, non-blocking) ---------------
-    bool compressing = false;
-    File compressSrc;
-    File compressDst;
-    heatshrink_encoder compressEncoder;
-    bool compressInputDone = false;
-    String compressSrcPath;
-    String compressDstPath;
-
-    bool compressStep(); // Returns true when done
-
-    // -- Collection lifecycle ------------------------------------------------
-    void checkState();
-    void startCollection(const String& uiState);
-    void stopCollection();
-    void collectSnapshot();
-    void writeLine(const String& line); // Immediate write + flush (headers, summaries)
-    void bufferLine(const String& line); // Buffer for deferred flush (pose snapshots)
-    void flushWriteBuffer(); // Flush buffered lines to disk
-    std::vector<String> writeBuffer;
-    unsigned long lastFlushMs = 0;
-    void writeSessionHeader();
-    void writeSessionSummary(int batteryEnd);
-    void writeSnapshot(float x, float y, float theta, float time);
-    void updateAccumulators(float x, float y, float theta);
-    void resetSession();
-    bool replayLine(const String& line);
-    bool recoverCollection(const String& uiState);
-    void finalizeOrphanSessions();
-
-    // Storage enforcement — delete oldest sessions when budget exceeded
-    void enforceLimits();
-
-    // -- Import state (separate from recording compression) -------------------
-    bool importing = false;
-    File importFile;
-    heatshrink_encoder importEncoder;
-    String importFilePath; // e.g. "/history/1771683615.jsonl.hs"
-    String importError;
-    size_t importBytesReceived = 0;
-
-    // Read first and last lines from a session file (decompresses .hs files)
-    static void readFirstLastLines(const String& path, bool compressed, String& firstLine, String& lastLine);
-
-    // -- Metadata cache (avoids repeated decompression for listSessions) ------
-    // Keyed by filename (e.g. "1771683615.jsonl.hs"). Populated on first list
-    // request and after compression/import. Entries are immutable once a session
-    // is finalized — invalidated only by delete/deleteAll/enforceLimits.
-    struct CachedMeta {
-        String session; // Raw JSON of session header line
-        String summary; // Raw JSON of summary line
-    };
-    std::map<String, CachedMeta> metaCache;
-
-    // Session/summary JSON captured during stopCollection for cache insertion
-    // after compression completes (avoids re-decompressing the just-written file).
-    String pendingSessionJson;
-    String pendingSummaryJson;
-
-    static bool isCleaningState(const String& uiState);
-    static bool isPausedState(const String& uiState);
-    static bool isDockingState(const String& uiState);
-    static bool isSuspendedState(const String& uiState);
-    static String cleanModeFromState(const String& uiState);
-};
-
-#endif // CLEANING_HISTORY_H
+#ifndef CLEANING_HISTORY_H
+#define CLEANING_HISTORY_H
+
+#include <Arduino.h>
+#include <map>
+#include <memory>
+#include <set>
+#include "config.h"
+#include "data_logger.h"
+#include "neato_commands.h"
+
+class NeatoSerial;
+class SystemManager;
+
+// Last completed cleaning session stats — populated at end of each session,
+// read by NotificationManager to enrich "cleaning done" notifications.
+struct LastCleanStats {
+    bool valid = false; // True after at least one completed session
+    String mode; // "house", "spot", or "manual"
+    long durationSec = 0; // Cleaning duration in seconds
+    float areaCoveredM2 = 0.0f; // Estimated area in square meters
+    float distanceM = 0.0f; // Total distance traveled in meters
+    int batteryStart = -1; // Battery % at session start
+    int batteryEnd = -1; // Battery % at session end
+    int recharges = 0; // Mid-clean recharge count
+    // Bumped every time a session is finalized (success or discard) so that
+    // NotificationManager can detect when stopCollection's async charger fetch
+    // has completed and the stats above reflect the just-ended session.
+    uint32_t sessionId = 0;
+};
+
+// Session metadata returned by listSessions() — includes the raw JSON of
+// the session header line and (if finished) the summary line so the frontend
+// can render list cards without fetching each file's full content.
+struct HistorySessionInfo {
+    String name; // Filename (e.g. "1771683615.jsonl.hs")
+    size_t size = 0; // File size in bytes
+    bool compressed = false;
+    bool recording = false; // True if this is the active recording session
+    String session; // Raw JSON of first line ({"type":"session",...})
+    String summary; // Raw JSON of last line ({"type":"summary",...}), empty if still recording
+};
+
+// Records robot pose data during autonomous cleaning runs and stores each
+// session as a JSONL file on SPIFFS. During collection, raw JSONL lines are
+// buffered and flushed to /history/<epoch>.jsonl. When cleaning ends, the
+// file is compressed to .jsonl.hs via incremental heatshrink encoding
+// (non-blocking, spread across tick() calls).
+//
+// Files are served through the same LogReader/CompressedLogReader/PlainLogReader
+// abstractions used by DataLogger, so the web server streaming code is identical.
+
+class CleaningHistory : public LoopTask {
+public:
+    CleaningHistory(NeatoSerial& neato, DataLogger& logger, SystemManager& sysMgr);
+
+    // -- File management (for API, mirrors DataLogger pattern) ----------------
+
+    std::vector<HistorySessionInfo> listSessions();
+    std::shared_ptr<LogReader> readSession(const String& filename);
+    bool deleteSession(const String& filename);
+    void deleteAllSessions();
+
+    // Last completed session stats (for notification enrichment)
+    const LastCleanStats& getLastCleanStats() const { return lastCleanStats; }
+
+    // Called by WebServer when a clean command is sent via API.
+    // Switches to active polling so collection starts immediately
+    // instead of waiting for the next idle-interval tick.
+    void notifyCleanStart();
+
+    // -- Session import (upload from browser, compress-on-write) ---------------
+    // Called by WebServer upload handler. Receives raw JSONL data from the browser,
+    // compresses it via heatshrink, and writes directly to /history/<name>.jsonl.hs.
+
+    // Prepare for import. Returns false with an error message if busy or file exists.
+    bool beginImport(const String& filename);
+    // Feed a chunk of raw JSONL data into the compressor and write to disk.
+    bool writeImportChunk(const uint8_t *data, size_t len);
+    // Finalize the encoder, flush remaining bytes, close file. Returns true on success.
+    bool endImport();
+    bool isImporting() const { return importing; }
+    const String& getImportError() const { return importError; }
+
+private:
+    void tick() override;
+
+    NeatoSerial& neato;
+    DataLogger& dataLogger;
+    SystemManager& systemManager;
+
+    // -- Last session stats (survives reset, updated at end of each session) --
+    LastCleanStats lastCleanStats;
+    uint32_t sessionCounter = 0; // Source of truth for lastCleanStats.sessionId
+
+    // -- State tracking ------------------------------------------------------
+    String prevUiState;
+    bool collecting = false;
+    bool recharging = false;
+    bool fetchPending = false;
+    bool recoveryAttempted = false; // Only try orphan recovery once after boot
+    size_t snapshotCount = 0;
+
+    // Active session file (open during collection, closed at end)
+    File activeFile;
+    String activeFilePath; // e.g. "/history/1771683615.jsonl"
+
+    // -- Session metadata ----------------------------------------------------
+    String cleanMode;
+    time_t sessionStartTime = 0;
+    int batteryStart = -1;
+
+    // -- Session accumulators ------------------------------------------------
+    int rechargeCount = 0;
+    float totalDistance = 0.0f;
+    float totalRotation = 0.0f;
+    float maxDistFromOrigin = 0.0f;
+    int errorsDuringClean = 0;
+    bool prevHadError = false;
+
+    // Previous pose for delta calculations
+    float prevX = 0.0f;
+    float prevY = 0.0f;
+    float prevTheta = 0.0f;
+    float originX = 0.0f;
+    float originY = 0.0f;
+    bool hasPrevPose = false;
+
+    // Coarse area coverage — set of visited grid cells
+    std::set<uint32_t> visitedCells;
+
+    // -- End-of-session compression (incremental, non-blocking) ---------------
+    bool compressing = false;
+    File compressSrc;
+    File compressDst;
+    heatshrink_encoder compressEncoder;
+    bool compressInputDone = false;
+    String compressSrcPath;
+    String compressDstPath;
+
+    bool compressStep(); // Returns true when done
+
+    // -- Collection lifecycle ------------------------------------------------
+    void checkState();
+    void startCollection(const String& uiState);
+    void stopCollection();
+    void collectSnapshot();
+    void writeLine(const String& line); // Immediate write + flush (headers, summaries)
+    void bufferLine(const String& line); // Buffer for deferred flush (pose snapshots)
+    void flushWriteBuffer(); // Flush buffered lines to disk
+    std::vector<String> writeBuffer;
+    unsigned long lastFlushMs = 0;
+    void writeSessionHeader();
+    void writeSessionSummary(int batteryEnd);
+    void writeSnapshot(float x, float y, float theta, float time);
+    void updateAccumulators(float x, float y, float theta);
+    void resetSession();
+    bool replayLine(const String& line);
+    bool recoverCollection(const String& uiState);
+    void finalizeOrphanSessions();
+
+    // Storage enforcement — delete oldest sessions when budget exceeded
+    void enforceLimits();
+
+    // -- Import state (separate from recording compression) -------------------
+    bool importing = false;
+    File importFile;
+    heatshrink_encoder importEncoder;
+    String importFilePath; // e.g. "/history/1771683615.jsonl.hs"
+    String importError;
+    size_t importBytesReceived = 0;
+
+    // Read first and last lines from a session file (decompresses .hs files)
+    static void readFirstLastLines(const String& path, bool compressed, String& firstLine, String& lastLine);
+
+    // -- Metadata cache (avoids repeated decompression for listSessions) ------
+    // Keyed by filename (e.g. "1771683615.jsonl.hs"). Populated on first list
+    // request and after compression/import. Entries are immutable once a session
+    // is finalized — invalidated only by delete/deleteAll/enforceLimits.
+    struct CachedMeta {
+        String session; // Raw JSON of session header line
+        String summary; // Raw JSON of summary line
+    };
+    std::map<String, CachedMeta> metaCache;
+
+    // Session/summary JSON captured during stopCollection for cache insertion
+    // after compression completes (avoids re-decompressing the just-written file).
+    String pendingSessionJson;
+    String pendingSummaryJson;
+
+    static bool isCleaningState(const String& uiState);
+    static bool isPausedState(const String& uiState);
+    static bool isDockingState(const String& uiState);
+    static bool isSuspendedState(const String& uiState);
+    static String cleanModeFromState(const String& uiState);
+};
+
+#endif // CLEANING_HISTORY_H
diff --git a/firmware/src/neato_serial.cpp b/firmware/src/neato_serial.cpp
index 80b5338..56402e7 100644
--- a/firmware/src/neato_serial.cpp
+++ b/firmware/src/neato_serial.cpp
@@ -1,794 +1,793 @@
-#include "neato_serial.h"
-#include "config.h"
-
-// -- Lifecycle ---------------------------------------------------------------
-
-// Helper: create a cache hit lambda that fires loggerCallback with cached=true.
-// Captures `this` so it reads loggerCallback at call time (works before setLogger).
-#define CACHE_HIT(CMD)                                                                                                 \
-    [this](unsigned long ageMs) {                                                                                      \
-        if (loggerCallback)                                                                                            \
-            loggerCallback(CMD, CMD_SUCCESS, 0, "", 0, 0, ageMs);                                                      \
-    }
-
-NeatoSerial::NeatoSerial() :
-    LoopTask(0), versionCache(
-                         CACHE_TTL_VERSION, [this](AsyncCache<VersionData>::Callback cb) { fetchVersion(cb); },
-                         CACHE_HIT(CMD_GET_VERSION)),
-    chargerCache(
-            CACHE_TTL_CHARGER, [this](AsyncCache<ChargerData>::Callback cb) { fetchCharger(cb); },
-            CACHE_HIT(CMD_GET_CHARGER)),
-    analogCache(
-            CACHE_TTL_SENSORS, [this](AsyncCache<BatteryAnalogData>::Callback cb) { fetchBatteryAnalog(cb); },
-            CACHE_HIT(CMD_GET_ANALOG_SENSORS)),
-    warrantyCache(
-            CACHE_TTL_VERSION, [this](AsyncCache<BatteryWarrantyData>::Callback cb) { fetchBatteryWarranty(cb); },
-            CACHE_HIT(CMD_GET_WARRANTY)),
-    digitalCache(
-            CACHE_TTL_SENSORS, [this](AsyncCache<DigitalSensorData>::Callback cb) { fetchDigitalSensors(cb); },
-            CACHE_HIT(CMD_GET_DIGITAL_SENSORS)),
-    motorCache(
-            CACHE_TTL_SENSORS, [this](AsyncCache<MotorData>::Callback cb) { fetchMotors(cb); },
-            CACHE_HIT(CMD_GET_MOTORS)),
-    stateCache(
-            CACHE_TTL_STATE, [this](AsyncCache<RobotState>::Callback cb) { fetchState(cb); }, CACHE_HIT(CMD_GET_STATE)),
-    errCache(
-            CACHE_TTL_STATE, [this](AsyncCache<ErrorData>::Callback cb) { fetchErr(cb); }, CACHE_HIT(CMD_GET_ERR)),
-    ldsCache(
-            CACHE_TTL_LDS, [this](AsyncCache<LdsScanData>::Callback cb) { fetchLdsScan(cb); },
-            CACHE_HIT(CMD_GET_LDS_SCAN)),
-    robotPosRawCache(
-            CACHE_TTL_SENSORS,
-            [this](AsyncCache<RobotPosData>::Callback cb) { fetchRobotPos(CMD_GET_ROBOT_POS_RAW, cb); },
-            CACHE_HIT(CMD_GET_ROBOT_POS_RAW)),
-    robotPosSmoothCache(
-            CACHE_TTL_SENSORS,
-            [this](AsyncCache<RobotPosData>::Callback cb) { fetchRobotPos(CMD_GET_ROBOT_POS_SMOOTH, cb); },
-            CACHE_HIT(CMD_GET_ROBOT_POS_SMOOTH)),
-    userSettingsCache(
-            CACHE_TTL_VERSION, [this](AsyncCache<UserSettingsData>::Callback cb) { fetchUserSettings(cb); },
-            CACHE_HIT(CMD_GET_USER_SETTINGS)) {
-    TaskRegistry::add(this);
-}
-
-#undef CACHE_HIT
-
-void NeatoSerial::begin(int txPin, int rxPin) {
-    uart.setRxBufferSize(NEATO_UART_RX_BUFFER);
-    uart.begin(NEATO_BAUD_RATE, SERIAL_8N1, rxPin, txPin);
-    LOG("NEATO", "UART initialized (TX=GPIO%d, RX=GPIO%d, baud=%d)", txPin, rxPin, NEATO_BAUD_RATE);
-}
-
-void NeatoSerial::initSKey() {
-    sKeyPending = true;
-    versionCache.invalidate(); // Force a fresh fetch (don't serve a stale failure)
-    getVersion([this](bool ok, const VersionData& v) {
-        if (!ok || v.serialNumber.length() == 0) {
-            LOG("NEATO", "SKey init failed — GetVersion returned no serial, retrying in %lu ms", sKeyRetryDelay);
-            sKeyRetryAt = millis() + sKeyRetryDelay;
-            sKeyRetryDelay = (sKeyRetryDelay * 2 < SKEY_RETRY_MAX_MS) ? sKeyRetryDelay * 2 : SKEY_RETRY_MAX_MS;
-            return;
-        }
-        sKeyPending = false;
-        robotModelName = v.modelName;
-        LOG("NEATO", "Model: %s (supported=%s)", robotModelName.c_str(),
-            isSupportedModel(robotModelName) ? "yes" : "no");
-        sKey = computeSKey(v.serialNumber);
-        if (sKey.length() > 0) {
-            LOG("NEATO", "SKey computed (%d chars) from serial %s", sKey.length(), v.serialNumber.c_str());
-        } else {
-            LOG("NEATO", "SKey computation failed for serial: %s", v.serialNumber.c_str());
-        }
-    });
-}
-
-String NeatoSerial::buildSetEvent(const char *event) const {
-    return String(CMD_SET_EVENT_PREFIX) + event + CMD_SET_EVENT_SKEY + sKey;
-}
-
-void NeatoSerial::tick() {
-    // Drive initSKey lifecycle: first attempt + retries on failure.
-    // Runs inside tick() (not setup()) so the UART state machine is already
-    // processing the queue — avoids the race where GetVersion was enqueued
-    // in setup() but tick() hadn't started yet.
-    if (sKeyPending && millis() >= sKeyRetryAt) {
-        sKeyRetryAt = ULONG_MAX; // Prevent re-entry while fetch is in flight
-        initSKey();
-    }
-
-    switch (state) {
-        case QUEUE_IDLE:
-            if (!queue.empty()) {
-                dequeueNext();
-            }
-            break;
-
-        case QUEUE_SENDING:
-            sendCurrentCommand();
-            break;
-
-        case QUEUE_WAITING_RESPONSE: {
-            // Read all available bytes
-            while (uart.available()) {
-                char c = static_cast<char>(uart.read());
-                if (c == NEATO_RESPONSE_TERMINATOR) {
-                    unsigned long elapsed = millis() - commandSentAt;
-                    LOG("NEATO", "RX: %u bytes in %lu ms", responseBuffer.length(), elapsed);
-
-                    // Validate: response must echo the sent command on the first line.
-                    // If it doesn't, the UART stream is desynced (we got a response
-                    // meant for a different command). Flush and fail this request so
-                    // the next command starts clean.
-                    if (!validateResponseEcho(responseBuffer)) {
-                        LOG("NEATO", "DESYNC: sent '%s' but response echoed a different command, flushing",
-                            currentCommand.c_str());
-                        flushUartRx();
-                        completeCommand(CMD_SERIAL_ERROR, responseBuffer);
-                        return;
-                    }
-
-                    // Detect "Unknown Cmd" — robot doesn't support this command
-                    if (responseBuffer.indexOf("Unknown Cmd") >= 0) {
-                        LOG("NEATO", "Unsupported: %s", currentCommand.c_str());
-                        completeCommand(CMD_UNSUPPORTED, responseBuffer);
-                        return;
-                    }
-
-                    completeCommand(CMD_SUCCESS, responseBuffer);
-                    return;
-                }
-                responseBuffer += c;
-            }
-            // Check timeout
-            if (millis() - commandSentAt >= NEATO_CMD_TIMEOUT_MS) {
-                LOG("NEATO", "Timeout: %s (%lu ms, partial: %u bytes)", currentCommand.c_str(),
-                    (unsigned long) NEATO_CMD_TIMEOUT_MS, responseBuffer.length());
-                // Log partial response on timeout (useful for debugging serial issues).
-                // Flush UART to prevent stale bytes from leaking into the next command.
-                flushUartRx();
-                completeCommand(CMD_TIMEOUT, responseBuffer);
-            }
-            break;
-        }
-
-        case QUEUE_INTER_DELAY:
-            if (millis() - delayStartedAt >= NEATO_INTER_CMD_DELAY_MS) {
-                state = QUEUE_IDLE;
-            }
-            break;
-    }
-}
-
-// -- Queue management --------------------------------------------------------
-
-bool NeatoSerial::enqueue(const String& command, std::function<void(bool, const String&)> callback,
-                          CommandPriority priority) {
-    if (static_cast<int>(queue.size()) >= NEATO_QUEUE_MAX_SIZE) {
-        LOG("NEATO", "Queue full, rejecting: %s", command.c_str());
-        if (loggerCallback)
-            loggerCallback(command, CMD_QUEUE_FULL, 0, "", static_cast<int>(queue.size()), 0, 0);
-        if (callback)
-            callback(false, "");
-        return false;
-    }
-    // Lower number = higher priority. Keep FIFO order within same priority.
-    auto it = queue.begin();
-    for (; it != queue.end(); ++it) {
-        if (it->priority > priority)
-            break;
-    }
-    queue.insert(it, {command, static_cast<uint8_t>(priority), callback});
-    return true;
-}
-
-std::function<void(bool, const String&)> NeatoSerial::wrapAction(std::function<void(bool)> callback) {
-    if (!callback)
-        return nullptr;
-    return [callback](bool ok, const String&) { callback(ok); };
-}
-
-void NeatoSerial::dequeueNext() {
-    if (queue.empty())
-        return;
-
-    // Capture queue depth before dequeue (for logging)
-    queueDepthAtStart = static_cast<int>(queue.size());
-
-    CommandEntry entry = queue.front();
-    queue.erase(queue.begin());
-
-    currentCommand = entry.command;
-    currentCallback = entry.callback;
-    responseBuffer = "";
-
-    state = QUEUE_SENDING;
-}
-
-void NeatoSerial::flushUartRx() {
-    int flushed = 0;
-    while (uart.available()) {
-        uart.read();
-        flushed++;
-    }
-    if (flushed > 0) {
-        LOG("NEATO", "Flushed %d stale bytes from UART RX", flushed);
-    }
-}
-
-void NeatoSerial::sendCurrentCommand() {
-    // Drain any stale bytes from a previous response that may have arrived late
-    flushUartRx();
-
-    LOG("NEATO", "TX: %s", currentCommand.c_str());
-    uart.print(currentCommand + "\n");
-    commandSentAt = millis();
-    state = QUEUE_WAITING_RESPONSE;
-}
-
-bool NeatoSerial::validateResponseEcho(const String& response) const {
-    // The Neato echoes the command on the first line of the response,
-    // e.g. "GetCharger\r\nLabel,Value\r\n...". Extract the first word of the
-    // sent command (before any space/flag) and check the response starts with it.
-    // Some commands echo only the name ("Clean" for "Clean House"), while others
-    // echo the full command with arguments ("TestMode On" for "TestMode On").
-    // Using startsWith handles both cases.
-    String expectedEcho = currentCommand;
-    int spacePos = expectedEcho.indexOf(' ');
-    if (spacePos > 0)
-        expectedEcho = expectedEcho.substring(0, spacePos);
-
-    // Find the first line in the response (up to \r or \n)
-    String firstLine = response;
-    int crPos = firstLine.indexOf('\r');
-    int lfPos = firstLine.indexOf('\n');
-    int lineEnd = -1;
-    if (crPos >= 0 && lfPos >= 0)
-        lineEnd = (crPos < lfPos) ? crPos : lfPos;
-    else if (crPos >= 0)
-        lineEnd = crPos;
-    else if (lfPos >= 0)
-        lineEnd = lfPos;
-    if (lineEnd >= 0)
-        firstLine = firstLine.substring(0, lineEnd);
-
-    // Check that the echo line starts with the expected command name (case-insensitive).
-    firstLine.trim();
-    expectedEcho.trim();
-    firstLine.toLowerCase();
-    expectedEcho.toLowerCase();
-    return firstLine.startsWith(expectedEcho);
-}
-
-void NeatoSerial::completeCommand(CommandStatus status, const String& response) {
-    unsigned long elapsed = millis() - commandSentAt;
-    String cmd = currentCommand;
-    auto cb = currentCallback;
-    int qDepth = queueDepthAtStart;
-    String resp = response; // Copy before clearing responseBuffer (response is a ref to it)
-    size_t respBytes = resp.length();
-
-    currentCommand = "";
-    currentCallback = nullptr;
-    responseBuffer = "";
-    queueDepthAtStart = 0;
-
-    // Start inter-command delay before next command
-    delayStartedAt = millis();
-    state = QUEUE_INTER_DELAY;
-
-    // Fire logger hook before user callback with enhanced metadata
-    if (loggerCallback)
-        loggerCallback(cmd, status, elapsed, resp, qDepth, respBytes, 0);
-
-    // User callback still gets simple bool for backward compatibility
-    bool success = (status == CMD_SUCCESS);
-    if (cb)
-        cb(success, resp);
-}
-
-// -- Cached sensor query methods (public API) --------------------------------
-// These delegate to AsyncCache, which handles TTL, dedup, and coalescing.
-
-void NeatoSerial::getVersion(std::function<void(bool, const VersionData&)> callback) {
-    versionCache.get(callback);
-}
-
-void NeatoSerial::getCharger(std::function<void(bool, const ChargerData&)> callback) {
-    chargerCache.get(callback);
-}
-
-void NeatoSerial::getBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
-    analogCache.get(callback);
-}
-
-void NeatoSerial::getBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
-    warrantyCache.get(callback);
-}
-
-void NeatoSerial::getUserSettings(std::function<void(bool, const UserSettingsData&)> callback) {
-    userSettingsCache.get(callback);
-}
-
-void NeatoSerial::getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback) {
-    getDigitalSensors(callback, PRIORITY_NORMAL);
-}
-
-void NeatoSerial::getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
-                                    CommandPriority priority) {
-    // Normal priority goes through cache; elevated priority bypasses it
-    // to guarantee commands are enqueued at the requested priority.
-    if (priority == PRIORITY_NORMAL) {
-        digitalCache.get(callback);
-    } else {
-        fetchDigitalSensors(callback, priority);
-    }
-}
-
-void NeatoSerial::getMotors(std::function<void(bool, const MotorData&)> callback) {
-    getMotors(callback, PRIORITY_NORMAL);
-}
-
-void NeatoSerial::getMotors(std::function<void(bool, const MotorData&)> callback, CommandPriority priority) {
-    // Normal priority goes through cache; elevated priority bypasses it
-    // to guarantee commands are enqueued at the requested priority.
-    if (priority == PRIORITY_NORMAL) {
-        motorCache.get(callback);
-    } else {
-        fetchMotors(callback, priority);
-    }
-}
-
-void NeatoSerial::getState(std::function<void(bool, const RobotState&)> callback) {
-    // During manual clean, the robot reports UIMGR_STATE_TESTMODE.
-    // Override to UIMGR_STATE_MANUALCLEANING so callers (frontend, dashboard)
-    // see the correct pseudo-state without needing to know about TestMode internals.
-    if (manualCleanActive) {
-        stateCache.get([callback](bool ok, const RobotState& data) {
-            if (!ok || !callback) {
-                if (callback)
-                    callback(ok, data);
-                return;
-            }
-            RobotState patched = data;
-            patched.uiState = "UIMGR_STATE_MANUALCLEANING";
-            callback(true, patched);
-        });
-        return;
-    }
-    stateCache.get(callback);
-}
-
-void NeatoSerial::getErr(std::function<void(bool, const ErrorData&)> callback) {
-    errCache.get(callback);
-}
-
-void NeatoSerial::getErrClear(std::function<void(bool, const ErrorData&)> callback) {
-    // getErrClear is never cached — it clears the error and always needs a fresh fetch
-    fetchErrClear(callback);
-}
-
-void NeatoSerial::getLdsScan(std::function<void(bool, const LdsScanData&)> callback) {
-    ldsCache.get(callback);
-}
-
-void NeatoSerial::getRobotPos(bool smooth, std::function<void(bool, const RobotPosData&)> callback) {
-    (smooth ? robotPosSmoothCache : robotPosRawCache).get(callback);
-}
-
-// -- Raw fetch methods (enqueue serial command, parse response) ---------------
-
-void NeatoSerial::fetchVersion(std::function<void(bool, const VersionData&)> callback) {
-    enqueue(CMD_GET_VERSION, [callback](bool ok, const String& raw) {
-        VersionData data;
-        if (ok)
-            ok = parseVersionData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchCharger(std::function<void(bool, const ChargerData&)> callback) {
-    enqueue(CMD_GET_CHARGER, [callback](bool ok, const String& raw) {
-        ChargerData data;
-        if (ok)
-            ok = parseChargerData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
-    enqueue(CMD_GET_ANALOG_SENSORS, [callback](bool ok, const String& raw) {
-        BatteryAnalogData data;
-        if (ok)
-            ok = parseBatteryAnalogData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
-    enqueue(CMD_GET_WARRANTY, [callback](bool ok, const String& raw) {
-        BatteryWarrantyData data;
-        if (ok)
-            ok = parseBatteryWarrantyData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
-                                      CommandPriority priority) {
-    enqueue(
-            CMD_GET_DIGITAL_SENSORS,
-            [callback](bool ok, const String& raw) {
-                DigitalSensorData data;
-                if (ok)
-                    ok = parseDigitalSensorData(raw, data);
-                if (callback)
-                    callback(ok, data);
-            },
-            priority);
-}
-
-void NeatoSerial::fetchMotors(std::function<void(bool, const MotorData&)> callback, CommandPriority priority) {
-    enqueue(
-            CMD_GET_MOTORS,
-            [callback](bool ok, const String& raw) {
-                MotorData data;
-                if (ok)
-                    ok = parseMotorData(raw, data);
-                if (callback)
-                    callback(ok, data);
-            },
-            priority);
-}
-
-void NeatoSerial::fetchState(std::function<void(bool, const RobotState&)> callback) {
-    enqueue(CMD_GET_STATE, [callback](bool ok, const String& raw) {
-        RobotState data;
-        if (ok)
-            ok = parseRobotState(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchErr(std::function<void(bool, const ErrorData&)> callback) {
-    enqueue(CMD_GET_ERR, [callback](bool ok, const String& raw) {
-        ErrorData data;
-        if (ok)
-            ok = parseErrorData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchErrClear(std::function<void(bool, const ErrorData&)> callback) {
-    enqueue(CMD_GET_ERR_CLEAR, [callback](bool ok, const String& raw) {
-        ErrorData data;
-        if (ok)
-            ok = parseErrorData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchLdsScan(std::function<void(bool, const LdsScanData&)> callback) {
-    enqueue(CMD_GET_LDS_SCAN, [callback](bool ok, const String& raw) {
-        LdsScanData data;
-        if (ok)
-            ok = parseLdsScanData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchRobotPos(const char *cmd, std::function<void(bool, const RobotPosData&)> callback) {
-    enqueue(cmd, [callback](bool ok, const String& raw) {
-        RobotPosData data;
-        if (ok)
-            ok = parseRobotPosData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-void NeatoSerial::fetchUserSettings(std::function<void(bool, const UserSettingsData&)> callback) {
-    enqueue(CMD_GET_USER_SETTINGS, [callback](bool ok, const String& raw) {
-        UserSettingsData data;
-        if (ok)
-            ok = parseUserSettingsData(raw, data);
-        if (callback)
-            callback(ok, data);
-    });
-}
-
-// -- Cache invalidation ------------------------------------------------------
-
-void NeatoSerial::invalidateState() {
-    stateCache.invalidate();
-    errCache.invalidate();
-}
-
-void NeatoSerial::invalidateAll() {
-    versionCache.invalidate();
-    chargerCache.invalidate();
-    analogCache.invalidate();
-    warrantyCache.invalidate();
-    digitalCache.invalidate();
-    motorCache.invalidate();
-    stateCache.invalidate();
-    errCache.invalidate();
-    ldsCache.invalidate();
-    robotPosRawCache.invalidate();
-    robotPosSmoothCache.invalidate();
-    userSettingsCache.invalidate();
-}
-
-// -- Action command convenience methods --------------------------------------
-
-bool NeatoSerial::clean(const String& action, std::function<void(bool)> callback) {
-    // All cleaning control uses SetEvent — the authenticated event API that D3-D7
-    // robots use for their cloud/app protocol. This correctly transitions the UI
-    // state machine and preserves map/localization during pause/resume.
-    //
-    // SKey must be computed at boot via initSKey(). If missing, commands will fail
-    // gracefully (callback with false).
-
-    if (!hasSKey()) {
-        LOG("NEATO", "clean(%s) failed — SKey not available", action.c_str());
-        if (callback)
-            callback(false);
-        return false;
-    }
-
-    if (action == "dock") {
-        invalidateState();
-        return enqueue(buildSetEvent(EVT_SEND_TO_BASE), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    if (action == "pause") {
-        invalidateState();
-        return enqueue(buildSetEvent(EVT_PAUSE), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    if (action == "stop") {
-        invalidateState();
-        return enqueue(buildSetEvent(EVT_STOP), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    // Type-aware resume: "house" only resumes a paused house clean, "spot"
-    // only resumes a paused spot clean. Prevents HA "start" from resuming
-    // a previously paused spot clean when the user expects a new house clean.
-    if (action == "house") {
-        bool isPausedHouse =
-                stateCache.hasCached() && stateCache.getCached().uiState.indexOf("HOUSECLEANINGPAUSED") >= 0;
-        if (isPausedHouse) {
-            invalidateState();
-            return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
-        }
-        invalidateState();
-        if (cleanStartCallback)
-            cleanStartCallback();
-        // Send navigation mode first (fire-and-forget); house clean proceeds regardless.
-        if (navModeGetter) {
-            String mode = navModeGetter();
-            if (mode.length() > 0 && mode != "Normal") {
-                String navCmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
-                enqueue(navCmd, nullptr, PRIORITY_HIGH);
-            }
-        }
-        return enqueue(buildSetEvent(EVT_START_HOUSE), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    if (action == "spot") {
-        bool isPausedSpot =
-                stateCache.hasCached() && stateCache.getCached().uiState.indexOf("SPOTCLEANINGPAUSED") >= 0;
-        if (isPausedSpot) {
-            invalidateState();
-            return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
-        }
-        invalidateState();
-        if (cleanStartCallback)
-            cleanStartCallback();
-        return enqueue(buildSetEvent(EVT_START_SPOT), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    // Generic action — resume whatever is paused, or start house clean
-    bool isPaused = stateCache.hasCached() && stateCache.getCached().uiState.indexOf("CLEANINGPAUSED") >= 0;
-    if (isPaused) {
-        invalidateState();
-        return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
-    }
-
-    // New clean from idle — fall through to house clean
-    invalidateState();
-    if (cleanStartCallback)
-        cleanStartCallback();
-    // Send navigation mode first (fire-and-forget); house clean proceeds regardless.
-    if (navModeGetter) {
-        String mode = navModeGetter();
-        if (mode.length() > 0 && mode != "Normal") {
-            String navCmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
-            enqueue(navCmd, nullptr, PRIORITY_HIGH);
-        }
-    }
-    return enqueue(buildSetEvent(EVT_START_HOUSE), wrapAction(callback), PRIORITY_HIGH);
-}
-
-bool NeatoSerial::testMode(bool enable, std::function<void(bool)> callback) {
-    const char *cmd = enable ? CMD_TEST_MODE_ON : CMD_TEST_MODE_OFF;
-    invalidateState();
-    // HIGH priority: TestMode is a prerequisite for motor commands — must execute
-    // before any CRITICAL/MEDIUM motor commands that may already be queued.
-    return enqueue(cmd, wrapAction(callback), PRIORITY_HIGH);
-}
-
-bool NeatoSerial::playSound(SoundId soundId, std::function<void(bool)> callback) {
-    String cmd = String(CMD_PLAY_SOUND) + " SoundID " + String(static_cast<int>(soundId));
-    return enqueue(cmd, wrapAction(callback));
-}
-
-bool NeatoSerial::setLdsRotation(bool on, std::function<void(bool)> callback) {
-    const char *cmd = on ? CMD_SET_LDS_ROTATION_ON : CMD_SET_LDS_ROTATION_OFF;
-    // HIGH priority: LDS rotation is a setup/teardown command that must execute
-    // before motor commands during manual clean enable/disable sequences.
-    return enqueue(cmd, wrapAction(callback), PRIORITY_HIGH);
-}
-
-bool NeatoSerial::setMotorWheels(int leftMM, int rightMM, int speedMMs, std::function<void(bool)> callback) {
-    // SetMotor 0 0 0 bug: zero values are ignored, robot coasts for ~1s.
-    // Workaround: disable wheels for immediate stop, then re-enable for next command.
-    if (leftMM == 0 && rightMM == 0) {
-        return enqueue(
-                String(CMD_SET_MOTOR) + " LWheelDisable RWheelDisable",
-                [this, callback](bool ok, const String&) {
-                    // Re-enable wheels so subsequent move commands work
-                    enqueue(String(CMD_SET_MOTOR) + " LWheelEnable RWheelEnable", wrapAction(callback),
-                            PRIORITY_CRITICAL);
-                },
-                PRIORITY_CRITICAL);
-    }
-    // Robot rejects distances outside ±10000mm — clamp to protocol limits
-    leftMM = constrain(leftMM, -10000, 10000);
-    rightMM = constrain(rightMM, -10000, 10000);
-    speedMMs = constrain(speedMMs, 0, 300);
-    String cmd = String(CMD_SET_MOTOR) + " LWheelDist " + String(leftMM) + " RWheelDist " + String(rightMM) +
-                 " Speed " + String(speedMMs);
-    return enqueue(cmd, wrapAction(callback), PRIORITY_CRITICAL);
-}
-
-bool NeatoSerial::setMotorBrush(int rpm, std::function<void(bool)> callback) {
-    if (rpm <= 0) {
-        return enqueue(String(CMD_SET_MOTOR) + " BrushDisable", wrapAction(callback), PRIORITY_MEDIUM);
-    }
-    // BrushEnable energizes the motor driver, then Brush + RPM starts spinning.
-    // Brush flag is mutually exclusive with wheel/vacuum commands per call.
-    return enqueue(
-            String(CMD_SET_MOTOR) + " BrushEnable",
-            [this, rpm, callback](bool ok, const String&) {
-                if (!ok) {
-                    if (callback)
-                        callback(false);
-                    return;
-                }
-                enqueue(String(CMD_SET_MOTOR) + " Brush RPM " + String(rpm), wrapAction(callback), PRIORITY_MEDIUM);
-            },
-            PRIORITY_MEDIUM);
-}
-
-bool NeatoSerial::setMotorVacuum(bool on, int speedPercent, std::function<void(bool)> callback) {
-    // VacuumSpeed must be combined with VacuumOn in the same call.
-    String cmd = String(CMD_SET_MOTOR);
-    cmd += on ? " VacuumOn VacuumSpeed " + String(speedPercent) : " VacuumOff";
-    return enqueue(cmd, wrapAction(callback), PRIORITY_MEDIUM);
-}
-
-bool NeatoSerial::setMotorSideBrush(bool on, int powerMw, std::function<void(bool)> callback) {
-    // Side brush (Botvac D3-D7 only) uses open-loop power control in milliwatts.
-    // Two-layer control: SideBrushEnable energizes motor driver, SideBrushOn starts spinning.
-    // Completely independent from the main brush.
-    if (!on) {
-        return enqueue(
-                String(CMD_SET_MOTOR) + " SideBrushOff",
-                [this, callback](bool ok, const String&) {
-                    // Best-effort disable after stopping
-                    enqueue(String(CMD_SET_MOTOR) + " SideBrushDisable", wrapAction(callback), PRIORITY_MEDIUM);
-                },
-                PRIORITY_MEDIUM);
-    }
-    return enqueue(
-            String(CMD_SET_MOTOR) + " SideBrushEnable",
-            [this, powerMw, callback](bool ok, const String&) {
-                if (!ok) {
-                    if (callback)
-                        callback(false);
-                    return;
-                }
-                enqueue(String(CMD_SET_MOTOR) + " SideBrushOn SideBrushPower " + String(powerMw), wrapAction(callback),
-                        PRIORITY_MEDIUM);
-            },
-            PRIORITY_MEDIUM);
-}
-
-// -- User settings -----------------------------------------------------------
-
-bool NeatoSerial::setUserSetting(const String& key, const String& value, std::function<void(bool)> callback) {
-    userSettingsCache.invalidate();
-    String cmd = String(CMD_SET_USER_SETTINGS) + " " + key + " " + value;
-    return enqueue(cmd, wrapAction(callback));
-}
-
-bool NeatoSerial::setNavigationMode(const String& mode, std::function<void(bool)> callback) {
-    String cmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
-    return enqueue(cmd, wrapAction(callback));
-}
-
-// -- Power control -----------------------------------------------------------
-
-bool NeatoSerial::powerControl(const String& action, std::function<void(bool)> callback) {
-    const char *cmd;
-    if (action == "restart") {
-        cmd = CMD_SET_SYSTEM_MODE_POWER_CYCLE;
-    } else if (action == "shutdown") {
-        cmd = CMD_SET_SYSTEM_MODE_SHUTDOWN;
-    } else {
-        LOG("NEATO", "powerControl: unknown action '%s'", action.c_str());
-        if (callback)
-            callback(false);
-        return false;
-    }
-
-    // SetSystemMode requires TestMode On first (protocol specifies 100ms delay,
-    // which the inter-command delay covers). Chain: TestMode On -> SetSystemMode.
-    invalidateState();
-    const char *sysCmd = cmd; // capture for lambda
-    return testMode(true, [this, sysCmd, callback](bool ok) {
-        if (!ok) {
-            LOG("NEATO", "powerControl: TestMode On failed");
-            if (callback)
-                callback(false);
-            return;
-        }
-        enqueue(sysCmd, wrapAction(callback), PRIORITY_HIGH);
-    });
-}
-
-// -- Clear errors ------------------------------------------------------------
-
-bool NeatoSerial::clearErrors(std::function<void(bool)> callback) {
-    invalidateState();
-    return enqueue(CMD_SET_UI_ERROR_CLEAR_ALL, wrapAction(callback));
-}
-
-bool NeatoSerial::newBattery(std::function<void(bool)> callback) {
-    invalidateState();
-    return testMode(true, [this, callback](bool ok) {
-        if (!ok) {
-            if (callback)
-                callback(false);
-            return;
-        }
-
-        enqueue(
-                CMD_NEW_BATTERY,
-                [this, callback](bool okCmd, const String&) {
-                    if (!okCmd) {
-                        // Best-effort return robot to normal mode even if NewBattery failed
-                        testMode(false, nullptr);
-                        if (callback)
-                            callback(false);
-                        return;
-                    }
-                    testMode(false, callback);
-                },
-                PRIORITY_HIGH);
-    });
-}
-
-bool NeatoSerial::sendRaw(const String& cmd, std::function<void(bool, const String&)> callback) {
-    if (cmd.isEmpty())
-        return false;
-    return enqueue(cmd, callback);
-}
+#include "neato_serial.h"
+#include "config.h"
+
+// -- Lifecycle ---------------------------------------------------------------
+
+// Helper: create a cache hit lambda that fires loggerCallback with cached=true.
+// Captures `this` so it reads loggerCallback at call time (works before setLogger).
+#define CACHE_HIT(CMD)                                                                                                 \
+    [this](unsigned long ageMs) {                                                                                      \
+        if (loggerCallback)                                                                                            \
+            loggerCallback(CMD, CMD_SUCCESS, 0, "", 0, 0, ageMs);                                                      \
+    }
+
+NeatoSerial::NeatoSerial() :
+    LoopTask(0), versionCache(
+                         CACHE_TTL_VERSION, [this](AsyncCache<VersionData>::Callback cb) { fetchVersion(cb); },
+                         CACHE_HIT(CMD_GET_VERSION)),
+    chargerCache(
+            CACHE_TTL_CHARGER, [this](AsyncCache<ChargerData>::Callback cb) { fetchCharger(cb); },
+            CACHE_HIT(CMD_GET_CHARGER)),
+    analogCache(
+            CACHE_TTL_SENSORS, [this](AsyncCache<BatteryAnalogData>::Callback cb) { fetchBatteryAnalog(cb); },
+            CACHE_HIT(CMD_GET_ANALOG_SENSORS)),
+    warrantyCache(
+            CACHE_TTL_VERSION, [this](AsyncCache<BatteryWarrantyData>::Callback cb) { fetchBatteryWarranty(cb); },
+            CACHE_HIT(CMD_GET_WARRANTY)),
+    digitalCache(
+            CACHE_TTL_SENSORS, [this](AsyncCache<DigitalSensorData>::Callback cb) { fetchDigitalSensors(cb); },
+            CACHE_HIT(CMD_GET_DIGITAL_SENSORS)),
+    motorCache(
+            CACHE_TTL_SENSORS, [this](AsyncCache<MotorData>::Callback cb) { fetchMotors(cb); },
+            CACHE_HIT(CMD_GET_MOTORS)),
+    stateCache(
+            CACHE_TTL_STATE, [this](AsyncCache<RobotState>::Callback cb) { fetchState(cb); }, CACHE_HIT(CMD_GET_STATE)),
+    errCache(
+            CACHE_TTL_STATE, [this](AsyncCache<ErrorData>::Callback cb) { fetchErr(cb); }, CACHE_HIT(CMD_GET_ERR)),
+    ldsCache(
+            CACHE_TTL_LDS, [this](AsyncCache<LdsScanData>::Callback cb) { fetchLdsScan(cb); },
+            CACHE_HIT(CMD_GET_LDS_SCAN)),
+    robotPosRawCache(
+            CACHE_TTL_SENSORS,
+            [this](AsyncCache<RobotPosData>::Callback cb) { fetchRobotPos(CMD_GET_ROBOT_POS_RAW, cb); },
+            CACHE_HIT(CMD_GET_ROBOT_POS_RAW)),
+    robotPosSmoothCache(
+            CACHE_TTL_SENSORS,
+            [this](AsyncCache<RobotPosData>::Callback cb) { fetchRobotPos(CMD_GET_ROBOT_POS_SMOOTH, cb); },
+            CACHE_HIT(CMD_GET_ROBOT_POS_SMOOTH)),
+    userSettingsCache(
+            CACHE_TTL_VERSION, [this](AsyncCache<UserSettingsData>::Callback cb) { fetchUserSettings(cb); },
+            CACHE_HIT(CMD_GET_USER_SETTINGS)) {
+    TaskRegistry::add(this);
+}
+
+#undef CACHE_HIT
+
+void NeatoSerial::begin(int txPin, int rxPin) {
+    uart.setRxBufferSize(NEATO_UART_RX_BUFFER);
+    uart.begin(NEATO_BAUD_RATE, SERIAL_8N1, rxPin, txPin);
+    LOG("NEATO", "UART initialized (TX=GPIO%d, RX=GPIO%d, baud=%d)", txPin, rxPin, NEATO_BAUD_RATE);
+}
+
+void NeatoSerial::initSKey() {
+    sKeyPending = true;
+    versionCache.invalidate(); // Force a fresh fetch (don't serve a stale failure)
+    getVersion([this](bool ok, const VersionData& v) {
+        if (!ok || v.serialNumber.length() == 0) {
+            LOG("NEATO", "SKey init failed — GetVersion returned no serial, retrying in %lu ms", sKeyRetryDelay);
+            sKeyRetryAt = millis() + sKeyRetryDelay;
+            sKeyRetryDelay = (sKeyRetryDelay * 2 < SKEY_RETRY_MAX_MS) ? sKeyRetryDelay * 2 : SKEY_RETRY_MAX_MS;
+            return;
+        }
+        sKeyPending = false;
+        robotModelName = v.modelName;
+        LOG("NEATO", "Model: %s (supported=%s)", robotModelName.c_str(),
+            isSupportedModel(robotModelName) ? "yes" : "no");
+        sKey = computeSKey(v.serialNumber);
+        if (sKey.length() > 0) {
+            LOG("NEATO", "SKey computed (%d chars) from serial %s", sKey.length(), v.serialNumber.c_str());
+        } else {
+            LOG("NEATO", "SKey computation failed for serial: %s", v.serialNumber.c_str());
+        }
+    });
+}
+
+String NeatoSerial::buildSetEvent(const char *event) const {
+    return String(CMD_SET_EVENT_PREFIX) + event + CMD_SET_EVENT_SKEY + sKey;
+}
+
+void NeatoSerial::tick() {
+    // Drive initSKey lifecycle: first attempt + retries on failure.
+    // Runs inside tick() (not setup()) so the UART state machine is already
+    // processing the queue — avoids the race where GetVersion was enqueued
+    // in setup() but tick() hadn't started yet.
+    if (sKeyPending && millis() >= sKeyRetryAt) {
+        sKeyRetryAt = ULONG_MAX; // Prevent re-entry while fetch is in flight
+        initSKey();
+    }
+
+    switch (state) {
+        case QUEUE_IDLE:
+            if (!queue.empty()) {
+                dequeueNext();
+            }
+            break;
+
+        case QUEUE_SENDING:
+            sendCurrentCommand();
+            break;
+
+        case QUEUE_WAITING_RESPONSE: {
+            // Read all available bytes
+            while (uart.available()) {
+                char c = static_cast<char>(uart.read());
+                if (c == NEATO_RESPONSE_TERMINATOR) {
+                    unsigned long elapsed = millis() - commandSentAt;
+                    LOG("NEATO", "RX: %u bytes in %lu ms", responseBuffer.length(), elapsed);
+
+                    // Validate: response must echo the sent command on the first line.
+                    // If it doesn't, the UART stream is desynced (we got a response
+                    // meant for a different command). Flush and fail this request so
+                    // the next command starts clean.
+                    if (!validateResponseEcho(responseBuffer)) {
+                        LOG("NEATO", "DESYNC: sent '%s' but response echoed a different command, flushing",
+                            currentCommand.c_str());
+                        flushUartRx();
+                        completeCommand(CMD_SERIAL_ERROR, responseBuffer);
+                        return;
+                    }
+
+                    // Detect "Unknown Cmd" — robot doesn't support this command
+                    if (responseBuffer.indexOf("Unknown Cmd") >= 0) {
+                        LOG("NEATO", "Unsupported: %s", currentCommand.c_str());
+                        completeCommand(CMD_UNSUPPORTED, responseBuffer);
+                        return;
+                    }
+
+                    completeCommand(CMD_SUCCESS, responseBuffer);
+                    return;
+                }
+                responseBuffer += c;
+            }
+            // Check timeout
+            if (millis() - commandSentAt >= NEATO_CMD_TIMEOUT_MS) {
+                LOG("NEATO", "Timeout: %s (%lu ms, partial: %u bytes)", currentCommand.c_str(),
+                    (unsigned long) NEATO_CMD_TIMEOUT_MS, responseBuffer.length());
+                // Log partial response on timeout (useful for debugging serial issues).
+                // Flush UART to prevent stale bytes from leaking into the next command.
+                flushUartRx();
+                completeCommand(CMD_TIMEOUT, responseBuffer);
+            }
+            break;
+        }
+
+        case QUEUE_INTER_DELAY:
+            if (millis() - delayStartedAt >= NEATO_INTER_CMD_DELAY_MS) {
+                state = QUEUE_IDLE;
+            }
+            break;
+    }
+}
+
+// -- Queue management --------------------------------------------------------
+
+bool NeatoSerial::enqueue(const String& command, std::function<void(bool, const String&)> callback,
+                          CommandPriority priority) {
+    if (static_cast<int>(queue.size()) >= NEATO_QUEUE_MAX_SIZE) {
+        LOG("NEATO", "Queue full, rejecting: %s", command.c_str());
+        if (loggerCallback)
+            loggerCallback(command, CMD_QUEUE_FULL, 0, "", static_cast<int>(queue.size()), 0, 0);
+        if (callback)
+            callback(false, "");
+        return false;
+    }
+    // Lower number = higher priority. Keep FIFO order within same priority.
+    auto it = queue.begin();
+    for (; it != queue.end(); ++it) {
+        if (it->priority > priority)
+            break;
+    }
+    queue.insert(it, {command, static_cast<uint8_t>(priority), callback});
+    return true;
+}
+
+std::function<void(bool, const String&)> NeatoSerial::wrapAction(std::function<void(bool)> callback) {
+    if (!callback)
+        return nullptr;
+    return [callback](bool ok, const String&) { callback(ok); };
+}
+
+void NeatoSerial::dequeueNext() {
+    if (queue.empty())
+        return;
+
+    // Capture queue depth before dequeue (for logging)
+    queueDepthAtStart = static_cast<int>(queue.size());
+
+    CommandEntry entry = queue.front();
+    queue.erase(queue.begin());
+
+    currentCommand = entry.command;
+    currentCallback = entry.callback;
+    responseBuffer = "";
+
+    state = QUEUE_SENDING;
+}
+
+void NeatoSerial::flushUartRx() {
+    int flushed = 0;
+    while (uart.available()) {
+        uart.read();
+        flushed++;
+    }
+    if (flushed > 0) {
+        LOG("NEATO", "Flushed %d stale bytes from UART RX", flushed);
+    }
+}
+
+void NeatoSerial::sendCurrentCommand() {
+    // Drain any stale bytes from a previous response that may have arrived late
+    flushUartRx();
+
+    LOG("NEATO", "TX: %s", currentCommand.c_str());
+    uart.print(currentCommand + "\n");
+    commandSentAt = millis();
+    state = QUEUE_WAITING_RESPONSE;
+}
+
+bool NeatoSerial::validateResponseEcho(const String& response) const {
+    // The Neato echoes the command on the first line of the response,
+    // e.g. "GetCharger\r\nLabel,Value\r\n...". Extract the first word of the
+    // sent command (before any space/flag) and check the response starts with it.
+    // Some commands echo only the name ("Clean" for "Clean House"), while others
+    // echo the full command with arguments ("TestMode On" for "TestMode On").
+    // Using startsWith handles both cases.
+    String expectedEcho = currentCommand;
+    int spacePos = expectedEcho.indexOf(' ');
+    if (spacePos > 0)
+        expectedEcho = expectedEcho.substring(0, spacePos);
+
+    // Find the first line in the response (up to \r or \n)
+    String firstLine = response;
+    int crPos = firstLine.indexOf('\r');
+    int lfPos = firstLine.indexOf('\n');
+    int lineEnd = -1;
+    if (crPos >= 0 && lfPos >= 0)
+        lineEnd = (crPos < lfPos) ? crPos : lfPos;
+    else if (crPos >= 0)
+        lineEnd = crPos;
+    else if (lfPos >= 0)
+        lineEnd = lfPos;
+    if (lineEnd >= 0)
+        firstLine = firstLine.substring(0, lineEnd);
+
+    // Check that the echo line starts with the expected command name (case-insensitive).
+    firstLine.trim();
+    expectedEcho.trim();
+    firstLine.toLowerCase();
+    expectedEcho.toLowerCase();
+    return firstLine.startsWith(expectedEcho);
+}
+
+void NeatoSerial::completeCommand(CommandStatus status, const String& response) {
+    unsigned long elapsed = millis() - commandSentAt;
+    String cmd = currentCommand;
+    auto cb = currentCallback;
+    int qDepth = queueDepthAtStart;
+    String resp = response; // Copy before clearing responseBuffer (response is a ref to it)
+    size_t respBytes = resp.length();
+
+    currentCommand = "";
+    currentCallback = nullptr;
+    responseBuffer = "";
+    queueDepthAtStart = 0;
+
+    // Start inter-command delay before next command
+    delayStartedAt = millis();
+    state = QUEUE_INTER_DELAY;
+
+    // Fire logger hook before user callback with enhanced metadata
+    if (loggerCallback)
+        loggerCallback(cmd, status, elapsed, resp, qDepth, respBytes, 0);
+
+    // User callback still gets simple bool for backward compatibility
+    bool success = (status == CMD_SUCCESS);
+    if (cb)
+        cb(success, resp);
+}
+
+// -- Cached sensor query methods (public API) --------------------------------
+// These delegate to AsyncCache, which handles TTL, dedup, and coalescing.
+
+void NeatoSerial::getVersion(std::function<void(bool, const VersionData&)> callback) {
+    versionCache.get(callback);
+}
+
+void NeatoSerial::getCharger(std::function<void(bool, const ChargerData&)> callback) {
+    chargerCache.get(callback);
+}
+
+void NeatoSerial::getBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
+    analogCache.get(callback);
+}
+
+void NeatoSerial::getBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
+    warrantyCache.get(callback);
+}
+
+void NeatoSerial::getUserSettings(std::function<void(bool, const UserSettingsData&)> callback) {
+    userSettingsCache.get(callback);
+}
+
+void NeatoSerial::getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback) {
+    getDigitalSensors(callback, PRIORITY_NORMAL);
+}
+
+void NeatoSerial::getDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
+                                    CommandPriority priority) {
+    // Normal priority goes through cache; elevated priority bypasses it
+    // to guarantee commands are enqueued at the requested priority.
+    if (priority == PRIORITY_NORMAL) {
+        digitalCache.get(callback);
+    } else {
+        fetchDigitalSensors(callback, priority);
+    }
+}
+
+void NeatoSerial::getMotors(std::function<void(bool, const MotorData&)> callback) {
+    getMotors(callback, PRIORITY_NORMAL);
+}
+
+void NeatoSerial::getMotors(std::function<void(bool, const MotorData&)> callback, CommandPriority priority) {
+    // Normal priority goes through cache; elevated priority bypasses it
+    // to guarantee commands are enqueued at the requested priority.
+    if (priority == PRIORITY_NORMAL) {
+        motorCache.get(callback);
+    } else {
+        fetchMotors(callback, priority);
+    }
+}
+
+void NeatoSerial::getState(std::function<void(bool, const RobotState&)> callback) {
+    // During manual clean, the robot reports UIMGR_STATE_TESTMODE.
+    // Override to UIMGR_STATE_MANUALCLEANING so callers (frontend, dashboard)
+    // see the correct pseudo-state without needing to know about TestMode internals.
+    if (manualCleanActive) {
+        stateCache.get([callback](bool ok, const RobotState& data) {
+            if (!ok || !callback) {
+                if (callback)
+                    callback(ok, data);
+                return;
+            }
+            RobotState patched = data;
+            patched.uiState = "UIMGR_STATE_MANUALCLEANING";
+            callback(true, patched);
+        });
+        return;
+    }
+    stateCache.get(callback);
+}
+
+void NeatoSerial::getErr(std::function<void(bool, const ErrorData&)> callback) {
+    errCache.get(callback);
+}
+
+void NeatoSerial::getErrClear(std::function<void(bool, const ErrorData&)> callback) {
+    // getErrClear is never cached — it clears the error and always needs a fresh fetch
+    fetchErrClear(callback);
+}
+
+void NeatoSerial::getLdsScan(std::function<void(bool, const LdsScanData&)> callback) {
+    ldsCache.get(callback);
+}
+
+void NeatoSerial::getRobotPos(bool smooth, std::function<void(bool, const RobotPosData&)> callback) {
+    (smooth ? robotPosSmoothCache : robotPosRawCache).get(callback);
+}
+
+// -- Raw fetch methods (enqueue serial command, parse response) ---------------
+
+void NeatoSerial::fetchVersion(std::function<void(bool, const VersionData&)> callback) {
+    enqueue(CMD_GET_VERSION, [callback](bool ok, const String& raw) {
+        VersionData data;
+        if (ok)
+            ok = parseVersionData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchCharger(std::function<void(bool, const ChargerData&)> callback) {
+    enqueue(CMD_GET_CHARGER, [callback](bool ok, const String& raw) {
+        ChargerData data;
+        if (ok)
+            ok = parseChargerData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchBatteryAnalog(std::function<void(bool, const BatteryAnalogData&)> callback) {
+    enqueue(CMD_GET_ANALOG_SENSORS, [callback](bool ok, const String& raw) {
+        BatteryAnalogData data;
+        if (ok)
+            ok = parseBatteryAnalogData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchBatteryWarranty(std::function<void(bool, const BatteryWarrantyData&)> callback) {
+    enqueue(CMD_GET_WARRANTY, [callback](bool ok, const String& raw) {
+        BatteryWarrantyData data;
+        if (ok)
+            ok = parseBatteryWarrantyData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchDigitalSensors(std::function<void(bool, const DigitalSensorData&)> callback,
+                                      CommandPriority priority) {
+    enqueue(
+            CMD_GET_DIGITAL_SENSORS,
+            [callback](bool ok, const String& raw) {
+                DigitalSensorData data;
+                if (ok)
+                    ok = parseDigitalSensorData(raw, data);
+                if (callback)
+                    callback(ok, data);
+            },
+            priority);
+}
+
+void NeatoSerial::fetchMotors(std::function<void(bool, const MotorData&)> callback, CommandPriority priority) {
+    enqueue(
+            CMD_GET_MOTORS,
+            [callback](bool ok, const String& raw) {
+                MotorData data;
+                if (ok)
+                    ok = parseMotorData(raw, data);
+                if (callback)
+                    callback(ok, data);
+            },
+            priority);
+}
+
+void NeatoSerial::fetchState(std::function<void(bool, const RobotState&)> callback) {
+    enqueue(CMD_GET_STATE, [callback](bool ok, const String& raw) {
+        RobotState data;
+        if (ok)
+            ok = parseRobotState(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchErr(std::function<void(bool, const ErrorData&)> callback) {
+    enqueue(CMD_GET_ERR, [callback](bool ok, const String& raw) {
+        ErrorData data;
+        if (ok)
+            ok = parseErrorData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchErrClear(std::function<void(bool, const ErrorData&)> callback) {
+    enqueue(CMD_GET_ERR_CLEAR, [callback](bool ok, const String& raw) {
+        ErrorData data;
+        if (ok)
+            ok = parseErrorData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchLdsScan(std::function<void(bool, const LdsScanData&)> callback) {
+    enqueue(CMD_GET_LDS_SCAN, [callback](bool ok, const String& raw) {
+        LdsScanData data;
+        if (ok)
+            ok = parseLdsScanData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchRobotPos(const char *cmd, std::function<void(bool, const RobotPosData&)> callback) {
+    enqueue(cmd, [callback](bool ok, const String& raw) {
+        RobotPosData data;
+        if (ok)
+            ok = parseRobotPosData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+void NeatoSerial::fetchUserSettings(std::function<void(bool, const UserSettingsData&)> callback) {
+    enqueue(CMD_GET_USER_SETTINGS, [callback](bool ok, const String& raw) {
+        UserSettingsData data;
+        if (ok)
+            ok = parseUserSettingsData(raw, data);
+        if (callback)
+            callback(ok, data);
+    });
+}
+
+// -- Cache invalidation ------------------------------------------------------
+
+void NeatoSerial::invalidateState() {
+    stateCache.invalidate();
+    errCache.invalidate();
+}
+
+void NeatoSerial::invalidateAll() {
+    versionCache.invalidate();
+    chargerCache.invalidate();
+    analogCache.invalidate();
+    warrantyCache.invalidate();
+    digitalCache.invalidate();
+    motorCache.invalidate();
+    stateCache.invalidate();
+    errCache.invalidate();
+    ldsCache.invalidate();
+    robotPosRawCache.invalidate();
+    robotPosSmoothCache.invalidate();
+    userSettingsCache.invalidate();
+}
+
+// -- Action command convenience methods --------------------------------------
+
+bool NeatoSerial::clean(const String& action, std::function<void(bool)> callback) {
+    // All cleaning control uses SetEvent — the authenticated event API that D3-D7
+    // robots use for their cloud/app protocol. This correctly transitions the UI
+    // state machine and preserves map/localization during pause/resume.
+    //
+    // SKey must be computed at boot via initSKey(). If missing, commands will fail
+    // gracefully (callback with false).
+
+    if (!hasSKey()) {
+        LOG("NEATO", "clean(%s) failed — SKey not available", action.c_str());
+        if (callback)
+            callback(false);
+        return false;
+    }
+
+    if (action == "dock") {
+        invalidateState();
+        return enqueue(buildSetEvent(EVT_SEND_TO_BASE), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    if (action == "pause") {
+        invalidateState();
+        return enqueue(buildSetEvent(EVT_PAUSE), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    if (action == "stop") {
+        invalidateState();
+        return enqueue(buildSetEvent(EVT_STOP), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    // Type-aware resume: "house" only resumes a paused house clean, "spot"
+    // only resumes a paused spot clean. Prevents HA "start" from resuming
+    // a previously paused spot clean when the user expects a new house clean.
+    if (action == "house") {
+        bool isPausedHouse =
+                stateCache.hasCached() && stateCache.getCached().uiState.indexOf("HOUSECLEANINGPAUSED") >= 0;
+        if (isPausedHouse) {
+            invalidateState();
+            return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
+        }
+        invalidateState();
+        if (cleanStartCallback)
+            cleanStartCallback();
+        // Send navigation mode first (fire-and-forget); house clean proceeds regardless.
+        if (navModeGetter) {
+            String mode = navModeGetter();
+            if (mode.length() > 0 && mode != "Normal") {
+                String navCmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
+                enqueue(navCmd, nullptr, PRIORITY_HIGH);
+            }
+        }
+        return enqueue(buildSetEvent(EVT_START_HOUSE), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    if (action == "spot") {
+        bool isPausedSpot = stateCache.hasCached() && stateCache.getCached().uiState.indexOf("SPOTCLEANINGPAUSED") >= 0;
+        if (isPausedSpot) {
+            invalidateState();
+            return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
+        }
+        invalidateState();
+        if (cleanStartCallback)
+            cleanStartCallback();
+        return enqueue(buildSetEvent(EVT_START_SPOT), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    // Generic action — resume whatever is paused, or start house clean
+    bool isPaused = stateCache.hasCached() && stateCache.getCached().uiState.indexOf("CLEANINGPAUSED") >= 0;
+    if (isPaused) {
+        invalidateState();
+        return enqueue(buildSetEvent(EVT_RESUME), wrapAction(callback), PRIORITY_HIGH);
+    }
+
+    // New clean from idle — fall through to house clean
+    invalidateState();
+    if (cleanStartCallback)
+        cleanStartCallback();
+    // Send navigation mode first (fire-and-forget); house clean proceeds regardless.
+    if (navModeGetter) {
+        String mode = navModeGetter();
+        if (mode.length() > 0 && mode != "Normal") {
+            String navCmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
+            enqueue(navCmd, nullptr, PRIORITY_HIGH);
+        }
+    }
+    return enqueue(buildSetEvent(EVT_START_HOUSE), wrapAction(callback), PRIORITY_HIGH);
+}
+
+bool NeatoSerial::testMode(bool enable, std::function<void(bool)> callback) {
+    const char *cmd = enable ? CMD_TEST_MODE_ON : CMD_TEST_MODE_OFF;
+    invalidateState();
+    // HIGH priority: TestMode is a prerequisite for motor commands — must execute
+    // before any CRITICAL/MEDIUM motor commands that may already be queued.
+    return enqueue(cmd, wrapAction(callback), PRIORITY_HIGH);
+}
+
+bool NeatoSerial::playSound(SoundId soundId, std::function<void(bool)> callback) {
+    String cmd = String(CMD_PLAY_SOUND) + " SoundID " + String(static_cast<int>(soundId));
+    return enqueue(cmd, wrapAction(callback));
+}
+
+bool NeatoSerial::setLdsRotation(bool on, std::function<void(bool)> callback) {
+    const char *cmd = on ? CMD_SET_LDS_ROTATION_ON : CMD_SET_LDS_ROTATION_OFF;
+    // HIGH priority: LDS rotation is a setup/teardown command that must execute
+    // before motor commands during manual clean enable/disable sequences.
+    return enqueue(cmd, wrapAction(callback), PRIORITY_HIGH);
+}
+
+bool NeatoSerial::setMotorWheels(int leftMM, int rightMM, int speedMMs, std::function<void(bool)> callback) {
+    // SetMotor 0 0 0 bug: zero values are ignored, robot coasts for ~1s.
+    // Workaround: disable wheels for immediate stop, then re-enable for next command.
+    if (leftMM == 0 && rightMM == 0) {
+        return enqueue(
+                String(CMD_SET_MOTOR) + " LWheelDisable RWheelDisable",
+                [this, callback](bool ok, const String&) {
+                    // Re-enable wheels so subsequent move commands work
+                    enqueue(String(CMD_SET_MOTOR) + " LWheelEnable RWheelEnable", wrapAction(callback),
+                            PRIORITY_CRITICAL);
+                },
+                PRIORITY_CRITICAL);
+    }
+    // Robot rejects distances outside ±10000mm — clamp to protocol limits
+    leftMM = constrain(leftMM, -10000, 10000);
+    rightMM = constrain(rightMM, -10000, 10000);
+    speedMMs = constrain(speedMMs, 0, 300);
+    String cmd = String(CMD_SET_MOTOR) + " LWheelDist " + String(leftMM) + " RWheelDist " + String(rightMM) +
+                 " Speed " + String(speedMMs);
+    return enqueue(cmd, wrapAction(callback), PRIORITY_CRITICAL);
+}
+
+bool NeatoSerial::setMotorBrush(int rpm, std::function<void(bool)> callback) {
+    if (rpm <= 0) {
+        return enqueue(String(CMD_SET_MOTOR) + " BrushDisable", wrapAction(callback), PRIORITY_MEDIUM);
+    }
+    // BrushEnable energizes the motor driver, then Brush + RPM starts spinning.
+    // Brush flag is mutually exclusive with wheel/vacuum commands per call.
+    return enqueue(
+            String(CMD_SET_MOTOR) + " BrushEnable",
+            [this, rpm, callback](bool ok, const String&) {
+                if (!ok) {
+                    if (callback)
+                        callback(false);
+                    return;
+                }
+                enqueue(String(CMD_SET_MOTOR) + " Brush RPM " + String(rpm), wrapAction(callback), PRIORITY_MEDIUM);
+            },
+            PRIORITY_MEDIUM);
+}
+
+bool NeatoSerial::setMotorVacuum(bool on, int speedPercent, std::function<void(bool)> callback) {
+    // VacuumSpeed must be combined with VacuumOn in the same call.
+    String cmd = String(CMD_SET_MOTOR);
+    cmd += on ? " VacuumOn VacuumSpeed " + String(speedPercent) : " VacuumOff";
+    return enqueue(cmd, wrapAction(callback), PRIORITY_MEDIUM);
+}
+
+bool NeatoSerial::setMotorSideBrush(bool on, int powerMw, std::function<void(bool)> callback) {
+    // Side brush (Botvac D3-D7 only) uses open-loop power control in milliwatts.
+    // Two-layer control: SideBrushEnable energizes motor driver, SideBrushOn starts spinning.
+    // Completely independent from the main brush.
+    if (!on) {
+        return enqueue(
+                String(CMD_SET_MOTOR) + " SideBrushOff",
+                [this, callback](bool ok, const String&) {
+                    // Best-effort disable after stopping
+                    enqueue(String(CMD_SET_MOTOR) + " SideBrushDisable", wrapAction(callback), PRIORITY_MEDIUM);
+                },
+                PRIORITY_MEDIUM);
+    }
+    return enqueue(
+            String(CMD_SET_MOTOR) + " SideBrushEnable",
+            [this, powerMw, callback](bool ok, const String&) {
+                if (!ok) {
+                    if (callback)
+                        callback(false);
+                    return;
+                }
+                enqueue(String(CMD_SET_MOTOR) + " SideBrushOn SideBrushPower " + String(powerMw), wrapAction(callback),
+                        PRIORITY_MEDIUM);
+            },
+            PRIORITY_MEDIUM);
+}
+
+// -- User settings -----------------------------------------------------------
+
+bool NeatoSerial::setUserSetting(const String& key, const String& value, std::function<void(bool)> callback) {
+    userSettingsCache.invalidate();
+    String cmd = String(CMD_SET_USER_SETTINGS) + " " + key + " " + value;
+    return enqueue(cmd, wrapAction(callback));
+}
+
+bool NeatoSerial::setNavigationMode(const String& mode, std::function<void(bool)> callback) {
+    String cmd = String(CMD_SET_NAVIGATION_MODE) + " " + mode;
+    return enqueue(cmd, wrapAction(callback));
+}
+
+// -- Power control -----------------------------------------------------------
+
+bool NeatoSerial::powerControl(const String& action, std::function<void(bool)> callback) {
+    const char *cmd;
+    if (action == "restart") {
+        cmd = CMD_SET_SYSTEM_MODE_POWER_CYCLE;
+    } else if (action == "shutdown") {
+        cmd = CMD_SET_SYSTEM_MODE_SHUTDOWN;
+    } else {
+        LOG("NEATO", "powerControl: unknown action '%s'", action.c_str());
+        if (callback)
+            callback(false);
+        return false;
+    }
+
+    // SetSystemMode requires TestMode On first (protocol specifies 100ms delay,
+    // which the inter-command delay covers). Chain: TestMode On -> SetSystemMode.
+    invalidateState();
+    const char *sysCmd = cmd; // capture for lambda
+    return testMode(true, [this, sysCmd, callback](bool ok) {
+        if (!ok) {
+            LOG("NEATO", "powerControl: TestMode On failed");
+            if (callback)
+                callback(false);
+            return;
+        }
+        enqueue(sysCmd, wrapAction(callback), PRIORITY_HIGH);
+    });
+}
+
+// -- Clear errors ------------------------------------------------------------
+
+bool NeatoSerial::clearErrors(std::function<void(bool)> callback) {
+    invalidateState();
+    return enqueue(CMD_SET_UI_ERROR_CLEAR_ALL, wrapAction(callback));
+}
+
+bool NeatoSerial::newBattery(std::function<void(bool)> callback) {
+    invalidateState();
+    return testMode(true, [this, callback](bool ok) {
+        if (!ok) {
+            if (callback)
+                callback(false);
+            return;
+        }
+
+        enqueue(
+                CMD_NEW_BATTERY,
+                [this, callback](bool okCmd, const String&) {
+                    if (!okCmd) {
+                        // Best-effort return robot to normal mode even if NewBattery failed
+                        testMode(false, nullptr);
+                        if (callback)
+                            callback(false);
+                        return;
+                    }
+                    testMode(false, callback);
+                },
+                PRIORITY_HIGH);
+    });
+}
+
+bool NeatoSerial::sendRaw(const String& cmd, std::function<void(bool, const String&)> callback) {
+    if (cmd.isEmpty())
+        return false;
+    return enqueue(cmd, callback);
+}
diff --git a/firmware/src/notification_manager.cpp b/firmware/src/notification_manager.cpp
index f30c180..0931826 100644
--- a/firmware/src/notification_manager.cpp
+++ b/firmware/src/notification_manager.cpp
@@ -1,236 +1,236 @@
-#include "notification_manager.h"
-#include "cleaning_history.h"
-#include "neato_serial.h"
-#include "settings_manager.h"
-#include "data_logger.h"
-#include <WiFi.h>
-#include <WiFiClient.h>
-#include <WiFiClientSecure.h>
-
-#define NTFY_DEFAULT_HOST "ntfy.sh"
-#define NTFY_CONNECT_TIMEOUT_MS 3000
-
-// Max wall-clock to wait for CleaningHistory::stopCollection's async charger
-// fetch to finalize stats before sending the "done" notification anyway.
-#define NTFY_DONE_PENDING_TIMEOUT_MS 5000
-
-NotificationManager::NotificationManager(NeatoSerial& neato, SettingsManager& settings, DataLogger& logger,
-                                         CleaningHistory& history) :
-    LoopTask(NOTIF_INTERVAL_IDLE_MS), neato(neato), settings(settings), dataLogger(logger), history(history) {
-    TaskRegistry::add(this);
-}
-
-void NotificationManager::begin() {
-    LOG("NOTIF", "Notification manager initialized");
-}
-
-void NotificationManager::tick() {
-    // Drain a pending "done" notification independently of the fetch path —
-    // it's waiting on CleaningHistory's async stop, not our own state fetch.
-    if (donePending)
-        flushPendingDone();
-
-    if (fetchPending)
-        return;
-
-    // Skip if notifications disabled, no topic configured, or WiFi not connected
-    const Settings& s = settings.get();
-    if (!s.ntfyEnabled || s.ntfyTopic.isEmpty() || WiFi.status() != WL_CONNECTED)
-        return;
-
-    checkTransitions();
-}
-
-void NotificationManager::checkTransitions() {
-    fetchPending = true;
-
-    // Fetch state first, then error — both return from cache (zero serial cost within TTL)
-    neato.getState([this](bool stateOk, const RobotState& state) {
-        neato.getErr([this, stateOk, state](bool errOk, const ErrorData& err) {
-            fetchPending = false;
-
-            const Settings& cfg = settings.get();
-            const String& topic = cfg.ntfyTopic;
-            const String& hostname = cfg.hostname;
-
-            if (stateOk) {
-                const String& ui = state.uiState;
-                const String& rs = state.robotState;
-
-                // Detect transitions
-                if (!prevUiState.isEmpty()) {
-                    bool wasCleaning = prevUiState.indexOf("CLEANINGRUNNING") >= 0;
-                    bool wasDocking = prevUiState.indexOf("DOCKING") >= 0;
-                    bool isCleaningRunning = ui.indexOf("CLEANINGRUNNING") >= 0;
-                    bool isDocking = ui.indexOf("DOCKING") >= 0;
-                    bool isSuspended = ui.indexOf("CLEANINGSUSPENDED") >= 0;
-                    bool isIdle = ui == "UIMGR_STATE_IDLE" || ui == "UIMGR_STATE_STANDBY";
-
-                    // Track cleaning context when entering docking
-                    if (wasCleaning && isDocking) {
-                        wasCleaningBeforeDock = true;
-                    }
-
-                    // Mid-clean recharge: robot state ST_M1_Charging_Cleaning means
-                    // the robot docked to recharge and will resume cleaning afterwards.
-                    // The UI state transitions DOCKING -> CLEANINGSUSPENDED once on the dock.
-                    bool isRecharging = rs.indexOf("Charging_Cleaning") >= 0;
-
-                    // Fresh start: idle -> CLEANINGRUNNING (excludes resume from
-                    // pause/suspended and resume after mid-clean recharge dock).
-                    bool prevInCleaningContext = prevUiState.indexOf("CLEANING") >= 0 ||
-                                                 prevUiState.indexOf("DOCKING") >= 0;
-                    if (isCleaningRunning && !prevInCleaningContext && cfg.ntfyOnStart) {
-                        sendNotification(topic, "arrow_forward", hostname + ": Cleaning started");
-                    }
-
-                    if (isDocking && !wasDocking && isRecharging && cfg.ntfyOnDocking) {
-                        // Recharge dock — robot will resume cleaning after charging
-                        sendNotification(topic, "electric_plug", hostname + ": Returning to base to recharge");
-                    }
-
-                    // Cleaning completed: cleaning/docking -> idle, but NOT if it's a recharge.
-                    // Also handle suspended -> idle (user stops clean while recharging).
-                    bool dockingDone = wasDocking && wasCleaningBeforeDock && !isRecharging;
-                    bool suspendedDone = (prevUiState.indexOf("CLEANINGSUSPENDED") >= 0) && wasCleaningBeforeDock;
-                    if ((wasCleaning || dockingDone || suspendedDone) && isIdle && cfg.ntfyOnDone && !donePending) {
-                        // Defer the send: CleaningHistory::stopCollection finalizes stats
-                        // inside an async getCharger callback, so reading getLastCleanStats()
-                        // here can race and pull stale data from the prior session. Capture
-                        // the current sessionId; flushPendingDone() fires once it increments
-                        // (or after NTFY_DONE_PENDING_TIMEOUT_MS).
-                        donePending = true;
-                        doneTriggerSessionId = history.getLastCleanStats().sessionId;
-                        donePendingSinceMs = millis();
-                        doneHostname = hostname;
-                        doneTopic = topic;
-                    }
-
-                    // Clear tracking flag when leaving docking — but preserve it
-                    // through DOCKING -> CLEANINGSUSPENDED (mid-clean recharge)
-                    if (wasDocking && !isDocking && !isSuspended) {
-                        wasCleaningBeforeDock = false;
-                    }
-                }
-
-                // Update adaptive interval based on current state
-                bool active = isActiveState(ui);
-                setInterval(active ? NOTIF_INTERVAL_ACTIVE_MS : NOTIF_INTERVAL_IDLE_MS);
-                prevUiState = ui;
-                prevRobotState = rs;
-            }
-
-            if (errOk) {
-                // New error or alert detected: was no error -> now has error, or code changed
-                if (err.hasError && (!prevHasError || err.errorCode != prevErrorCode)) {
-                    bool isAlert = (err.kind == "warning"); // UI_ALERT_* (201-242)
-                    bool allowed = isAlert ? cfg.ntfyOnAlert : cfg.ntfyOnError;
-                    if (allowed) {
-                        String tag = isAlert ? "information_source" : "warning";
-                        sendNotification(topic, tag, hostname + ": " + err.displayMessage);
-                    }
-                }
-                prevHasError = err.hasError;
-                prevErrorCode = err.errorCode;
-            }
-        });
-    });
-}
-
-bool NotificationManager::isActiveState(const String& uiState) {
-    return uiState.indexOf("CLEANINGRUNNING") >= 0 || uiState.indexOf("CLEANINGPAUSED") >= 0 ||
-           uiState.indexOf("CLEANINGSUSPENDED") >= 0 || uiState.indexOf("DOCKING") >= 0;
-}
-
-void NotificationManager::flushPendingDone() {
-    const LastCleanStats& stats = history.getLastCleanStats();
-    bool finalized = stats.sessionId != doneTriggerSessionId;
-    bool timedOut = (millis() - donePendingSinceMs) >= NTFY_DONE_PENDING_TIMEOUT_MS;
-    if (!finalized && !timedOut)
-        return;
-
-    // If stopCollection finalized after we triggered, sessionId moved and stats
-    // are fresh; if we timed out, fire bare without stats rather than stale.
-    sendDoneNotification(doneTopic, doneHostname, finalized && stats.valid);
-    donePending = false;
-}
-
-void NotificationManager::sendDoneNotification(const String& topic, const String& hostname, bool withStats) {
-    String msg = hostname + ": Cleaning done";
-    if (withStats) {
-        const LastCleanStats& stats = history.getLastCleanStats();
-        long mins = stats.durationSec / 60;
-        msg += "\n" + String(mins) + "min";
-        msg += " | " + String(stats.areaCoveredM2, 1) + "m2";
-        msg += " | " + String(stats.distanceM, 0) + "m";
-        if (stats.batteryStart >= 0 && stats.batteryEnd >= 0) {
-            msg += " | " + String(stats.batteryStart) + "% -> " + String(stats.batteryEnd) + "%";
-        }
-    }
-    sendNotification(topic, "white_check_mark", msg);
-}
-
-void NotificationManager::sendNotification(const String& topic, const String& tags, const String& message) {
-    LOG("NOTIF", "Sending: [%s] %s", tags.c_str(), message.c_str());
-
-    const Settings& cfg = settings.get();
-    String host = cfg.ntfyServer.isEmpty() ? NTFY_DEFAULT_HOST : cfg.ntfyServer;
-    bool useHttps = !cfg.ntfyServer.isEmpty(); // Custom servers use HTTPS; ntfy.sh uses plain HTTP
-
-    WiFiClientSecure secureClient;
-    WiFiClient plainClient;
-    Client* client;
-
-    if (useHttps) {
-        secureClient.setInsecure(); // Skip cert validation — self-hosted server
-        secureClient.setTimeout(NTFY_CONNECT_TIMEOUT_MS);
-        if (!secureClient.connect(host.c_str(), 443)) {
-            LOG("NOTIF", "TLS connect to %s:443 failed", host.c_str());
-            dataLogger.logNotification("notif_send_fail", message, false);
-            return;
-        }
-        client = &secureClient;
-    } else {
-        plainClient.setTimeout(NTFY_CONNECT_TIMEOUT_MS);
-        if (!plainClient.connect(host.c_str(), 80)) {
-            LOG("NOTIF", "Connect to %s:80 failed", host.c_str());
-            dataLogger.logNotification("notif_send_fail", message, false);
-            return;
-        }
-        client = &plainClient;
-    }
-
-    // Build HTTP POST request
-    client->print("POST /" + topic + " HTTP/1.1\r\n");
-    client->print("Host: " + host + "\r\n");
-    client->print("Content-Type: text/plain\r\n");
-    client->print("Tags: " + tags + "\r\n");
-    client->print("Content-Length: " + String(message.length()) + "\r\n");
-    if (!cfg.ntfyToken.isEmpty()) {
-        client->print("Authorization: Bearer " + cfg.ntfyToken + "\r\n");
-    }
-    client->print("Connection: close\r\n");
-    client->print("\r\n");
-    client->print(message);
-
-    // Read just the HTTP status line (e.g. "HTTP/1.1 200 OK\r\n")
-    bool ok = false;
-    String statusLine = client->readStringUntil('\n');
-    if (statusLine.length() > 0) {
-        int spaceIdx = statusLine.indexOf(' ');
-        if (spaceIdx > 0) {
-            int code = statusLine.substring(spaceIdx + 1, spaceIdx + 4).toInt();
-            ok = (code >= 200 && code < 300);
-            LOG("NOTIF", "Response: %d %s", code, ok ? "OK" : "FAIL");
-        }
-    }
-
-    client->stop();
-
-    dataLogger.logNotification("notif_sent", message, ok);
-}
-
-void NotificationManager::sendTestNotification(const String& topic) {
-    const String& hostname = settings.get().hostname;
-    sendNotification(topic, "bell", hostname + ": Test notification");
-}
+#include "notification_manager.h"
+#include "cleaning_history.h"
+#include "neato_serial.h"
+#include "settings_manager.h"
+#include "data_logger.h"
+#include <WiFi.h>
+#include <WiFiClient.h>
+#include <WiFiClientSecure.h>
+
+#define NTFY_DEFAULT_HOST "ntfy.sh"
+#define NTFY_CONNECT_TIMEOUT_MS 3000
+
+// Max wall-clock to wait for CleaningHistory::stopCollection's async charger
+// fetch to finalize stats before sending the "done" notification anyway.
+#define NTFY_DONE_PENDING_TIMEOUT_MS 5000
+
+NotificationManager::NotificationManager(NeatoSerial& neato, SettingsManager& settings, DataLogger& logger,
+                                         CleaningHistory& history) :
+    LoopTask(NOTIF_INTERVAL_IDLE_MS), neato(neato), settings(settings), dataLogger(logger), history(history) {
+    TaskRegistry::add(this);
+}
+
+void NotificationManager::begin() {
+    LOG("NOTIF", "Notification manager initialized");
+}
+
+void NotificationManager::tick() {
+    // Drain a pending "done" notification independently of the fetch path —
+    // it's waiting on CleaningHistory's async stop, not our own state fetch.
+    if (donePending)
+        flushPendingDone();
+
+    if (fetchPending)
+        return;
+
+    // Skip if notifications disabled, no topic configured, or WiFi not connected
+    const Settings& s = settings.get();
+    if (!s.ntfyEnabled || s.ntfyTopic.isEmpty() || WiFi.status() != WL_CONNECTED)
+        return;
+
+    checkTransitions();
+}
+
+void NotificationManager::checkTransitions() {
+    fetchPending = true;
+
+    // Fetch state first, then error — both return from cache (zero serial cost within TTL)
+    neato.getState([this](bool stateOk, const RobotState& state) {
+        neato.getErr([this, stateOk, state](bool errOk, const ErrorData& err) {
+            fetchPending = false;
+
+            const Settings& cfg = settings.get();
+            const String& topic = cfg.ntfyTopic;
+            const String& hostname = cfg.hostname;
+
+            if (stateOk) {
+                const String& ui = state.uiState;
+                const String& rs = state.robotState;
+
+                // Detect transitions
+                if (!prevUiState.isEmpty()) {
+                    bool wasCleaning = prevUiState.indexOf("CLEANINGRUNNING") >= 0;
+                    bool wasDocking = prevUiState.indexOf("DOCKING") >= 0;
+                    bool isCleaningRunning = ui.indexOf("CLEANINGRUNNING") >= 0;
+                    bool isDocking = ui.indexOf("DOCKING") >= 0;
+                    bool isSuspended = ui.indexOf("CLEANINGSUSPENDED") >= 0;
+                    bool isIdle = ui == "UIMGR_STATE_IDLE" || ui == "UIMGR_STATE_STANDBY";
+
+                    // Track cleaning context when entering docking
+                    if (wasCleaning && isDocking) {
+                        wasCleaningBeforeDock = true;
+                    }
+
+                    // Mid-clean recharge: robot state ST_M1_Charging_Cleaning means
+                    // the robot docked to recharge and will resume cleaning afterwards.
+                    // The UI state transitions DOCKING -> CLEANINGSUSPENDED once on the dock.
+                    bool isRecharging = rs.indexOf("Charging_Cleaning") >= 0;
+
+                    // Fresh start: idle -> CLEANINGRUNNING (excludes resume from
+                    // pause/suspended and resume after mid-clean recharge dock).
+                    bool prevInCleaningContext =
+                            prevUiState.indexOf("CLEANING") >= 0 || prevUiState.indexOf("DOCKING") >= 0;
+                    if (isCleaningRunning && !prevInCleaningContext && cfg.ntfyOnStart) {
+                        sendNotification(topic, "arrow_forward", hostname + ": Cleaning started");
+                    }
+
+                    if (isDocking && !wasDocking && isRecharging && cfg.ntfyOnDocking) {
+                        // Recharge dock — robot will resume cleaning after charging
+                        sendNotification(topic, "electric_plug", hostname + ": Returning to base to recharge");
+                    }
+
+                    // Cleaning completed: cleaning/docking -> idle, but NOT if it's a recharge.
+                    // Also handle suspended -> idle (user stops clean while recharging).
+                    bool dockingDone = wasDocking && wasCleaningBeforeDock && !isRecharging;
+                    bool suspendedDone = (prevUiState.indexOf("CLEANINGSUSPENDED") >= 0) && wasCleaningBeforeDock;
+                    if ((wasCleaning || dockingDone || suspendedDone) && isIdle && cfg.ntfyOnDone && !donePending) {
+                        // Defer the send: CleaningHistory::stopCollection finalizes stats
+                        // inside an async getCharger callback, so reading getLastCleanStats()
+                        // here can race and pull stale data from the prior session. Capture
+                        // the current sessionId; flushPendingDone() fires once it increments
+                        // (or after NTFY_DONE_PENDING_TIMEOUT_MS).
+                        donePending = true;
+                        doneTriggerSessionId = history.getLastCleanStats().sessionId;
+                        donePendingSinceMs = millis();
+                        doneHostname = hostname;
+                        doneTopic = topic;
+                    }
+
+                    // Clear tracking flag when leaving docking — but preserve it
+                    // through DOCKING -> CLEANINGSUSPENDED (mid-clean recharge)
+                    if (wasDocking && !isDocking && !isSuspended) {
+                        wasCleaningBeforeDock = false;
+                    }
+                }
+
+                // Update adaptive interval based on current state
+                bool active = isActiveState(ui);
+                setInterval(active ? NOTIF_INTERVAL_ACTIVE_MS : NOTIF_INTERVAL_IDLE_MS);
+                prevUiState = ui;
+                prevRobotState = rs;
+            }
+
+            if (errOk) {
+                // New error or alert detected: was no error -> now has error, or code changed
+                if (err.hasError && (!prevHasError || err.errorCode != prevErrorCode)) {
+                    bool isAlert = (err.kind == "warning"); // UI_ALERT_* (201-242)
+                    bool allowed = isAlert ? cfg.ntfyOnAlert : cfg.ntfyOnError;
+                    if (allowed) {
+                        String tag = isAlert ? "information_source" : "warning";
+                        sendNotification(topic, tag, hostname + ": " + err.displayMessage);
+                    }
+                }
+                prevHasError = err.hasError;
+                prevErrorCode = err.errorCode;
+            }
+        });
+    });
+}
+
+bool NotificationManager::isActiveState(const String& uiState) {
+    return uiState.indexOf("CLEANINGRUNNING") >= 0 || uiState.indexOf("CLEANINGPAUSED") >= 0 ||
+           uiState.indexOf("CLEANINGSUSPENDED") >= 0 || uiState.indexOf("DOCKING") >= 0;
+}
+
+void NotificationManager::flushPendingDone() {
+    const LastCleanStats& stats = history.getLastCleanStats();
+    bool finalized = stats.sessionId != doneTriggerSessionId;
+    bool timedOut = (millis() - donePendingSinceMs) >= NTFY_DONE_PENDING_TIMEOUT_MS;
+    if (!finalized && !timedOut)
+        return;
+
+    // If stopCollection finalized after we triggered, sessionId moved and stats
+    // are fresh; if we timed out, fire bare without stats rather than stale.
+    sendDoneNotification(doneTopic, doneHostname, finalized && stats.valid);
+    donePending = false;
+}
+
+void NotificationManager::sendDoneNotification(const String& topic, const String& hostname, bool withStats) {
+    String msg = hostname + ": Cleaning done";
+    if (withStats) {
+        const LastCleanStats& stats = history.getLastCleanStats();
+        long mins = stats.durationSec / 60;
+        msg += "\n" + String(mins) + "min";
+        msg += " | " + String(stats.areaCoveredM2, 1) + "m2";
+        msg += " | " + String(stats.distanceM, 0) + "m";
+        if (stats.batteryStart >= 0 && stats.batteryEnd >= 0) {
+            msg += " | " + String(stats.batteryStart) + "% -> " + String(stats.batteryEnd) + "%";
+        }
+    }
+    sendNotification(topic, "white_check_mark", msg);
+}
+
+void NotificationManager::sendNotification(const String& topic, const String& tags, const String& message) {
+    LOG("NOTIF", "Sending: [%s] %s", tags.c_str(), message.c_str());
+
+    const Settings& cfg = settings.get();
+    String host = cfg.ntfyServer.isEmpty() ? NTFY_DEFAULT_HOST : cfg.ntfyServer;
+    bool useHttps = !cfg.ntfyServer.isEmpty(); // Custom servers use HTTPS; ntfy.sh uses plain HTTP
+
+    WiFiClientSecure secureClient;
+    WiFiClient plainClient;
+    Client *client;
+
+    if (useHttps) {
+        secureClient.setInsecure(); // Skip cert validation — self-hosted server
+        secureClient.setTimeout(NTFY_CONNECT_TIMEOUT_MS);
+        if (!secureClient.connect(host.c_str(), 443)) {
+            LOG("NOTIF", "TLS connect to %s:443 failed", host.c_str());
+            dataLogger.logNotification("notif_send_fail", message, false);
+            return;
+        }
+        client = &secureClient;
+    } else {
+        plainClient.setTimeout(NTFY_CONNECT_TIMEOUT_MS);
+        if (!plainClient.connect(host.c_str(), 80)) {
+            LOG("NOTIF", "Connect to %s:80 failed", host.c_str());
+            dataLogger.logNotification("notif_send_fail", message, false);
+            return;
+        }
+        client = &plainClient;
+    }
+
+    // Build HTTP POST request
+    client->print("POST /" + topic + " HTTP/1.1\r\n");
+    client->print("Host: " + host + "\r\n");
+    client->print("Content-Type: text/plain\r\n");
+    client->print("Tags: " + tags + "\r\n");
+    client->print("Content-Length: " + String(message.length()) + "\r\n");
+    if (!cfg.ntfyToken.isEmpty()) {
+        client->print("Authorization: Bearer " + cfg.ntfyToken + "\r\n");
+    }
+    client->print("Connection: close\r\n");
+    client->print("\r\n");
+    client->print(message);
+
+    // Read just the HTTP status line (e.g. "HTTP/1.1 200 OK\r\n")
+    bool ok = false;
+    String statusLine = client->readStringUntil('\n');
+    if (statusLine.length() > 0) {
+        int spaceIdx = statusLine.indexOf(' ');
+        if (spaceIdx > 0) {
+            int code = statusLine.substring(spaceIdx + 1, spaceIdx + 4).toInt();
+            ok = (code >= 200 && code < 300);
+            LOG("NOTIF", "Response: %d %s", code, ok ? "OK" : "FAIL");
+        }
+    }
+
+    client->stop();
+
+    dataLogger.logNotification("notif_sent", message, ok);
+}
+
+void NotificationManager::sendTestNotification(const String& topic) {
+    const String& hostname = settings.get().hostname;
+    sendNotification(topic, "bell", hostname + ": Test notification");
+}
diff --git a/firmware/src/notification_manager.h b/firmware/src/notification_manager.h
index 1420874..4f2493b 100644
--- a/firmware/src/notification_manager.h
+++ b/firmware/src/notification_manager.h
@@ -1,59 +1,58 @@
-#ifndef NOTIFICATION_MANAGER_H
-#define NOTIFICATION_MANAGER_H
-
-#include <Arduino.h>
-#include "config.h"
-#include "loop_task.h"
-
-class NeatoSerial;
-class SettingsManager;
-class DataLogger;
-class CleaningHistory;
-
-class NotificationManager : public LoopTask {
-public:
-    NotificationManager(NeatoSerial& neato, SettingsManager& settings, DataLogger& logger,
-                        CleaningHistory& history);
-
-    void begin();
-
-    // Send a test notification to the given topic (called from web server)
-    void sendTestNotification(const String& topic);
-
-private:
-    void tick() override; // Called by LoopTask; skipped while fetchPending
-
-    NeatoSerial& neato;
-    SettingsManager& settings;
-    DataLogger& dataLogger;
-    CleaningHistory& history;
-
-    // Previous state for transition detection
-    String prevUiState;
-    String prevRobotState;
-    bool prevHasError = false;
-    int prevErrorCode = 200; // UI_ALERT_INVALID = no error
-
-    // Track whether the robot was cleaning before entering docking state
-    bool wasCleaningBeforeDock = false;
-
-    // Pending state fetch tracking
-    bool fetchPending = false;
-
-    // Deferred "cleaning done" notification — captured at the cleaning->idle
-    // transition and held until CleaningHistory::stopCollection finalizes the
-    // session stats (sessionId increments) or a wall-clock timeout elapses.
-    bool donePending = false;
-    uint32_t doneTriggerSessionId = 0; // sessionId observed at trigger time
-    unsigned long donePendingSinceMs = 0;
-    String doneHostname; // captured hostname at trigger time
-    String doneTopic;    // captured topic at trigger time
-
-    void checkTransitions();
-    void flushPendingDone();
-    void sendDoneNotification(const String& topic, const String& hostname, bool withStats);
-    void sendNotification(const String& topic, const String& tags, const String& message);
-    static bool isActiveState(const String& uiState);
-};
-
-#endif // NOTIFICATION_MANAGER_H
+#ifndef NOTIFICATION_MANAGER_H
+#define NOTIFICATION_MANAGER_H
+
+#include <Arduino.h>
+#include "config.h"
+#include "loop_task.h"
+
+class NeatoSerial;
+class SettingsManager;
+class DataLogger;
+class CleaningHistory;
+
+class NotificationManager : public LoopTask {
+public:
+    NotificationManager(NeatoSerial& neato, SettingsManager& settings, DataLogger& logger, CleaningHistory& history);
+
+    void begin();
+
+    // Send a test notification to the given topic (called from web server)
+    void sendTestNotification(const String& topic);
+
+private:
+    void tick() override; // Called by LoopTask; skipped while fetchPending
+
+    NeatoSerial& neato;
+    SettingsManager& settings;
+    DataLogger& dataLogger;
+    CleaningHistory& history;
+
+    // Previous state for transition detection
+    String prevUiState;
+    String prevRobotState;
+    bool prevHasError = false;
+    int prevErrorCode = 200; // UI_ALERT_INVALID = no error
+
+    // Track whether the robot was cleaning before entering docking state
+    bool wasCleaningBeforeDock = false;
+
+    // Pending state fetch tracking
+    bool fetchPending = false;
+
+    // Deferred "cleaning done" notification — captured at the cleaning->idle
+    // transition and held until CleaningHistory::stopCollection finalizes the
+    // session stats (sessionId increments) or a wall-clock timeout elapses.
+    bool donePending = false;
+    uint32_t doneTriggerSessionId = 0; // sessionId observed at trigger time
+    unsigned long donePendingSinceMs = 0;
+    String doneHostname; // captured hostname at trigger time
+    String doneTopic; // captured topic at trigger time
+
+    void checkTransitions();
+    void flushPendingDone();
+    void sendDoneNotification(const String& topic, const String& hostname, bool withStats);
+    void sendNotification(const String& topic, const String& tags, const String& message);
+    static bool isActiveState(const String& uiState);
+};
+
+#endif // NOTIFICATION_MANAGER_H
diff --git a/firmware/src/system_manager.cpp b/firmware/src/system_manager.cpp
index ff6db94..def26f6 100644
--- a/firmware/src/system_manager.cpp
+++ b/firmware/src/system_manager.cpp
@@ -1,193 +1,193 @@
-#include "system_manager.h"
-#include <SPIFFS.h>
-#include <WiFi.h>
-#include <ctime>
-#include <esp_idf_version.h>
-
-SystemManager::SystemManager(Preferences& prefs) : LoopTask(5000), prefs(prefs) {
-    TaskRegistry::add(this);
-}
-
-// -- Lifecycle ---------------------------------------------------------------
-
-void SystemManager::begin() {
-    // NTP is configured by SettingsManager via applyTimezone() after settings are loaded
-    LOG("SYS", "System manager initialized (NTP pending timezone from settings)");
-}
-
-// -- Task Watchdog Timer -----------------------------------------------------
-
-void SystemManager::initTaskWdt() {
-    // Initialize TWDT with configured timeout. If loop() stops calling
-    // feedTaskWdt(), the hardware watchdog resets the ESP32.
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
-    // ESP-IDF 5.3+ uses config struct API
-    const esp_task_wdt_config_t wdtCfg = {
-        .timeout_ms = TASK_WDT_TIMEOUT_S * 1000,
-        .idle_core_mask = 0,
-        .trigger_panic = true,
-    };
-    esp_task_wdt_init(&wdtCfg);
-#else
-    esp_task_wdt_init(TASK_WDT_TIMEOUT_S, true); // true = panic (reset) on timeout
-#endif
-    esp_task_wdt_add(nullptr); // nullptr = subscribe current task (loopTask)
-    LOG("SYS", "Task watchdog initialized (%ds timeout)", TASK_WDT_TIMEOUT_S);
-}
-
-void SystemManager::feedTaskWdt() {
-    esp_task_wdt_reset();
-}
-
-void SystemManager::tick() {
-    // Detect NTP sync transition
-    if (!ntpSynced) {
-        time_t t = time(nullptr);
-        if (t > 1700000000) {
-            ntpSynced = true;
-            LOG("SYS", "NTP synced: %ld", static_cast<long>(t));
-            if (ntpSyncCallback) {
-                ntpSyncCallback();
-            }
-        }
-    }
-
-    // Heap watchdog — restart if free heap stays critically low for too long.
-    // This catches scenarios where the web server exhausts sockets/memory and
-    // becomes unresponsive (e.g. after a UART desync cascade). A brief dip is
-    // tolerated; only sustained low heap triggers the restart.
-    size_t freeHeap = ESP.getFreeHeap();
-    if (freeHeap < HEAP_WATCHDOG_THRESHOLD) {
-        if (heapLowSince == 0) {
-            heapLowSince = millis();
-            LOG("SYS", "Heap watchdog: low heap detected (%u bytes)", freeHeap);
-        } else if (millis() - heapLowSince >= HEAP_WATCHDOG_DURATION_MS) {
-            LOG("SYS", "Heap watchdog: heap critically low for %lums (%u bytes), restarting", HEAP_WATCHDOG_DURATION_MS,
-                freeHeap);
-            ESP.restart();
-        }
-    } else {
-        // Heap recovered — reset the timer
-        if (heapLowSince > 0) {
-            LOG("SYS", "Heap watchdog: heap recovered (%u bytes)", freeHeap);
-            heapLowSince = 0;
-        }
-    }
-}
-
-// -- Time --------------------------------------------------------------------
-
-time_t SystemManager::now() const {
-    // Prefer NTP
-    time_t t = time(nullptr);
-    if (t > 1700000000)
-        return t;
-
-    // Fall back to external clock
-    if (fallbackSet && fallbackEpoch > 0) {
-        return fallbackEpoch + (millis() - fallbackMillis) / 1000;
-    }
-
-    // Last resort: uptime as pseudo-timestamp
-    return static_cast<time_t>(millis() / 1000);
-}
-
-void SystemManager::setFallbackClock(time_t epoch) {
-    fallbackEpoch = epoch;
-    fallbackMillis = millis();
-    fallbackSet = true;
-    LOG("SYS", "Fallback clock set: epoch %ld", static_cast<long>(epoch));
-}
-
-// -- Timezone ----------------------------------------------------------------
-
-void SystemManager::applyTimezone(const String& tz) {
-    configTzTime(tz.c_str(), NTP_SERVER_1, NTP_SERVER_2);
-    LOG("SYS", "NTP timezone applied: %s", tz.c_str());
-}
-
-// -- Deferred reboot ---------------------------------------------------------
-
-void SystemManager::restart() {
-    LOG("SYS", "Restart scheduled");
-    pendingRebootAt = millis();
-}
-
-void SystemManager::factoryReset() {
-    LOG("SYS", "Factory reset scheduled");
-    pendingFactoryReset = true;
-    pendingRebootAt = millis();
-}
-
-void SystemManager::formatFs() {
-    LOG("SYS", "Filesystem format scheduled");
-    pendingFormatFs = true;
-    pendingRebootAt = millis();
-}
-
-void SystemManager::checkPendingReboot() {
-    if (pendingRebootAt == 0 || millis() - pendingRebootAt < 500)
-        return;
-
-    if (pendingFactoryReset) {
-        LOG("SYS", "Factory reset: clearing NVS, WiFi credentials, and filesystem...");
-        prefs.clear();
-        WiFi.disconnect(true, true);
-        SPIFFS.format();
-        delay(500);
-    } else if (pendingFormatFs) {
-        LOG("SYS", "Formatting filesystem...");
-        SPIFFS.format();
-        delay(500);
-    }
-    LOG("SYS", "Rebooting...");
-    ESP.restart();
-}
-
-// -- System health -----------------------------------------------------------
-
-std::vector<Field> SystemHealth::toFields() const {
-    return {
-            {"heap", String(heap), FIELD_INT},
-            {"heapTotal", String(heapTotal), FIELD_INT},
-            {"uptime", String(uptime), FIELD_INT},
-            {"rssi", String(rssi), FIELD_INT},
-            {"fsUsed", String(fsUsed), FIELD_INT},
-            {"fsTotal", String(fsTotal), FIELD_INT},
-            {"ntpSynced", ntpSynced ? "true" : "false", FIELD_BOOL},
-            {"time", String(static_cast<long>(time)), FIELD_INT},
-            {"timeSource", timeSource, FIELD_STRING},
-            {"tz", tz, FIELD_STRING},
-            {"localTime", localTime, FIELD_STRING},
-            {"isDst", isDst ? "true" : "false", FIELD_BOOL},
-    };
-}
-
-SystemHealth SystemManager::getSystemHealth(const String& tz) const {
-    SystemHealth h;
-    h.heap = ESP.getFreeHeap();
-    h.heapTotal = ESP.getHeapSize();
-    h.uptime = millis();
-    h.rssi = WiFi.RSSI();
-    h.fsUsed = SPIFFS.usedBytes();
-    h.fsTotal = SPIFFS.totalBytes();
-    h.ntpSynced = ntpSynced;
-    h.time = now();
-    h.timeSource = ntpSynced ? "ntp" : (fallbackSet ? "fallback" : "millis");
-    h.tz = tz;
-
-    // Compute DST-aware local time string via localtime_r (same conversion the
-    // scheduler uses). The POSIX TZ string applied via configTzTime() handles
-    // DST transitions, so this is always correct for the configured timezone.
-    if (h.time > 1700000000) {
-        struct tm tm;
-        localtime_r(&h.time, &tm);
-        static const char *DAYS[] = {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"};
-        char buf[20];
-        snprintf(buf, sizeof(buf), "%s %02d:%02d:%02d", DAYS[tm.tm_wday], tm.tm_hour, tm.tm_min, tm.tm_sec);
-        h.localTime = buf;
-        h.isDst = tm.tm_isdst > 0;
-    }
-
-    return h;
-}
+#include "system_manager.h"
+#include <SPIFFS.h>
+#include <WiFi.h>
+#include <ctime>
+#include <esp_idf_version.h>
+
+SystemManager::SystemManager(Preferences& prefs) : LoopTask(5000), prefs(prefs) {
+    TaskRegistry::add(this);
+}
+
+// -- Lifecycle ---------------------------------------------------------------
+
+void SystemManager::begin() {
+    // NTP is configured by SettingsManager via applyTimezone() after settings are loaded
+    LOG("SYS", "System manager initialized (NTP pending timezone from settings)");
+}
+
+// -- Task Watchdog Timer -----------------------------------------------------
+
+void SystemManager::initTaskWdt() {
+    // Initialize TWDT with configured timeout. If loop() stops calling
+    // feedTaskWdt(), the hardware watchdog resets the ESP32.
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
+    // ESP-IDF 5.3+ uses config struct API
+    const esp_task_wdt_config_t wdtCfg = {
+            .timeout_ms = TASK_WDT_TIMEOUT_S * 1000,
+            .idle_core_mask = 0,
+            .trigger_panic = true,
+    };
+    esp_task_wdt_init(&wdtCfg);
+#else
+    esp_task_wdt_init(TASK_WDT_TIMEOUT_S, true); // true = panic (reset) on timeout
+#endif
+    esp_task_wdt_add(nullptr); // nullptr = subscribe current task (loopTask)
+    LOG("SYS", "Task watchdog initialized (%ds timeout)", TASK_WDT_TIMEOUT_S);
+}
+
+void SystemManager::feedTaskWdt() {
+    esp_task_wdt_reset();
+}
+
+void SystemManager::tick() {
+    // Detect NTP sync transition
+    if (!ntpSynced) {
+        time_t t = time(nullptr);
+        if (t > 1700000000) {
+            ntpSynced = true;
+            LOG("SYS", "NTP synced: %ld", static_cast<long>(t));
+            if (ntpSyncCallback) {
+                ntpSyncCallback();
+            }
+        }
+    }
+
+    // Heap watchdog — restart if free heap stays critically low for too long.
+    // This catches scenarios where the web server exhausts sockets/memory and
+    // becomes unresponsive (e.g. after a UART desync cascade). A brief dip is
+    // tolerated; only sustained low heap triggers the restart.
+    size_t freeHeap = ESP.getFreeHeap();
+    if (freeHeap < HEAP_WATCHDOG_THRESHOLD) {
+        if (heapLowSince == 0) {
+            heapLowSince = millis();
+            LOG("SYS", "Heap watchdog: low heap detected (%u bytes)", freeHeap);
+        } else if (millis() - heapLowSince >= HEAP_WATCHDOG_DURATION_MS) {
+            LOG("SYS", "Heap watchdog: heap critically low for %lums (%u bytes), restarting", HEAP_WATCHDOG_DURATION_MS,
+                freeHeap);
+            ESP.restart();
+        }
+    } else {
+        // Heap recovered — reset the timer
+        if (heapLowSince > 0) {
+            LOG("SYS", "Heap watchdog: heap recovered (%u bytes)", freeHeap);
+            heapLowSince = 0;
+        }
+    }
+}
+
+// -- Time --------------------------------------------------------------------
+
+time_t SystemManager::now() const {
+    // Prefer NTP
+    time_t t = time(nullptr);
+    if (t > 1700000000)
+        return t;
+
+    // Fall back to external clock
+    if (fallbackSet && fallbackEpoch > 0) {
+        return fallbackEpoch + (millis() - fallbackMillis) / 1000;
+    }
+
+    // Last resort: uptime as pseudo-timestamp
+    return static_cast<time_t>(millis() / 1000);
+}
+
+void SystemManager::setFallbackClock(time_t epoch) {
+    fallbackEpoch = epoch;
+    fallbackMillis = millis();
+    fallbackSet = true;
+    LOG("SYS", "Fallback clock set: epoch %ld", static_cast<long>(epoch));
+}
+
+// -- Timezone ----------------------------------------------------------------
+
+void SystemManager::applyTimezone(const String& tz) {
+    configTzTime(tz.c_str(), NTP_SERVER_1, NTP_SERVER_2);
+    LOG("SYS", "NTP timezone applied: %s", tz.c_str());
+}
+
+// -- Deferred reboot ---------------------------------------------------------
+
+void SystemManager::restart() {
+    LOG("SYS", "Restart scheduled");
+    pendingRebootAt = millis();
+}
+
+void SystemManager::factoryReset() {
+    LOG("SYS", "Factory reset scheduled");
+    pendingFactoryReset = true;
+    pendingRebootAt = millis();
+}
+
+void SystemManager::formatFs() {
+    LOG("SYS", "Filesystem format scheduled");
+    pendingFormatFs = true;
+    pendingRebootAt = millis();
+}
+
+void SystemManager::checkPendingReboot() {
+    if (pendingRebootAt == 0 || millis() - pendingRebootAt < 500)
+        return;
+
+    if (pendingFactoryReset) {
+        LOG("SYS", "Factory reset: clearing NVS, WiFi credentials, and filesystem...");
+        prefs.clear();
+        WiFi.disconnect(true, true);
+        SPIFFS.format();
+        delay(500);
+    } else if (pendingFormatFs) {
+        LOG("SYS", "Formatting filesystem...");
+        SPIFFS.format();
+        delay(500);
+    }
+    LOG("SYS", "Rebooting...");
+    ESP.restart();
+}
+
+// -- System health -----------------------------------------------------------
+
+std::vector<Field> SystemHealth::toFields() const {
+    return {
+            {"heap", String(heap), FIELD_INT},
+            {"heapTotal", String(heapTotal), FIELD_INT},
+            {"uptime", String(uptime), FIELD_INT},
+            {"rssi", String(rssi), FIELD_INT},
+            {"fsUsed", String(fsUsed), FIELD_INT},
+            {"fsTotal", String(fsTotal), FIELD_INT},
+            {"ntpSynced", ntpSynced ? "true" : "false", FIELD_BOOL},
+            {"time", String(static_cast<long>(time)), FIELD_INT},
+            {"timeSource", timeSource, FIELD_STRING},
+            {"tz", tz, FIELD_STRING},
+            {"localTime", localTime, FIELD_STRING},
+            {"isDst", isDst ? "true" : "false", FIELD_BOOL},
+    };
+}
+
+SystemHealth SystemManager::getSystemHealth(const String& tz) const {
+    SystemHealth h;
+    h.heap = ESP.getFreeHeap();
+    h.heapTotal = ESP.getHeapSize();
+    h.uptime = millis();
+    h.rssi = WiFi.RSSI();
+    h.fsUsed = SPIFFS.usedBytes();
+    h.fsTotal = SPIFFS.totalBytes();
+    h.ntpSynced = ntpSynced;
+    h.time = now();
+    h.timeSource = ntpSynced ? "ntp" : (fallbackSet ? "fallback" : "millis");
+    h.tz = tz;
+
+    // Compute DST-aware local time string via localtime_r (same conversion the
+    // scheduler uses). The POSIX TZ string applied via configTzTime() handles
+    // DST transitions, so this is always correct for the configured timezone.
+    if (h.time > 1700000000) {
+        struct tm tm;
+        localtime_r(&h.time, &tm);
+        static const char *DAYS[] = {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"};
+        char buf[20];
+        snprintf(buf, sizeof(buf), "%s %02d:%02d:%02d", DAYS[tm.tm_wday], tm.tm_hour, tm.tm_min, tm.tm_sec);
+        h.localTime = buf;
+        h.isDst = tm.tm_isdst > 0;
+    }
+
+    return h;
+}
diff --git a/firmware/src/web_server.cpp b/firmware/src/web_server.cpp
index d1a494e..168583d 100644
--- a/firmware/src/web_server.cpp
+++ b/firmware/src/web_server.cpp
@@ -1,539 +1,538 @@
-#include "web_server.h"
-#include "web_assets.h"
-#include "neato_serial.h"
-#include "data_logger.h"
-#include "system_manager.h"
-#include "settings_manager.h"
-#include "firmware_manager.h"
-#include "manual_clean_manager.h"
-#include "notification_manager.h"
-#include "cleaning_history.h"
-#include "wifi_manager.h"
-#include <SPIFFS.h>
-
-unsigned long WebServer::lastApiActivity = 0;
-
-WebServer::WebServer(AsyncWebServer& server, NeatoSerial& neato, DataLogger& logger, SystemManager& sys,
-                     FirmwareManager& fw, SettingsManager& settings, ManualCleanManager& manual,
-                     NotificationManager& notif, CleaningHistory& history, WiFiManager& wifi) :
-    server(server), neato(neato), logger(logger), sysMgr(sys), fwMgr(fw), settingsMgr(settings), manualMgr(manual),
-    notifMgr(notif), historyMgr(history), wifiMgr(wifi) {}
-
-void WebServer::loggedRoute(const char *path, WebRequestMethodComposite httpMethod, SyncHandler handler) {
-    server.on(path, httpMethod, [this, handler](AsyncWebServerRequest *request) {
-        lastApiActivity = millis();
-        unsigned long startMs = lastApiActivity;
-        int status = handler(request);
-        logger.logRequest(request->method(), request->url().c_str(), status, millis() - startMs);
-    });
-}
-
-void WebServer::loggedBodyRoute(const char *path, WebRequestMethodComposite httpMethod, BodyHandler handler) {
-    server.on(
-            path, httpMethod, [](AsyncWebServerRequest *request) { /* handled in body callback */ }, nullptr,
-            [this, handler](AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t, size_t) {
-                lastApiActivity = millis();
-                unsigned long startMs = lastApiActivity;
-                int status = handler(request, data, len);
-                logger.logRequest(request->method(), request->url().c_str(), status, millis() - startMs);
-            });
-}
-
-void WebServer::sendGzipAsset(AsyncWebServerRequest *request, const uint8_t *data, size_t len,
-                              const char *contentType) {
-    AsyncWebServerResponse *response = request->beginResponse(200, contentType, data, len);
-    response->addHeader("Content-Encoding", "gzip");
-    request->send(response);
-}
-
-void WebServer::sendError(AsyncWebServerRequest *request, int code, const String& msg) {
-    request->send(code, "application/json", fieldsToJson({{"error", msg, FIELD_STRING}}));
-}
-
-void WebServer::sendOk(AsyncWebServerRequest *request) {
-    request->send(200, "application/json", fieldsToJson({{"ok", "true", FIELD_BOOL}}));
-}
-
-void WebServer::begin() {
-    // Register all embedded frontend assets from the auto-generated registry
-    for (size_t i = 0; i < WEB_ASSETS_COUNT; i++) {
-        const WebAsset& asset = WEB_ASSETS[i];
-        server.on(asset.path, HTTP_GET, [&asset](AsyncWebServerRequest *request) {
-            sendGzipAsset(request, asset.data, asset.length, asset.contentType);
-        });
-    }
-
-    LOG("WEB", "Registered %u embedded assets", WEB_ASSETS_COUNT);
-
-    registerApiRoutes();
-    registerManualRoutes();
-    registerLogRoutes();
-    registerSystemRoutes();
-    registerSettingsRoutes();
-    registerFirmwareRoutes();
-    registerMapRoutes();
-    registerWiFiRoutes();
-
-    LOG("WEB", "Frontend and API routes registered");
-}
-
-void WebServer::registerApiRoutes() {
-    // -- Sensor query endpoints ----------------------------------------------
-
-    registerGetRoute("/api/version", neato, &NeatoSerial::getVersion, {});
-    registerGetRoute("/api/charger", neato, &NeatoSerial::getCharger, {});
-    registerGetRoute("/api/analog", neato, &NeatoSerial::getBatteryAnalog, {});
-    registerGetRoute("/api/warranty", neato, &NeatoSerial::getBatteryWarranty, {});
-    registerGetRoute(
-            "/api/motors", neato,
-            static_cast<void (NeatoSerial::*)(std::function<void(bool, const MotorData&)>)>(&NeatoSerial::getMotors),
-            {});
-    registerGetRoute("/api/state", neato, &NeatoSerial::getState, {});
-    registerGetRoute("/api/error", neato, &NeatoSerial::getErr, {});
-    registerGetRoute("/api/lidar", neato, &NeatoSerial::getLdsScan, {});
-    registerGetRoute("/api/user-settings", neato, &NeatoSerial::getUserSettings, {});
-    registerGetRoute(
-            "/api/sensors", neato,
-            static_cast<void (NeatoSerial::*)(std::function<void(bool, const DigitalSensorData&)>)>(
-                    &NeatoSerial::getDigitalSensors),
-            {});
-
-    // -- Action endpoints ----------------------------------------------------
-    // All parameterized actions use query strings: resource URL identifies the
-    // command, query params carry arguments (mirrors Neato serial protocol).
-
-    registerPostRoute("/api/clean", neato, &NeatoSerial::clean, {"action"});
-    registerPostRoute("/api/sound", neato, &NeatoSerial::playSound, {"id"});
-    registerPostRoute("/api/power", neato, &NeatoSerial::powerControl, {"action"});
-    registerPostRoute("/api/lidar/rotate", neato, &NeatoSerial::setLdsRotation, {"enable"});
-    registerPostRoute("/api/user-settings", neato, &NeatoSerial::setUserSetting, {"key", "value"});
-    registerPostRoute("/api/clear-errors", neato, &NeatoSerial::clearErrors, {});
-    registerPostRoute("/api/battery/new", neato, &NeatoSerial::newBattery, {});
-
-    // Serial endpoint — send arbitrary serial command, returns raw response.
-    // Always available (no debug gate — useful for diagnostics without enabling verbose logging).
-    // Excluded from public API docs (diagnostics-only passthrough).
-    server.on("/api/serial", HTTP_POST, [this](AsyncWebServerRequest *request) {
-        lastApiActivity = millis();
-        unsigned long startMs = lastApiActivity;
-
-        if (!request->hasParam("cmd")) {
-            logger.logRequest(HTTP_POST, "/api/serial", 400, millis() - startMs);
-            sendError(request, 400, "missing cmd");
-            return;
-        }
-        String cmd = request->getParam("cmd")->value();
-        if (cmd.isEmpty()) {
-            logger.logRequest(HTTP_POST, "/api/serial", 400, millis() - startMs);
-            sendError(request, 400, "empty cmd");
-            return;
-        }
-
-        auto weak = request->pause();
-        bool ok = neato.sendRaw(cmd, [this, weak, startMs](bool /*success*/, const String& response) {
-            if (auto req = weak.lock()) {
-                unsigned long elapsed = millis() - startMs;
-                logger.logRequest(HTTP_POST, "/api/serial", 200, elapsed);
-                req->send(200, "text/plain", response);
-            }
-        });
-        if (!ok) {
-            logger.logRequest(HTTP_POST, "/api/serial", 503, millis() - startMs);
-            sendError(request, 503, "unavailable");
-        }
-    });
-
-    LOG("WEB", "API routes registered");
-}
-
-// -- Manual clean endpoints ---------------------------------------------------
-
-void WebServer::registerManualRoutes() {
-    // Register longer paths first — ESPAsyncWebServer matches routes by prefix,
-    // so /api/manual would swallow /api/manual/move and /api/manual/motors.
-
-    loggedRoute("/api/manual/status", HTTP_GET, [this](AsyncWebServerRequest *request) {
-        request->send(200, "application/json", manualMgr.getStatusJson());
-        return 200;
-    });
-    registerPostRoute("/api/manual/move", manualMgr, &ManualCleanManager::move, {"left", "right", "speed"});
-    registerPostRoute("/api/manual/motors", manualMgr, &ManualCleanManager::setMotors,
-                      {"brush", "vacuum", "sideBrush"});
-    registerPostRoute("/api/manual", manualMgr, &ManualCleanManager::enable, {"enable"});
-
-    LOG("WEB", "Manual clean routes registered");
-}
-
-// -- Log file endpoints ------------------------------------------------------
-
-// Strip .hs extension so browser saves a plain .jsonl file
-static String downloadName(const String& filename) {
-    if (filename.endsWith(".hs"))
-        return filename.substring(0, filename.length() - 3);
-    return filename;
-}
-
-static String logListJson(const std::vector<LogFileInfo>& files) {
-    String json = "[";
-    for (size_t i = 0; i < files.size(); i++) {
-        if (i > 0)
-            json += ",";
-        json += files[i].toJson();
-    }
-    json += "]";
-    return json;
-}
-
-void WebServer::registerLogRoutes() {
-
-    // GET /api/logs[/filename] — list logs or download a specific file
-    // A single BackwardCompatible handler matches both "/api/logs" and "/api/logs/..."
-    // This route uses server.on() directly instead of loggedRoute() because
-    // compressed log downloads use chunked streaming (beginChunkedResponse) which
-    // must not block — loggedRoute's sync wrapper would block until completion.
-    server.on("/api/logs", HTTP_GET, [this](AsyncWebServerRequest *request) {
-        unsigned long startMs = millis();
-        String filename = request->url().substring(String("/api/logs/").length());
-
-        if (filename.isEmpty()) {
-            String json = logListJson(logger.listLogs());
-            logger.logRequest(HTTP_GET, "/api/logs", 200, millis() - startMs);
-            request->send(200, "application/json", json);
-            return;
-        }
-
-        // Open log via DataLogger — handles path resolution and transparent decompression
-        auto reader = logger.readLog(filename);
-        if (!reader) {
-            logger.logRequest(HTTP_GET, request->url().c_str(), 404, millis() - startMs);
-            sendError(request, 404, "log not found");
-            return;
-        }
-
-        logger.logRequest(HTTP_GET, request->url().c_str(), 200, millis() - startMs);
-
-        // Stream log content via chunked response — reader handles decompression
-        AsyncWebServerResponse *response = request->beginChunkedResponse(
-                "application/x-ndjson",
-                [reader](uint8_t *buffer, size_t maxLen, size_t) -> size_t { return reader->read(buffer, maxLen); });
-
-        response->addHeader("Content-Disposition", "attachment; filename=\"" + downloadName(filename) + "\"");
-
-        request->send(response);
-    });
-
-    // DELETE /api/logs[/filename] — delete all logs or a specific file
-    loggedRoute("/api/logs", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
-        String filename = request->url().substring(String("/api/logs/").length());
-
-        if (filename.isEmpty()) {
-            logger.deleteAllLogs();
-            sendOk(request);
-            return 200;
-        }
-
-        if (logger.deleteLog(filename)) {
-            sendOk(request);
-            return 200;
-        }
-
-        sendError(request, 404, "log not found");
-        return 404;
-    });
-
-    LOG("WEB", "Log routes registered");
-}
-
-// -- System health endpoint ---------------------------------------------------
-
-void WebServer::registerSystemRoutes() {
-
-    // GET /api/system — live system health (heap, uptime, RSSI, storage, NTP)
-    loggedRoute("/api/system", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
-        request->send(200, "application/json", sysMgr.getSystemHealth(settingsMgr.get().tz).toJson());
-        return 200;
-    });
-
-    // POST /api/system/restart — deferred restart
-    loggedRoute("/api/system/restart", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
-        sendOk(request);
-        sysMgr.restart();
-        return 200;
-    });
-
-    // POST /api/system/reset — factory reset (clears NVS + WiFi, then restarts)
-    loggedRoute("/api/system/reset", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
-        sendOk(request);
-        sysMgr.factoryReset();
-        return 200;
-    });
-
-    // POST /api/system/format-fs — format filesystem (erases logs + map data, then restarts)
-    loggedRoute("/api/system/format-fs", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
-        sendOk(request);
-        sysMgr.formatFs();
-        return 200;
-    });
-
-    LOG("WEB", "System routes registered");
-}
-
-// -- Settings endpoint -------------------------------------------------------
-
-void WebServer::registerSettingsRoutes() {
-
-    // GET /api/settings — all user-configurable settings
-    loggedRoute("/api/settings", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
-        request->send(200, "application/json", settingsMgr.get().toJson());
-        return 200;
-    });
-
-    // PUT /api/settings — partial update (only fields present are written)
-    loggedBodyRoute("/api/settings", HTTP_PUT,
-                    [this](AsyncWebServerRequest *request, uint8_t *data, size_t len) -> int {
-                        String body = String(reinterpret_cast<const char *>(data), len);
-                        ApplyResult result = settingsMgr.apply(body);
-                        if (result == APPLY_INVALID) {
-                            sendError(request, 400, "Invalid settings");
-                            return 400;
-                        }
-                        if (result == APPLY_CHANGED) {
-                            // Push manual clean settings to manager (no reboot needed)
-                            const auto& s = settingsMgr.get();
-                            manualMgr.setStallThreshold(s.stallThreshold);
-                            manualMgr.setBrushRpm(s.brushRpm);
-                            manualMgr.setVacuumSpeed(s.vacuumSpeed);
-                            manualMgr.setSideBrushPower(s.sideBrushPower);
-                        }
-                        request->send(200, "application/json", settingsMgr.get().toJson());
-                        return 200;
-                    });
-
-    // POST /api/notifications/test?topic=<topic> — send a test notification
-    loggedRoute("/api/notifications/test", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
-        if (!request->hasParam("topic")) {
-            sendError(request, 400, "missing topic");
-            return 400;
-        }
-        String topic = request->getParam("topic")->value();
-        if (topic.isEmpty()) {
-            sendError(request, 400, "topic cannot be empty");
-            return 400;
-        }
-        notifMgr.sendTestNotification(topic);
-        sendOk(request);
-        return 200;
-    });
-
-    LOG("WEB", "Settings routes registered");
-}
-
-// -- Firmware endpoints -------------------------------------------------------
-
-void WebServer::registerFirmwareRoutes() {
-
-    // GET /api/firmware/version — current ESP32 firmware version + chip model + robot support status
-    loggedRoute("/api/firmware/version", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
-        std::vector<Field> fields = {
-                {"name", "OpenNeato", FIELD_STRING},
-                {"version", fwMgr.getFirmwareVersion(), FIELD_STRING},
-                {"chip", fwMgr.getChipModel(), FIELD_STRING},
-                {"model", neato.getModelName(), FIELD_STRING},
-                {"hostname", settingsMgr.get().hostname, FIELD_STRING},
-                {"supported", isSupportedModel(neato.getModelName()) ? "true" : "false", FIELD_BOOL},
-                {"identifying", neato.isIdentifying() ? "true" : "false", FIELD_BOOL},
-                {"repositoryUrl", "https://github.com/renjfk/OpenNeato", FIELD_STRING},
-                {"license", "MIT", FIELD_STRING},
-        };
-        request->send(200, "application/json", fieldsToJson(fields));
-        return 200;
-    });
-
-    // POST /api/firmware/update?hash=<md5> — single-request firmware upload
-    server.on(
-            "/api/firmware/update", HTTP_POST,
-            // Response handler (called after upload completes)
-            [this](AsyncWebServerRequest *request) {
-                unsigned long startMs = millis();
-                bool ok = fwMgr.getError().isEmpty();
-
-                if (ok) {
-                    ok = fwMgr.endUpdate();
-                }
-
-                if (!ok) {
-                    logger.logRequest(HTTP_POST, "/api/firmware/update", 400, millis() - startMs);
-                    sendError(request, 400, fwMgr.getError());
-                } else {
-                    logger.logRequest(HTTP_POST, "/api/firmware/update", 200, millis() - startMs);
-                    AsyncWebServerResponse *response = request->beginResponse(200, "text/plain", "OK");
-                    response->addHeader("Connection", "close");
-                    request->send(response);
-                }
-            },
-            // Upload handler (called per chunk)
-            [this](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len,
-                   bool final) {
-                // First chunk: initialize update session
-                if (!index) {
-                    String md5 = request->hasParam("hash") ? request->getParam("hash")->value() : "";
-                    if (!fwMgr.beginUpdate(md5)) {
-                        return;
-                    }
-                }
-
-                if (len) {
-                    fwMgr.writeChunk(data, len);
-
-                    // Report progress at most once per second
-                    static unsigned long lastProgressMs = 0;
-                    unsigned long now = millis();
-                    if (now - lastProgressMs >= 1000) {
-                        auto percent = static_cast<uint8_t>(
-                                request->contentLength() > 0 ? static_cast<float>(fwMgr.getProgress()) * 100.0f /
-                                                                       static_cast<float>(request->contentLength())
-                                                             : 0);
-                        LOG("FW", "Progress: %u%% (%zu/%zu bytes)", percent, fwMgr.getProgress(),
-                            request->contentLength());
-                        lastProgressMs = now;
-                    }
-                }
-            });
-
-    LOG("WEB", "Firmware routes registered");
-}
-
-// -- Map data endpoints -------------------------------------------------------
-
-void WebServer::registerMapRoutes() {
-
-    // GET /api/history[/filename] — list sessions, collection status, or download a specific file
-    server.on("/api/history", HTTP_GET, [this](AsyncWebServerRequest *request) {
-        lastApiActivity = millis();
-        unsigned long startMs = lastApiActivity;
-        String suffix = request->url().substring(String("/api/history/").length());
-
-        if (suffix.isEmpty()) {
-            // List all session files with embedded session/summary metadata
-            auto sessions = historyMgr.listSessions();
-            String json = "[";
-            for (size_t i = 0; i < sessions.size(); i++) {
-                if (i > 0)
-                    json += ",";
-                const auto& s = sessions[i];
-                json += R"({"name":")" + s.name + R"(","size":)" + String(static_cast<unsigned long>(s.size)) +
-                        R"(,"compressed":)" + String(s.compressed ? "true" : "false") + R"(,"recording":)" +
-                        String(s.recording ? "true" : "false");
-                if (s.session.length() > 0) {
-                    json += ",\"session\":" + s.session;
-                } else {
-                    json += ",\"session\":null";
-                }
-                if (s.summary.length() > 0) {
-                    json += ",\"summary\":" + s.summary;
-                } else {
-                    json += ",\"summary\":null";
-                }
-                json += "}";
-            }
-            json += "]";
-            logger.logRequest(HTTP_GET, "/api/history", 200, millis() - startMs);
-            request->send(200, "application/json", json);
-            return;
-        }
-
-        // Download specific session
-        auto reader = historyMgr.readSession(suffix);
-        if (!reader) {
-            logger.logRequest(HTTP_GET, request->url().c_str(), 404, millis() - startMs);
-            sendError(request, 404, "session not found");
-            return;
-        }
-
-        logger.logRequest(HTTP_GET, request->url().c_str(), 200, millis() - startMs);
-
-        AsyncWebServerResponse *response = request->beginChunkedResponse(
-                "application/x-ndjson",
-                [reader](uint8_t *buffer, size_t maxLen, size_t) -> size_t { return reader->read(buffer, maxLen); });
-
-        response->addHeader("Content-Disposition", "attachment; filename=\"" + downloadName(suffix) + "\"");
-
-        request->send(response);
-    });
-
-    // DELETE /api/history[/filename] — delete one or all sessions
-    loggedRoute("/api/history", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
-        String filename = request->url().substring(String("/api/history/").length());
-
-        if (filename.isEmpty()) {
-            historyMgr.deleteAllSessions();
-            sendOk(request);
-            return 200;
-        }
-
-        if (historyMgr.deleteSession(filename)) {
-            sendOk(request);
-            return 200;
-        }
-
-        sendError(request, 404, "session not found");
-        return 404;
-    });
-
-    // POST /api/history/import — upload a .jsonl session file, compress and store
-    server.on(
-            "/api/history/import", HTTP_POST,
-            // Response handler (called after upload completes)
-            [this](AsyncWebServerRequest *request) {
-                unsigned long startMs = millis();
-                bool ok = historyMgr.getImportError().isEmpty();
-
-                if (ok) {
-                    ok = historyMgr.endImport();
-                }
-
-                if (!ok) {
-                    logger.logRequest(HTTP_POST, "/api/history/import", 400, millis() - startMs);
-                    sendError(request, 400, historyMgr.getImportError());
-                } else {
-                    logger.logRequest(HTTP_POST, "/api/history/import", 200, millis() - startMs);
-                    sendOk(request);
-                }
-            },
-            // Upload handler (called per chunk)
-            [this](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len,
-                   bool final) {
-                // First chunk: initialize import session
-                if (!index) {
-                    if (!historyMgr.beginImport(filename)) {
-                        return;
-                    }
-                }
-
-                if (len && historyMgr.isImporting()) {
-                    historyMgr.writeImportChunk(data, len);
-                }
-            });
-
-    LOG("WEB", "History routes registered");
-}
-
-// -- WiFi management endpoints -----------------------------------------------
-
-void WebServer::registerWiFiRoutes() {
-    // GET /api/wifi/status , STA + fallback AP snapshot
-    registerGetRoute("/api/wifi/status", wifiMgr, &WiFiManager::getStatus, {});
-
-    // GET /api/wifi/scan , list nearby networks
-    registerGetRoute("/api/wifi/scan", wifiMgr, &WiFiManager::scanNetworks, {});
-
-    // POST /api/wifi/connect?ssid=&password= , save credentials and connect.
-    // On success the device reboots into normal STA mode; on failure the
-    // fallback AP stays up so the user can retry.
-    registerPostRoute("/api/wifi/connect", wifiMgr, &WiFiManager::connect, {"ssid", "password"});
-
-    // POST /api/wifi/disconnect , clear credentials and drop the connection
-    registerPostRoute("/api/wifi/disconnect", wifiMgr, &WiFiManager::disconnect, {});
-
-    LOG("WEB", "WiFi routes registered");
-}
+#include "web_server.h"
+#include "web_assets.h"
+#include "neato_serial.h"
+#include "data_logger.h"
+#include "system_manager.h"
+#include "settings_manager.h"
+#include "firmware_manager.h"
+#include "manual_clean_manager.h"
+#include "notification_manager.h"
+#include "cleaning_history.h"
+#include "wifi_manager.h"
+#include <SPIFFS.h>
+
+unsigned long WebServer::lastApiActivity = 0;
+
+WebServer::WebServer(AsyncWebServer& server, NeatoSerial& neato, DataLogger& logger, SystemManager& sys,
+                     FirmwareManager& fw, SettingsManager& settings, ManualCleanManager& manual,
+                     NotificationManager& notif, CleaningHistory& history, WiFiManager& wifi) :
+    server(server), neato(neato), logger(logger), sysMgr(sys), fwMgr(fw), settingsMgr(settings), manualMgr(manual),
+    notifMgr(notif), historyMgr(history), wifiMgr(wifi) {}
+
+void WebServer::loggedRoute(const char *path, WebRequestMethodComposite httpMethod, SyncHandler handler) {
+    server.on(path, httpMethod, [this, handler](AsyncWebServerRequest *request) {
+        lastApiActivity = millis();
+        unsigned long startMs = lastApiActivity;
+        int status = handler(request);
+        logger.logRequest(request->method(), request->url().c_str(), status, millis() - startMs);
+    });
+}
+
+void WebServer::loggedBodyRoute(const char *path, WebRequestMethodComposite httpMethod, BodyHandler handler) {
+    server.on(
+            path, httpMethod, [](AsyncWebServerRequest *request) { /* handled in body callback */ }, nullptr,
+            [this, handler](AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t, size_t) {
+                lastApiActivity = millis();
+                unsigned long startMs = lastApiActivity;
+                int status = handler(request, data, len);
+                logger.logRequest(request->method(), request->url().c_str(), status, millis() - startMs);
+            });
+}
+
+void WebServer::sendGzipAsset(AsyncWebServerRequest *request, const uint8_t *data, size_t len,
+                              const char *contentType) {
+    AsyncWebServerResponse *response = request->beginResponse(200, contentType, data, len);
+    response->addHeader("Content-Encoding", "gzip");
+    request->send(response);
+}
+
+void WebServer::sendError(AsyncWebServerRequest *request, int code, const String& msg) {
+    request->send(code, "application/json", fieldsToJson({{"error", msg, FIELD_STRING}}));
+}
+
+void WebServer::sendOk(AsyncWebServerRequest *request) {
+    request->send(200, "application/json", fieldsToJson({{"ok", "true", FIELD_BOOL}}));
+}
+
+void WebServer::begin() {
+    // Register all embedded frontend assets from the auto-generated registry
+    for (size_t i = 0; i < WEB_ASSETS_COUNT; i++) {
+        const WebAsset& asset = WEB_ASSETS[i];
+        server.on(asset.path, HTTP_GET, [&asset](AsyncWebServerRequest *request) {
+            sendGzipAsset(request, asset.data, asset.length, asset.contentType);
+        });
+    }
+
+    LOG("WEB", "Registered %u embedded assets", WEB_ASSETS_COUNT);
+
+    registerApiRoutes();
+    registerManualRoutes();
+    registerLogRoutes();
+    registerSystemRoutes();
+    registerSettingsRoutes();
+    registerFirmwareRoutes();
+    registerMapRoutes();
+    registerWiFiRoutes();
+
+    LOG("WEB", "Frontend and API routes registered");
+}
+
+void WebServer::registerApiRoutes() {
+    // -- Sensor query endpoints ----------------------------------------------
+
+    registerGetRoute("/api/version", neato, &NeatoSerial::getVersion, {});
+    registerGetRoute("/api/charger", neato, &NeatoSerial::getCharger, {});
+    registerGetRoute("/api/analog", neato, &NeatoSerial::getBatteryAnalog, {});
+    registerGetRoute("/api/warranty", neato, &NeatoSerial::getBatteryWarranty, {});
+    registerGetRoute(
+            "/api/motors", neato,
+            static_cast<void (NeatoSerial::*)(std::function<void(bool, const MotorData&)>)>(&NeatoSerial::getMotors),
+            {});
+    registerGetRoute("/api/state", neato, &NeatoSerial::getState, {});
+    registerGetRoute("/api/error", neato, &NeatoSerial::getErr, {});
+    registerGetRoute("/api/lidar", neato, &NeatoSerial::getLdsScan, {});
+    registerGetRoute("/api/user-settings", neato, &NeatoSerial::getUserSettings, {});
+    registerGetRoute("/api/sensors", neato,
+                     static_cast<void (NeatoSerial::*)(std::function<void(bool, const DigitalSensorData&)>)>(
+                             &NeatoSerial::getDigitalSensors),
+                     {});
+
+    // -- Action endpoints ----------------------------------------------------
+    // All parameterized actions use query strings: resource URL identifies the
+    // command, query params carry arguments (mirrors Neato serial protocol).
+
+    registerPostRoute("/api/clean", neato, &NeatoSerial::clean, {"action"});
+    registerPostRoute("/api/sound", neato, &NeatoSerial::playSound, {"id"});
+    registerPostRoute("/api/power", neato, &NeatoSerial::powerControl, {"action"});
+    registerPostRoute("/api/lidar/rotate", neato, &NeatoSerial::setLdsRotation, {"enable"});
+    registerPostRoute("/api/user-settings", neato, &NeatoSerial::setUserSetting, {"key", "value"});
+    registerPostRoute("/api/clear-errors", neato, &NeatoSerial::clearErrors, {});
+    registerPostRoute("/api/battery/new", neato, &NeatoSerial::newBattery, {});
+
+    // Serial endpoint — send arbitrary serial command, returns raw response.
+    // Always available (no debug gate — useful for diagnostics without enabling verbose logging).
+    // Excluded from public API docs (diagnostics-only passthrough).
+    server.on("/api/serial", HTTP_POST, [this](AsyncWebServerRequest *request) {
+        lastApiActivity = millis();
+        unsigned long startMs = lastApiActivity;
+
+        if (!request->hasParam("cmd")) {
+            logger.logRequest(HTTP_POST, "/api/serial", 400, millis() - startMs);
+            sendError(request, 400, "missing cmd");
+            return;
+        }
+        String cmd = request->getParam("cmd")->value();
+        if (cmd.isEmpty()) {
+            logger.logRequest(HTTP_POST, "/api/serial", 400, millis() - startMs);
+            sendError(request, 400, "empty cmd");
+            return;
+        }
+
+        auto weak = request->pause();
+        bool ok = neato.sendRaw(cmd, [this, weak, startMs](bool /*success*/, const String& response) {
+            if (auto req = weak.lock()) {
+                unsigned long elapsed = millis() - startMs;
+                logger.logRequest(HTTP_POST, "/api/serial", 200, elapsed);
+                req->send(200, "text/plain", response);
+            }
+        });
+        if (!ok) {
+            logger.logRequest(HTTP_POST, "/api/serial", 503, millis() - startMs);
+            sendError(request, 503, "unavailable");
+        }
+    });
+
+    LOG("WEB", "API routes registered");
+}
+
+// -- Manual clean endpoints ---------------------------------------------------
+
+void WebServer::registerManualRoutes() {
+    // Register longer paths first — ESPAsyncWebServer matches routes by prefix,
+    // so /api/manual would swallow /api/manual/move and /api/manual/motors.
+
+    loggedRoute("/api/manual/status", HTTP_GET, [this](AsyncWebServerRequest *request) {
+        request->send(200, "application/json", manualMgr.getStatusJson());
+        return 200;
+    });
+    registerPostRoute("/api/manual/move", manualMgr, &ManualCleanManager::move, {"left", "right", "speed"});
+    registerPostRoute("/api/manual/motors", manualMgr, &ManualCleanManager::setMotors,
+                      {"brush", "vacuum", "sideBrush"});
+    registerPostRoute("/api/manual", manualMgr, &ManualCleanManager::enable, {"enable"});
+
+    LOG("WEB", "Manual clean routes registered");
+}
+
+// -- Log file endpoints ------------------------------------------------------
+
+// Strip .hs extension so browser saves a plain .jsonl file
+static String downloadName(const String& filename) {
+    if (filename.endsWith(".hs"))
+        return filename.substring(0, filename.length() - 3);
+    return filename;
+}
+
+static String logListJson(const std::vector<LogFileInfo>& files) {
+    String json = "[";
+    for (size_t i = 0; i < files.size(); i++) {
+        if (i > 0)
+            json += ",";
+        json += files[i].toJson();
+    }
+    json += "]";
+    return json;
+}
+
+void WebServer::registerLogRoutes() {
+
+    // GET /api/logs[/filename] — list logs or download a specific file
+    // A single BackwardCompatible handler matches both "/api/logs" and "/api/logs/..."
+    // This route uses server.on() directly instead of loggedRoute() because
+    // compressed log downloads use chunked streaming (beginChunkedResponse) which
+    // must not block — loggedRoute's sync wrapper would block until completion.
+    server.on("/api/logs", HTTP_GET, [this](AsyncWebServerRequest *request) {
+        unsigned long startMs = millis();
+        String filename = request->url().substring(String("/api/logs/").length());
+
+        if (filename.isEmpty()) {
+            String json = logListJson(logger.listLogs());
+            logger.logRequest(HTTP_GET, "/api/logs", 200, millis() - startMs);
+            request->send(200, "application/json", json);
+            return;
+        }
+
+        // Open log via DataLogger — handles path resolution and transparent decompression
+        auto reader = logger.readLog(filename);
+        if (!reader) {
+            logger.logRequest(HTTP_GET, request->url().c_str(), 404, millis() - startMs);
+            sendError(request, 404, "log not found");
+            return;
+        }
+
+        logger.logRequest(HTTP_GET, request->url().c_str(), 200, millis() - startMs);
+
+        // Stream log content via chunked response — reader handles decompression
+        AsyncWebServerResponse *response = request->beginChunkedResponse(
+                "application/x-ndjson",
+                [reader](uint8_t *buffer, size_t maxLen, size_t) -> size_t { return reader->read(buffer, maxLen); });
+
+        response->addHeader("Content-Disposition", "attachment; filename=\"" + downloadName(filename) + "\"");
+
+        request->send(response);
+    });
+
+    // DELETE /api/logs[/filename] — delete all logs or a specific file
+    loggedRoute("/api/logs", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
+        String filename = request->url().substring(String("/api/logs/").length());
+
+        if (filename.isEmpty()) {
+            logger.deleteAllLogs();
+            sendOk(request);
+            return 200;
+        }
+
+        if (logger.deleteLog(filename)) {
+            sendOk(request);
+            return 200;
+        }
+
+        sendError(request, 404, "log not found");
+        return 404;
+    });
+
+    LOG("WEB", "Log routes registered");
+}
+
+// -- System health endpoint ---------------------------------------------------
+
+void WebServer::registerSystemRoutes() {
+
+    // GET /api/system — live system health (heap, uptime, RSSI, storage, NTP)
+    loggedRoute("/api/system", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
+        request->send(200, "application/json", sysMgr.getSystemHealth(settingsMgr.get().tz).toJson());
+        return 200;
+    });
+
+    // POST /api/system/restart — deferred restart
+    loggedRoute("/api/system/restart", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
+        sendOk(request);
+        sysMgr.restart();
+        return 200;
+    });
+
+    // POST /api/system/reset — factory reset (clears NVS + WiFi, then restarts)
+    loggedRoute("/api/system/reset", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
+        sendOk(request);
+        sysMgr.factoryReset();
+        return 200;
+    });
+
+    // POST /api/system/format-fs — format filesystem (erases logs + map data, then restarts)
+    loggedRoute("/api/system/format-fs", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
+        sendOk(request);
+        sysMgr.formatFs();
+        return 200;
+    });
+
+    LOG("WEB", "System routes registered");
+}
+
+// -- Settings endpoint -------------------------------------------------------
+
+void WebServer::registerSettingsRoutes() {
+
+    // GET /api/settings — all user-configurable settings
+    loggedRoute("/api/settings", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
+        request->send(200, "application/json", settingsMgr.get().toJson());
+        return 200;
+    });
+
+    // PUT /api/settings — partial update (only fields present are written)
+    loggedBodyRoute("/api/settings", HTTP_PUT,
+                    [this](AsyncWebServerRequest *request, uint8_t *data, size_t len) -> int {
+                        String body = String(reinterpret_cast<const char *>(data), len);
+                        ApplyResult result = settingsMgr.apply(body);
+                        if (result == APPLY_INVALID) {
+                            sendError(request, 400, "Invalid settings");
+                            return 400;
+                        }
+                        if (result == APPLY_CHANGED) {
+                            // Push manual clean settings to manager (no reboot needed)
+                            const auto& s = settingsMgr.get();
+                            manualMgr.setStallThreshold(s.stallThreshold);
+                            manualMgr.setBrushRpm(s.brushRpm);
+                            manualMgr.setVacuumSpeed(s.vacuumSpeed);
+                            manualMgr.setSideBrushPower(s.sideBrushPower);
+                        }
+                        request->send(200, "application/json", settingsMgr.get().toJson());
+                        return 200;
+                    });
+
+    // POST /api/notifications/test?topic=<topic> — send a test notification
+    loggedRoute("/api/notifications/test", HTTP_POST, [this](AsyncWebServerRequest *request) -> int {
+        if (!request->hasParam("topic")) {
+            sendError(request, 400, "missing topic");
+            return 400;
+        }
+        String topic = request->getParam("topic")->value();
+        if (topic.isEmpty()) {
+            sendError(request, 400, "topic cannot be empty");
+            return 400;
+        }
+        notifMgr.sendTestNotification(topic);
+        sendOk(request);
+        return 200;
+    });
+
+    LOG("WEB", "Settings routes registered");
+}
+
+// -- Firmware endpoints -------------------------------------------------------
+
+void WebServer::registerFirmwareRoutes() {
+
+    // GET /api/firmware/version — current ESP32 firmware version + chip model + robot support status
+    loggedRoute("/api/firmware/version", HTTP_GET, [this](AsyncWebServerRequest *request) -> int {
+        std::vector<Field> fields = {
+                {"name", "OpenNeato", FIELD_STRING},
+                {"version", fwMgr.getFirmwareVersion(), FIELD_STRING},
+                {"chip", fwMgr.getChipModel(), FIELD_STRING},
+                {"model", neato.getModelName(), FIELD_STRING},
+                {"hostname", settingsMgr.get().hostname, FIELD_STRING},
+                {"supported", isSupportedModel(neato.getModelName()) ? "true" : "false", FIELD_BOOL},
+                {"identifying", neato.isIdentifying() ? "true" : "false", FIELD_BOOL},
+                {"repositoryUrl", "https://github.com/renjfk/OpenNeato", FIELD_STRING},
+                {"license", "MIT", FIELD_STRING},
+        };
+        request->send(200, "application/json", fieldsToJson(fields));
+        return 200;
+    });
+
+    // POST /api/firmware/update?hash=<md5> — single-request firmware upload
+    server.on(
+            "/api/firmware/update", HTTP_POST,
+            // Response handler (called after upload completes)
+            [this](AsyncWebServerRequest *request) {
+                unsigned long startMs = millis();
+                bool ok = fwMgr.getError().isEmpty();
+
+                if (ok) {
+                    ok = fwMgr.endUpdate();
+                }
+
+                if (!ok) {
+                    logger.logRequest(HTTP_POST, "/api/firmware/update", 400, millis() - startMs);
+                    sendError(request, 400, fwMgr.getError());
+                } else {
+                    logger.logRequest(HTTP_POST, "/api/firmware/update", 200, millis() - startMs);
+                    AsyncWebServerResponse *response = request->beginResponse(200, "text/plain", "OK");
+                    response->addHeader("Connection", "close");
+                    request->send(response);
+                }
+            },
+            // Upload handler (called per chunk)
+            [this](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len,
+                   bool final) {
+                // First chunk: initialize update session
+                if (!index) {
+                    String md5 = request->hasParam("hash") ? request->getParam("hash")->value() : "";
+                    if (!fwMgr.beginUpdate(md5)) {
+                        return;
+                    }
+                }
+
+                if (len) {
+                    fwMgr.writeChunk(data, len);
+
+                    // Report progress at most once per second
+                    static unsigned long lastProgressMs = 0;
+                    unsigned long now = millis();
+                    if (now - lastProgressMs >= 1000) {
+                        auto percent = static_cast<uint8_t>(
+                                request->contentLength() > 0 ? static_cast<float>(fwMgr.getProgress()) * 100.0f /
+                                                                       static_cast<float>(request->contentLength())
+                                                             : 0);
+                        LOG("FW", "Progress: %u%% (%zu/%zu bytes)", percent, fwMgr.getProgress(),
+                            request->contentLength());
+                        lastProgressMs = now;
+                    }
+                }
+            });
+
+    LOG("WEB", "Firmware routes registered");
+}
+
+// -- Map data endpoints -------------------------------------------------------
+
+void WebServer::registerMapRoutes() {
+
+    // GET /api/history[/filename] — list sessions, collection status, or download a specific file
+    server.on("/api/history", HTTP_GET, [this](AsyncWebServerRequest *request) {
+        lastApiActivity = millis();
+        unsigned long startMs = lastApiActivity;
+        String suffix = request->url().substring(String("/api/history/").length());
+
+        if (suffix.isEmpty()) {
+            // List all session files with embedded session/summary metadata
+            auto sessions = historyMgr.listSessions();
+            String json = "[";
+            for (size_t i = 0; i < sessions.size(); i++) {
+                if (i > 0)
+                    json += ",";
+                const auto& s = sessions[i];
+                json += R"({"name":")" + s.name + R"(","size":)" + String(static_cast<unsigned long>(s.size)) +
+                        R"(,"compressed":)" + String(s.compressed ? "true" : "false") + R"(,"recording":)" +
+                        String(s.recording ? "true" : "false");
+                if (s.session.length() > 0) {
+                    json += ",\"session\":" + s.session;
+                } else {
+                    json += ",\"session\":null";
+                }
+                if (s.summary.length() > 0) {
+                    json += ",\"summary\":" + s.summary;
+                } else {
+                    json += ",\"summary\":null";
+                }
+                json += "}";
+            }
+            json += "]";
+            logger.logRequest(HTTP_GET, "/api/history", 200, millis() - startMs);
+            request->send(200, "application/json", json);
+            return;
+        }
+
+        // Download specific session
+        auto reader = historyMgr.readSession(suffix);
+        if (!reader) {
+            logger.logRequest(HTTP_GET, request->url().c_str(), 404, millis() - startMs);
+            sendError(request, 404, "session not found");
+            return;
+        }
+
+        logger.logRequest(HTTP_GET, request->url().c_str(), 200, millis() - startMs);
+
+        AsyncWebServerResponse *response = request->beginChunkedResponse(
+                "application/x-ndjson",
+                [reader](uint8_t *buffer, size_t maxLen, size_t) -> size_t { return reader->read(buffer, maxLen); });
+
+        response->addHeader("Content-Disposition", "attachment; filename=\"" + downloadName(suffix) + "\"");
+
+        request->send(response);
+    });
+
+    // DELETE /api/history[/filename] — delete one or all sessions
+    loggedRoute("/api/history", HTTP_DELETE, [this](AsyncWebServerRequest *request) -> int {
+        String filename = request->url().substring(String("/api/history/").length());
+
+        if (filename.isEmpty()) {
+            historyMgr.deleteAllSessions();
+            sendOk(request);
+            return 200;
+        }
+
+        if (historyMgr.deleteSession(filename)) {
+            sendOk(request);
+            return 200;
+        }
+
+        sendError(request, 404, "session not found");
+        return 404;
+    });
+
+    // POST /api/history/import — upload a .jsonl session file, compress and store
+    server.on(
+            "/api/history/import", HTTP_POST,
+            // Response handler (called after upload completes)
+            [this](AsyncWebServerRequest *request) {
+                unsigned long startMs = millis();
+                bool ok = historyMgr.getImportError().isEmpty();
+
+                if (ok) {
+                    ok = historyMgr.endImport();
+                }
+
+                if (!ok) {
+                    logger.logRequest(HTTP_POST, "/api/history/import", 400, millis() - startMs);
+                    sendError(request, 400, historyMgr.getImportError());
+                } else {
+                    logger.logRequest(HTTP_POST, "/api/history/import", 200, millis() - startMs);
+                    sendOk(request);
+                }
+            },
+            // Upload handler (called per chunk)
+            [this](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len,
+                   bool final) {
+                // First chunk: initialize import session
+                if (!index) {
+                    if (!historyMgr.beginImport(filename)) {
+                        return;
+                    }
+                }
+
+                if (len && historyMgr.isImporting()) {
+                    historyMgr.writeImportChunk(data, len);
+                }
+            });
+
+    LOG("WEB", "History routes registered");
+}
+
+// -- WiFi management endpoints -----------------------------------------------
+
+void WebServer::registerWiFiRoutes() {
+    // GET /api/wifi/status , STA + fallback AP snapshot
+    registerGetRoute("/api/wifi/status", wifiMgr, &WiFiManager::getStatus, {});
+
+    // GET /api/wifi/scan , list nearby networks
+    registerGetRoute("/api/wifi/scan", wifiMgr, &WiFiManager::scanNetworks, {});
+
+    // POST /api/wifi/connect?ssid=&password= , save credentials and connect.
+    // On success the device reboots into normal STA mode; on failure the
+    // fallback AP stays up so the user can retry.
+    registerPostRoute("/api/wifi/connect", wifiMgr, &WiFiManager::connect, {"ssid", "password"});
+
+    // POST /api/wifi/disconnect , clear credentials and drop the connection
+    registerPostRoute("/api/wifi/disconnect", wifiMgr, &WiFiManager::disconnect, {});
+
+    LOG("WEB", "WiFi routes registered");
+}

From bc85f601a9ec46cad9349bfecccac5d61dffa3a3 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:15:10 -0400
Subject: [PATCH 40/44] ci: add c6-debug to firmware matrix + artifact upload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the ESP32-C6 target to the CI build matrix so PRs and main pushes
verify it compiles. The [board_c6] / [env:c6-*] platformio.ini entries
already exist (pioarduino 54.03.21-2 platform); they just weren't gated
in CI.

Also uploads the c6-debug build's firmware.bin (+ bootloader / partitions)
as an actions artifact, retention 7 days. Lets you OTA-flash the C6 bridge
without a working local pioarduino install — useful on Windows where the
toolchain dance is finicky. Only c6-debug uploads to keep storage low;
other targets can opt in if needed.
---
 .github/workflows/ci.yml | 261 ++++++++++++++++++++-------------------
 1 file changed, 136 insertions(+), 125 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 78e3d53..cf35a03 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,125 +1,136 @@
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-    paths-ignore:
-      - 'custom_components/**'
-      - '.github/workflows/release.yml'
-      - '.github/workflows/release-ha.yml'
-      - '.github/workflows/prerelease.yml'
-      - '.github/workflows/slash-command.yml'
-      - '**/*.md'
-      - 'docs/**'
-      - 'LICENSE'
-      - '.gitignore'
-      - '.gitattributes'
-      - 'hacs.json'
-  pull_request:
-    paths-ignore:
-      - 'custom_components/**'
-      - '.github/workflows/release.yml'
-      - '.github/workflows/release-ha.yml'
-      - '.github/workflows/prerelease.yml'
-      - '.github/workflows/slash-command.yml'
-      - '**/*.md'
-      - 'docs/**'
-      - 'LICENSE'
-      - '.gitignore'
-      - '.gitattributes'
-      - 'hacs.json'
-
-permissions:
-  contents: read
-
-jobs:
-  firmware:
-    name: Firmware (${{ matrix.env }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        env: [c3-debug, s3-debug, esp32-debug]
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Build frontend (generates web_assets.h)
-        run: npm ci && npm run build
-        working-directory: frontend
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Cache PlatformIO
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.platformio/platforms
-            ~/.platformio/packages
-          key: platformio-${{ matrix.env }}-${{ hashFiles('platformio.ini') }}
-
-      - name: Install PlatformIO
-        # intelhex is an unlisted runtime dep of the newer tool-esptoolpy
-        # bundled with pioarduino 54.x; esptool imports it at module load.
-        run: pip install platformio intelhex
-
-      - name: Build firmware
-        run: pio run -e ${{ matrix.env }}
-
-      - name: Format check (clang-format)
-        run: python scripts/check_format.py
-
-      - name: Static analysis (clang-tidy)
-        run: pio check -e ${{ matrix.env }} --fail-on-defect=low
-
-  frontend:
-    name: Frontend
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-        working-directory: frontend
-
-      - name: Lint and format check
-        run: npm run check
-        working-directory: frontend
-
-      - name: Build (lint + typecheck + vite + embed)
-        run: npm run build
-        working-directory: frontend
-
-  flash-tool:
-    name: Flash Tool
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-go@v5
-        with:
-          go-version-file: flash/go.mod
-
-      - name: Lint
-        uses: golangci/golangci-lint-action@v7
-        with:
-          version: v2.11.3
-          args: ./...
-          working-directory: flash
-
-      - name: Build
-        run: go build -o openneato-flash .
-        working-directory: flash
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - 'custom_components/**'
+      - '.github/workflows/release.yml'
+      - '.github/workflows/release-ha.yml'
+      - '.github/workflows/prerelease.yml'
+      - '.github/workflows/slash-command.yml'
+      - '**/*.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - '.gitattributes'
+      - 'hacs.json'
+  pull_request:
+    paths-ignore:
+      - 'custom_components/**'
+      - '.github/workflows/release.yml'
+      - '.github/workflows/release-ha.yml'
+      - '.github/workflows/prerelease.yml'
+      - '.github/workflows/slash-command.yml'
+      - '**/*.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - '.gitattributes'
+      - 'hacs.json'
+
+permissions:
+  contents: read
+
+jobs:
+  firmware:
+    name: Firmware (${{ matrix.env }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        env: [c3-debug, c6-debug, s3-debug, esp32-debug]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend (generates web_assets.h)
+        run: npm ci && npm run build
+        working-directory: frontend
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache PlatformIO
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.platformio/platforms
+            ~/.platformio/packages
+          key: platformio-${{ matrix.env }}-${{ hashFiles('platformio.ini') }}
+
+      - name: Install PlatformIO
+        # intelhex is an unlisted runtime dep of the newer tool-esptoolpy
+        # bundled with pioarduino 54.x; esptool imports it at module load.
+        run: pip install platformio intelhex
+
+      - name: Build firmware
+        run: pio run -e ${{ matrix.env }}
+
+      - name: Upload firmware binary
+        if: matrix.env == 'c6-debug'
+        uses: actions/upload-artifact@v4
+        with:
+          name: firmware-${{ matrix.env }}
+          path: |
+            .pio/build/${{ matrix.env }}/firmware.bin
+            .pio/build/${{ matrix.env }}/partitions.bin
+            .pio/build/${{ matrix.env }}/bootloader.bin
+          retention-days: 7
+
+      - name: Format check (clang-format)
+        run: python scripts/check_format.py
+
+      - name: Static analysis (clang-tidy)
+        run: pio check -e ${{ matrix.env }} --fail-on-defect=low
+
+  frontend:
+    name: Frontend
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: frontend
+
+      - name: Lint and format check
+        run: npm run check
+        working-directory: frontend
+
+      - name: Build (lint + typecheck + vite + embed)
+        run: npm run build
+        working-directory: frontend
+
+  flash-tool:
+    name: Flash Tool
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: flash/go.mod
+
+      - name: Lint
+        uses: golangci/golangci-lint-action@v7
+        with:
+          version: v2.11.3
+          args: ./...
+          working-directory: flash
+
+      - name: Build
+        run: go build -o openneato-flash .
+        working-directory: flash

From da6772f985b1801f56dd580818068cf29158f02c Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:20:44 -0400
Subject: [PATCH 41/44] ci: add c6-ota to matrix; upload its firmware.bin as
 artifact
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

c6-debug overflows the 1.5625 MB OTA slot (~1.7 MB binary — debug strings
push it over). c6-ota disables logging (-DENABLE_LOGGING=0), which fits.
Both targets stay in the matrix so debug-build regressions still show up;
the artifact comes from c6-ota since that's what you actually OTA-flash
to the bridge.
---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cf35a03..dafefa8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,7 +39,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        env: [c3-debug, c6-debug, s3-debug, esp32-debug]
+        env: [c3-debug, c6-debug, c6-ota, s3-debug, esp32-debug]
     steps:
       - uses: actions/checkout@v4
 
@@ -74,7 +74,7 @@ jobs:
         run: pio run -e ${{ matrix.env }}
 
       - name: Upload firmware binary
-        if: matrix.env == 'c6-debug'
+        if: matrix.env == 'c6-ota'
         uses: actions/upload-artifact@v4
         with:
           name: firmware-${{ matrix.env }}

From ad3e5d891781c03671354ea816cbeb1e39a6930f Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:28:06 -0400
Subject: [PATCH 42/44] build(c6): add -DCORE_DEBUG_LEVEL=0 to ota/release
 flags

C6 ota build overshoots the 1.5625 MB OTA slot by ~42 KB. Arduino-ESP32's
log_e/log_w/log_i/log_d macros expand based on CORE_DEBUG_LEVEL; defaulting
to 0 strips the format strings and call sites that the framework's WiFi /
BLE / 802.15.4 layers emit. ENABLE_LOGGING=0 only covers our own LOG()
helper, not the framework's. Trying this first before resorting to a C6
partition table change.
---
 platformio.ini | 329 +++++++++++++++++++++++++------------------------
 1 file changed, 167 insertions(+), 162 deletions(-)

diff --git a/platformio.ini b/platformio.ini
index d19e4f6..6ce1ddc 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -1,162 +1,167 @@
-; PlatformIO Project Configuration File
-;
-; Structure:
-;   [env]           — shared settings (platform, framework, libraries, partitions, checks)
-;   [board_*]       — board-specific settings (board, build flags)
-;   [mode_*]        — build mode settings (debug, ota, release)
-;   [env:<board>-<mode>] — concrete targets combining board + mode
-;
-; To add a new board, create a [board_xyz] section and new env entries
-; that extend both the board and a mode (e.g. [env:xyz-debug]).
-;
-; *-release envs auto-generate release artifacts (firmware.bin + full.tar.gz)
-; via a post-build hook in scripts/env_config.py. GoReleaser picks these up
-; from .pio/build/*-release/ via extra_files globs. CHIP_MODEL build flag is
-; required for each board — the hook reads it to name the artifacts.
-;
-; https://docs.platformio.org/page/projectconf.html
-
-[platformio]
-src_dir = firmware/src
-lib_dir = firmware/lib
-
-; --- Shared across all boards and modes ---------------------------------------
-
-[env]
-platform = espressif32 @ 7.0.1
-framework = arduino
-extra_scripts = pre:scripts/env_config.py
-board_build.partitions = firmware/partition.csv
-board_build.filesystem = spiffs
-upload_speed = 115200
-monitor_speed = 115200
-check_tool = clangtidy
-check_flags =
-    clangtidy: --config-file=.clang-tidy
-check_skip_packages = yes
-lib_compat_mode = strict
-lib_ldf_mode = chain
-lib_deps =
-    ESP32Async/AsyncTCP @ 3.4.10
-    ESP32Async/ESPAsyncWebServer @ 3.11.0
-
-; --- Build modes --------------------------------------------------------------
-
-[mode_ota]
-upload_protocol = custom
-upload_command = bash -c 'HASH=$$(md5sum "$SOURCE" | cut -d" " -f1) && curl -f --progress-bar -F "file=@$SOURCE" "http://$UPLOAD_PORT/api/firmware/update?hash=$$HASH"'
-
-; --- Board: ESP32-C3-DevKitM-1 -----------------------------------------------
-
-[board_c3]
-board = esp32-c3-devkitm-1
-build_flags =
-    -Wno-attributes
-    -DARDUINO_USB_MODE=1
-    -DARDUINO_USB_CDC_ON_BOOT=1
-    -DCHIP_MODEL=\"ESP32-C3\"
-    -std=gnu++17
-
-; --- Targets (C3) -------------------------------------------------------------
-
-[env:c3-debug]
-extends = board_c3
-
-[env:c3-ota]
-extends = board_c3, mode_ota
-build_flags =
-    ${board_c3.build_flags}
-    -DENABLE_LOGGING=0
-
-[env:c3-release]
-extends = board_c3
-build_flags =
-    ${board_c3.build_flags}
-    -DENABLE_LOGGING=0
-
-; --- Board: ESP32-C6-DevKitC-1 (RISC-V, single-core, WiFi 6) -----------------
-
-[board_c6]
-platform = https://github.com/pioarduino/platform-espressif32/releases/download/54.03.21-2/platform-espressif32.zip
-board = esp32-c6-devkitc-1
-build_flags =
-    -DARDUINO_USB_MODE=1
-    -DARDUINO_USB_CDC_ON_BOOT=1
-    -DCHIP_MODEL=\"ESP32-C6\"
-    -std=gnu++17
-    ; To pre-seed WiFi credentials at build time (useful for first OTA flash):
-    ; -DPRESET_WIFI_SSID=\"YourSSID\"
-    ; -DPRESET_WIFI_PASS=\"YourPassword\"
-
-; --- Targets (C6) -------------------------------------------------------------
-
-[env:c6-debug]
-extends = board_c6
-
-[env:c6-ota]
-extends = board_c6, mode_ota
-build_flags =
-    ${board_c6.build_flags}
-    -DENABLE_LOGGING=0
-
-[env:c6-release]
-extends = board_c6
-build_flags =
-    ${board_c6.build_flags}
-    -DENABLE_LOGGING=0
-
-; --- Board: ESP32-S3-DevKitC-1 (Xtensa LX7, dual-core, native USB) -----------
-
-[board_s3]
-board = esp32-s3-devkitc-1
-board_build.flash_size = 4MB
-board_upload.flash_size = 4MB
-build_flags =
-    -Wno-attributes
-    -DARDUINO_USB_MODE=1
-    -DARDUINO_USB_CDC_ON_BOOT=1
-    -DCHIP_MODEL=\"ESP32-S3\"
-    -std=gnu++17
-
-; --- Targets (S3) -------------------------------------------------------------
-
-[env:s3-debug]
-extends = board_s3
-
-[env:s3-ota]
-extends = board_s3, mode_ota
-build_flags =
-    ${board_s3.build_flags}
-    -DENABLE_LOGGING=0
-
-[env:s3-release]
-extends = board_s3
-build_flags =
-    ${board_s3.build_flags}
-    -DENABLE_LOGGING=0
-
-; --- Board: ESP32-D0WD-V3 (original ESP32, Xtensa LX6) ----------------------
-
-[board_esp32]
-board = esp32dev
-build_flags =
-    -Wno-attributes
-    -DCHIP_MODEL=\"ESP32\"
-    -std=gnu++17
-
-; --- Targets (ESP32) ----------------------------------------------------------
-
-[env:esp32-debug]
-extends = board_esp32
-
-[env:esp32-ota]
-extends = board_esp32, mode_ota
-build_flags =
-    ${board_esp32.build_flags}
-    -DENABLE_LOGGING=0
-
-[env:esp32-release]
-extends = board_esp32
-build_flags =
-    ${board_esp32.build_flags}
-    -DENABLE_LOGGING=0
+; PlatformIO Project Configuration File
+;
+;   Build options: build flags, source filter
+;   Upload options: custom upload port, speed and extra flags
+;   Library options: dependencies, extra library storages
+;   Advanced options: extra scripting
+;
+; Please visit documentation for the other options and examples
+; https://docs.platformio.org/page/projectconf.html
+
+[platformio]
+src_dir = firmware/src
+lib_dir = firmware/lib
+
+[env]
+platform = espressif32 @ 7.0.1
+framework = arduino
+extra_scripts = pre:scripts/env_config.py
+board_build.partitions = firmware/partition.csv
+board_build.filesystem = spiffs
+upload_speed = 115200
+monitor_speed = 115200
+check_tool = clangtidy
+check_flags = 
+	clangtidy: --config-file=.clang-tidy
+check_skip_packages = yes
+lib_compat_mode = strict
+lib_ldf_mode = chain
+lib_deps = 
+	ESP32Async/AsyncTCP @ 3.4.10
+	ESP32Async/ESPAsyncWebServer @ 3.11.0
+
+[mode_ota]
+upload_protocol = custom
+upload_command = bash -c 'HASH=$$(md5sum "$SOURCE" | cut -d" " -f1) && curl -f --progress-bar -F "file=@$SOURCE" "http://$UPLOAD_PORT/api/firmware/update?hash=$$HASH"'
+
+[board_c3]
+board = esp32-c3-devkitm-1
+build_flags = 
+	-Wno-attributes
+	-DARDUINO_USB_MODE=1
+	-DARDUINO_USB_CDC_ON_BOOT=1
+	-DCHIP_MODEL=\"ESP32-C3\"
+	-std=gnu++17
+
+[env:c3-debug]
+extends = board_c3
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:c3-ota]
+extends = board_c3, mode_ota
+build_flags = 
+	${board_c3.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:c3-release]
+extends = board_c3
+build_flags = 
+	${board_c3.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[board_c6]
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/54.03.21-2/platform-espressif32.zip
+board = esp32-c6-devkitc-1
+build_flags = 
+	-DARDUINO_USB_MODE=1
+	-DARDUINO_USB_CDC_ON_BOOT=1
+	-DCHIP_MODEL=\"ESP32-C6\"
+	-std=gnu++17
+
+[env:c6-debug]
+extends = board_c6
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:c6-ota]
+extends = board_c6, mode_ota
+build_flags = 
+	${board_c6.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:c6-release]
+extends = board_c6
+build_flags = 
+	${board_c6.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[board_s3]
+board = esp32-s3-devkitc-1
+board_build.flash_size = 4MB
+board_upload.flash_size = 4MB
+build_flags = 
+	-Wno-attributes
+	-DARDUINO_USB_MODE=1
+	-DARDUINO_USB_CDC_ON_BOOT=1
+	-DCHIP_MODEL=\"ESP32-S3\"
+	-std=gnu++17
+
+[env:s3-debug]
+extends = board_s3
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:s3-ota]
+extends = board_s3, mode_ota
+build_flags = 
+	${board_s3.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:s3-release]
+extends = board_s3
+build_flags = 
+	${board_s3.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[board_esp32]
+board = esp32dev
+build_flags = 
+	-Wno-attributes
+	-DCHIP_MODEL=\"ESP32\"
+	-std=gnu++17
+
+[env:esp32-debug]
+extends = board_esp32
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:esp32-ota]
+extends = board_esp32, mode_ota
+build_flags = 
+	${board_esp32.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0
+
+[env:esp32-release]
+extends = board_esp32
+build_flags = 
+	${board_esp32.build_flags}
+	-DENABLE_LOGGING=0
+platform_packages = 
+	pioarduino/tool-esptoolpy@^5.0.2
+	platformio/tool-esptoolpy@^2.41100.0

From e80ffba8db47f4c38c0a59d2e5db0860aa356d0c Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:28:46 -0400
Subject: [PATCH 43/44] build(c6): actually apply CORE_DEBUG_LEVEL=0 + revert
 local pio cruft

Previous commit (ad3e5d8) was supposed to add -DCORE_DEBUG_LEVEL=0 to c6
ota/release flags but my Edit failed silently because pio had rewritten
platformio.ini locally (added 'platform_packages' blocks pinning both
pioarduino and platformio editions of tool-esptoolpy after a local
package-install hiccup). That cruft also slipped into ad3e5d8.

This commit:
- Actually adds -DCORE_DEBUG_LEVEL=0 to c6-ota and c6-release build_flags
- Removes the spurious platform_packages blocks from both envs (CI installs
  tool-esptoolpy via 'pip install platformio intelhex' just fine without
  the override).
---
 platformio.ini | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/platformio.ini b/platformio.ini
index 6ce1ddc..d37802a 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -84,21 +84,17 @@ platform_packages =
 
 [env:c6-ota]
 extends = board_c6, mode_ota
-build_flags = 
+build_flags =
 	${board_c6.build_flags}
 	-DENABLE_LOGGING=0
-platform_packages = 
-	pioarduino/tool-esptoolpy@^5.0.2
-	platformio/tool-esptoolpy@^2.41100.0
+	-DCORE_DEBUG_LEVEL=0
 
 [env:c6-release]
 extends = board_c6
-build_flags = 
+build_flags =
 	${board_c6.build_flags}
 	-DENABLE_LOGGING=0
-platform_packages = 
-	pioarduino/tool-esptoolpy@^5.0.2
-	platformio/tool-esptoolpy@^2.41100.0
+	-DCORE_DEBUG_LEVEL=0
 
 [board_s3]
 board = esp32-s3-devkitc-1

From 7642b4199247d56780db0448b0efe57fb1084670 Mon Sep 17 00:00:00 2001
From: Antoine Weill--Duflos <antoine@haply.co>
Date: Sat, 23 May 2026 13:32:56 -0400
Subject: [PATCH 44/44] build(c6): drop tool-esptoolpy override on c6-debug

The 'platform_packages = pioarduino/tool-esptoolpy@^5.0.2' override broke
the pioarduino 54.03.21 platform's auto-resolution: build script ends up
calling 'python esptool.py' with a relative path that doesn't exist in the
workspace. c6-ota and c6-release didn't have the override and built cleanly
in CI; c6-debug had it and failed at bootloader.bin generation. Removing it.
---
 platformio.ini | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/platformio.ini b/platformio.ini
index d37802a..979ca5d 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -78,9 +78,6 @@ build_flags =
 
 [env:c6-debug]
 extends = board_c6
-platform_packages = 
-	pioarduino/tool-esptoolpy@^5.0.2
-	platformio/tool-esptoolpy@^2.41100.0
 
 [env:c6-ota]
 extends = board_c6, mode_ota