refactor(http): serve web UI from LittleFS, bundled with Vite

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,7 +8,7 @@
 - [ ] Breaking HTTP / pins / NVS / servo defaults / hook CLI called out as `type!:` plus a `BREAKING CHANGE:` footer
 - [ ] Firmware: `pio run` and/or `pio test -e native` when that code changed
 - [ ] Packages: `npm test --prefix packages/tiny-engineer-cursor` / `…/tiny-engineer-antigravity` / `…/tiny-engineer-claude-code` when that package changed
-- [ ] HTTP: HTML index (`src/http/index_page.cpp`) + `docs/api.md` (and README / `docs/hardware/testing.md` if the route list changed)
+- [ ] HTTP: HTML index (`ui/index.html`) + `docs/api.md` (and README / `docs/hardware/testing.md` if the route list changed)
 - [ ] Settings: layers in `docs/settings.md`; no raw `access_token` in logs
 - [ ] CAD: `.f3d` + exported `.3mf`; CERN-OHL-S; `AiEmblem.3mf` not used as a branding swap
 - [ ] Pins: `include/pins.h` + `docs/hardware/` together

.github/workflows/ci.yml

@@ -22,6 +22,11 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
       - uses: actions/cache@v4
         with:
           path: |
@@ -61,11 +66,18 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
       - name: Check OLED expression assets
         run: |
           node scripts/expressions/generate.js --check
           node scripts/expressions/test-assets.js
+      - name: Lint and test web UI
+        run: |
+          npm ci --prefix ui
+          npm run lint --prefix ui
+          npm test --prefix ui
       - name: Cursor package tests
         run: npm test --prefix packages/tiny-engineer-cursor
       - name: Antigravity package tests

.github/workflows/release.yml

@@ -18,6 +18,11 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
       - uses: actions/cache@v4
         with:
           path: |

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 __pycache__/
 data/*.*
+data/ui/
 artifacts/
 
 # Cursor hook event log

AGENTS.md

@@ -11,6 +11,7 @@ Tiny Engineer is an open-source ESP32-C3 Wi-Fi desk robot: 3D-printed mechanics,
 | Path | Role |
 | --- | --- |
 | `src/`, `include/`, `lib/`, `data/` | Firmware (PlatformIO) |
+| `ui/` | Web control panel (Vite + ES modules); `pio run` builds, minifies and gzips it onto LittleFS |
 | `packages/` | HTTP / hook CLIs (Cursor, Antigravity, Claude Code, …) — scope `integrations` |
 | `skills/` | Agent skills shared by Claude Code, Cursor and Antigravity — scope `integrations` |
 | `3d_models/` | CAD and printables (CERN-OHL-S) |
@@ -22,7 +23,7 @@ Physical module: **Waveshare ESP32-C3-Zero**. PlatformIO `board = esp32-c3-devki
 
 ## Commands
 
-From the repo root (Node 18+ for packages). Host only — CI never flashes.
+From the repo root (Node 18+ for packages, Node 20.19+ on 20.x or 22.12+ for `ui/` and therefore `pio run`). Host only — CI never flashes.
 
 ```bash
 pio run
@@ -33,6 +34,8 @@ node scripts/expressions/test-assets.js
 npm test --prefix packages/tiny-engineer-cursor
 npm test --prefix packages/tiny-engineer-antigravity
 npm test --prefix packages/tiny-engineer-claude-code
+npm run lint --prefix ui
+npm test --prefix ui
 python3 scripts/check_pcb.py
 ```
 
@@ -51,7 +54,7 @@ Significant: logic, types, APIs, headers, firmware under `src/` / `include/` / `
 
 When adding, removing, or changing method, path, or query params of any HTTP route, update in the **same** change:
 
-1. **HTML index** — [`src/http/index_page.cpp`](src/http/index_page.cpp): endpoint table and param lists for `/anim`, `/settings`, `/test/servo`
+1. **HTML index** — [`ui/index.html`](ui/index.html): endpoint table and param lists for `/anim`, `/settings`, `/test/servo`
 2. **API reference** — [`docs/api.md`](docs/api.md)
 3. **Summaries** — if the endpoint list, params, or boot URLs changed: [`README.md`](README.md) and [`docs/hardware/testing.md`](docs/hardware/testing.md)
 4. **405 paths** — if needed: `isHttpTestPath()` / `handleNotFound` in `src/http/`

CONTRIBUTING.md

@@ -59,7 +59,7 @@ python3 scripts/check_pcb.py
 
 **Firmware.** `pio run` plus native tests when you touch settings validation. Pin changes update [`include/pins.h`](include/pins.h) **and** [`docs/hardware/`](docs/hardware/) in the same PR.
 
-**HTTP / API.** Same PR must update the HTML index ([`src/http/index_page.cpp`](src/http/index_page.cpp)) and [`docs/api.md`](docs/api.md). If the route list, params, or boot URLs changed, also update [`README.md`](README.md) and [`docs/hardware/testing.md`](docs/hardware/testing.md). See [.cursor/rules/sync-api-endpoints.mdc](.cursor/rules/sync-api-endpoints.mdc).
+**HTTP / API.** Same PR must update the HTML index ([`ui/index.html`](ui/index.html)) and [`docs/api.md`](docs/api.md). If the route list, params, or boot URLs changed, also update [`README.md`](README.md) and [`docs/hardware/testing.md`](docs/hardware/testing.md). See [.cursor/rules/sync-api-endpoints.mdc](.cursor/rules/sync-api-endpoints.mdc).
 
 **Settings.** Follow the layer checklist in [docs/settings.md](docs/settings.md). Never log the raw `access_token` (set/unset only).
 

docs/api.md

@@ -6,7 +6,7 @@ Listens on **port 80** after STA Wi-Fi connects, or during setup AP mode at `htt
 
 Optional auth: when an `access_token` is configured in settings, all JSON API routes require `Authorization: Bearer <token>`. Empty token (default) means no auth. `GET /auth` is always public and reports whether auth is required. Missing/wrong token → **401** `{"ok":false,"error":"unauthorized"}`. HTML panel routes stay public (the UI prompts for the token). `Content-Type: application/json`. CORS: `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization`.
 
-When WiFi credentials are not saved yet, control APIs (`/anim`, `/test/*`) return **503** `{"ok":false,"error":"wifi not configured"}`. Setup routes (`/`, `/config`, `/auth`, `/health`, `/settings`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`) stay available on the setup AP.
+When WiFi credentials are not saved yet, control APIs (`/anim`, `/test/*`) return **503** `{"ok":false,"error":"wifi not configured"}`. Setup routes (`/`, `/config`, `/ui/*`, `/auth`, `/health`, `/settings`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`) stay available on the setup AP.
 
 If boot WiFi credentials are missing, the device opens setup AP mode (`TinyEngineer-XXXX`) and serves a five-step setup wizard at `/config` (servo calibration, OLED orientation, RGB LED, speaker test, then Wi-Fi). If saved credentials fail, it reopens setup AP mode. Hardware tests: [`docs/hardware/testing.md`](hardware/testing.md). How to wire this API into AI tools: [`integration.md`](integration.md).
 
@@ -24,7 +24,11 @@ Open in a browser:
 curl http://tiny-engineer.local/
 ```
 
-Returns `Content-Type: text/html; charset=utf-8`.
+Returns `Content-Type: text/html; charset=utf-8`, gzip-encoded. The page is served from LittleFS (`/ui/index.html.gz`); if the filesystem image is missing, or its `/ui/version.txt` does not match the firmware version, it returns **503** with flashing instructions.
+
+### `GET /ui/*`
+
+Web UI assets from LittleFS, gzip-encoded. Bundled files under `/ui/assets/` have content-hashed names and are sent with `Cache-Control: max-age=31536000, immutable`; anything else under `/ui/` is `no-cache`. Always public. Source lives in [`ui/`](../ui/); `pio run` builds it with Vite and gzips the output into `data/ui/`.
 
 ### `GET /auth`
 

docs/flash.md

@@ -41,6 +41,7 @@ Firmware is Arduino on [PlatformIO](https://platformio.org/) ([pioarduino](https
 ### Install and connect
 
 1. Install [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation.html) (or the PlatformIO IDE extension).
+   Also install [Node.js](https://nodejs.org/) 20.19+ on 20.x, or 22.12+: `pio run` builds the web UI in [`ui/`](../ui/) with npm.
 2. Use a USB-C **data** cable. Charge-only cables fail upload and serial.
 3. Plug the data cable into the **main control board USB-C** once the ESP32 is seated on its headers. Advanced breakout build: use the Adafruit 5993, or the C3-Zero onboard USB-C before that breakout is wired — [hardware/wiring.md](hardware/wiring.md).
 
@@ -54,7 +55,7 @@ pio run -t upload       # flash firmware + LittleFS
 pio device monitor      # serial (115200)
 ```
 
-After firmware upload, a post-script also uploads **LittleFS** ([`scripts/upload_fs_after_upload.py`](../scripts/upload_fs_after_upload.py)) so WAV assets (`welcome`, `bell`, and friends) land on the board. If animations move but stay silent, run `pio run -t uploadfs` once.
+After firmware upload, a post-script also uploads **LittleFS** ([`scripts/upload_fs_after_upload.py`](../scripts/upload_fs_after_upload.py)) so the web UI and WAV assets (`welcome`, `bell`, and friends) land on the board. If the web page says the UI is missing, or animations move but stay silent, run `pio run -t uploadfs` once.
 
 Several serial ports:
 
@@ -118,15 +119,16 @@ After that, with the robot on your home Wi-Fi:
 ```bash
 export TINY_ENGINEER_URL=http://192.168.x.x   # default: tiny-engineer.local
 export TINY_ENGINEER_TOKEN=...                # only if access_token is set
-pio run -e ota -t ota       # firmware
-pio run -e ota -t otafs     # LittleFS (WAV assets)
+pio run -e ota -t ota       # LittleFS (web UI, WAV assets), then firmware
 ```
 
+Firmware and filesystem are one release: the web UI is stamped with the firmware version it was built with, and the firmware refuses to serve a UI from another build (`/` returns **503** naming both versions). `-t ota` therefore uploads the filesystem first, waits for the robot to reboot, then uploads the firmware. `pio run -e ota -t otafs` uploads the filesystem alone, for recovery.
+
 These are the same variables the agent integrations read ([integration.md](integration.md)). OTA listens on UDP/TCP port 3232 and only runs while connected to home Wi-Fi, not in setup AP mode. When `access_token` is set it is also the OTA password; changing it applies to OTA without a reboot.
 
 An update is written to the inactive slot and booted once; it becomes permanent only after it connects to Wi-Fi and starts its OTA listener. Firmware that never gets that far is rolled back to the previous slot on the next reset or power cycle. A firmware that hangs needs that power cycle to recover.
 
-A filesystem update that fails midway reboots the robot; re-run `pio run -e ota -t otafs` or fall back to `pio run -e ota -t uploadfs` over USB.
+A filesystem update that fails midway reboots the robot; re-run `pio run -e ota -t ota` or fall back to `pio run -e ota -t upload` over USB.
 
 Partition changes, including a switch back to the default build, cannot be applied over the air. Flash those with `pio run -t upload` over USB.
 

docs/hardware/testing.md

@@ -106,6 +106,7 @@ curl -X POST "http://tiny-engineer.local/test/servo?index=0&angle=90"
 | Method | Path | Body |
 | --- | --- | --- |
 | `GET` | `/` | HTML endpoint index |
+| `GET` | `/ui/*` | Web UI assets from LittleFS (gzip) |
 | `GET` | `/auth` | Auth status (`ok`, `required`, `wifi_configured`, `provisioning`) — always public |
 | `GET` | `/health` | Health JSON — full field list in [api.md](../api.md#get-health) |
 | `GET` / `POST` | `/anim` | Current animation / start one (`name`, optional `interrupt`) — full params in [api.md](../api.md#post-anim) |

docs/settings.md

@@ -52,7 +52,7 @@ Call the getter wherever the value affects behavior (e.g. `settingsVolume()` in
    - Pass pointer into `saveSettings`
 4. Update the “missing …” **400** message to list the new param.
 
-### 4. Web UI — [`src/http/index_page.cpp`](../src/http/index_page.cpp)
+### 4. Web UI — [`ui/`](../ui/)
 
 1. Config form control (`#config-foo`). Use `.range-row` + range/number for 0–N scales (see volume).
 2. `loadSettings()` reads `j.foo`; save POST includes `&foo=…`.
@@ -91,7 +91,7 @@ Flash only when you want to try it on hardware (`pio run -t upload`).
 - **JSON buffer:** `sendSettingsJson` uses a fixed `char` buffer — bump size when adding fields.
 - **Factory reset:** `factoryResetSettings()` in [`reset.cpp`](../src/settings/reset.cpp) clears NVS namespace `te` and writes defaults, including WiFi credentials. Servo min/max (`sranges`), RGB LED mapping (`rgb_ord`), and OLED rotation (`oled_rot`) are written back unchanged. Exposed as `POST /settings/reset`. After reset, power-cycle into setup AP mode to configure WiFi again (WiFi is not editable on the normal Config page). Servo ranges, LED mapping, and screen rotation can be retuned in that wizard.
 - **Hostname-style settings:** freeze the boot value separately if live change cannot apply (see `settingsBootHostname()` / `reboot_required`).
-- **HTML string size:** the panel is a big string literal in `index_page.cpp`; keep controls compact.
+- **UI size:** the panel ships gzipped on LittleFS next to the WAVs; keep controls compact.
 - **Doc drift:** HTML param tables must match `api.md` exactly.
 
 ## Related

docs/testing.md

@@ -26,6 +26,19 @@ pio run -e expression-demo
 
 The `expression-demo` environment builds a separate OLED-only application without changing the default robot build. For a later bench test, follow its [wiring and upload notes](../lib/TinyEngineerExpressions/README.md#standalone-oled-demo), leave the separate servo supply off, and observe all 16 faces through a complete 48-second cycle. Report physical display results separately from host tests and compilation.
 
+## Web UI
+
+The control panel in [`ui/`](../ui/) is linted with [html-validate](https://html-validate.org/), ESLint, [Stylelint](https://stylelint.io/) (`stylelint-config-standard`) and Prettier. Node 20.19+ on 20.x, or 22.12+.
+
+```bash
+npm ci --prefix ui
+npm run lint --prefix ui
+npm test --prefix ui
+npm run format --prefix ui   # apply Prettier
+```
+
+`npm test` runs [Vitest](https://vitest.dev/) in jsdom: each test loads the real `index.html`, imports the UI modules, and drives them against a fake robot that stubs `fetch` and records requests ([`ui/test/robot.js`](../ui/test/robot.js)). The tests cover the auth gate, config saving and access-token handling, the servo page range hint, and the setup wizard (step order, what each step saves, step-only calibration moves, LED order validation).
+
 ## Packages
 
 Node 18+. No robot.

partitions.csv

@@ -1,6 +1,6 @@
 # Name,   Type, SubType, Offset,  Size, Flags
 # 4MB: one app slot (USB flash, no OTA). Dual 0x150000 OTA apps overflowed
-# the firmware (~1.38MB HTML UI). LittleFS is ~1.81MB so a mod can replace
+# the firmware (~1.3MB). LittleFS is ~1.81MB so a mod can replace
 # some WAVs with longer clips and keep the stock files it does not ship.
 # NVS stays at 0x9000. spiffs moved; reflash app + filesystem together.
 nvs,      data, nvs,     0x9000,  0x5000,

scripts/audio_pack.py

@@ -275,16 +275,16 @@ def pack_audio(assets_dir, dest_dir, partition_bytes, mod_dir=None):
 
     total = sum(
         path.stat().st_size
-        for path in dest_dir.iterdir()
+        for path in dest_dir.rglob("*")
         if path.is_file()
     )
     limit = partition_bytes - HEADROOM_BYTES
     if total > limit:
         raise AudioPackError(
-            f"Audio image is {total} bytes; "
+            f"Filesystem image is {total} bytes; "
             f"spiffs allows {limit} after {HEADROOM_BYTES} bytes headroom"
         )
-    print(f"Audio image {total} bytes (limit {limit})")
+    print(f"Filesystem image {total} bytes (limit {limit})")
 
 
 def _overlay_mod(mod_dir, dest_dir):

scripts/copy_assets.py

@@ -9,6 +9,7 @@
     sys.path.insert(0, str(scripts_dir))
 
 from audio_pack import pack_audio, spiffs_size_bytes, validate_mod_name
+from ui_pack import build_ui, pack_ui
 
 mod_name = env.GetProjectOption("custom_audio_mod", "")
 mod_name = "" if mod_name is None else str(mod_name).strip()
@@ -18,6 +19,9 @@
     mod_dir = project_dir / "mods" / mod_name / "assets"
     print(f"Audio mod overlay: {mod_name}")
 
+# Before pack_audio so its size check covers the UI files too.
+pack_ui(build_ui(project_dir / "ui"), project_dir / "data" / "ui", env["TE_FW_VERSION"])
+
 pack_audio(
     project_dir / "assets",
     project_dir / "data",

scripts/firmware_version.py

@@ -35,3 +35,5 @@ def _sanitize(raw: str) -> str:
 version = _sanitize(_git_describe(project_dir))
 print(f"Firmware version: {version}")
 env.Append(CPPDEFINES=[("FW_VERSION", '\\"%s\\"' % version)])
+# copy_assets.py stamps the web UI with the same string so the firmware can detect a mismatched filesystem.
+env.Replace(TE_FW_VERSION=version)

scripts/ota.py

@@ -2,10 +2,15 @@
 
 import os
 import subprocess
+import time
+import urllib.error
+import urllib.request
 from pathlib import Path
 from urllib.parse import urlparse
 
 DEFAULT_HOST = "tiny-engineer.local"
+REBOOT_TIMEOUT_S = 90
+FIRMWARE_ATTEMPTS = 3
 
 
 def ota_host():
@@ -15,7 +20,7 @@ def ota_host():
     return host or DEFAULT_HOST
 
 
-def espota(image, filesystem):
+def espota(image, filesystem, check=True):
     command = [
         env.subst("$PYTHONEXE"),
         str(Path(env.PioPlatform().get_package_dir("framework-arduinoespressif32")) / "tools" / "espota.py"),
@@ -33,29 +38,59 @@ def espota(image, filesystem):
         command.append("--spiffs")
 
     print(f"OTA {'filesystem' if filesystem else 'firmware'} -> {ota_host()}")
-    subprocess.run(command, check=True)
+    return subprocess.run(command, check=check).returncode == 0
 
 
-def upload_firmware(source, target, env):
-    espota(env.subst("$BUILD_DIR/${PROGNAME}.bin"), filesystem=False)
+def wait_for_reboot():
+    # The robot restarts after an OTA write; any HTTP answer (even 401) means it is back.
+    time.sleep(5)
+    deadline = time.monotonic() + REBOOT_TIMEOUT_S
 
+    while time.monotonic() < deadline:
+        try:
+            urllib.request.urlopen(f"http://{ota_host()}/health", timeout=3)
+            return
+        except urllib.error.HTTPError:
+            return
+        except OSError:
+            time.sleep(2)
 
-def upload_filesystem(source, target, env):
+    raise RuntimeError(f"{ota_host()} did not come back within {REBOOT_TIMEOUT_S} s")
+
+
+def build_filesystem():
     project_dir = env.subst("$PROJECT_DIR")
     # The platform only wires up the LittleFS image builder when buildfs is a command-line target.
     subprocess.run(
         [env.subst("$PYTHONEXE"), "-m", "platformio", "run", "-t", "buildfs", "-e", env.subst("$PIOENV"), "-d", project_dir],
         check=True,
     )
-    espota(env.subst("$BUILD_DIR/${ESP32_FS_IMAGE_NAME}.bin"), filesystem=True)
+    return env.subst("$BUILD_DIR/${ESP32_FS_IMAGE_NAME}.bin")
+
+
+def upload_release(source, target, env):
+    # Filesystem first: until the firmware follows, the robot keeps its old firmware and the
+    # web UI refuses to load on the version mismatch instead of calling an older API.
+    espota(build_filesystem(), filesystem=True)
+    wait_for_reboot()
+
+    # The OTA listener starts just after the HTTP server, so the first attempt can be early.
+    for attempt in range(1, FIRMWARE_ATTEMPTS + 1):
+        if espota(env.subst("$BUILD_DIR/${PROGNAME}.bin"), filesystem=False, check=attempt == FIRMWARE_ATTEMPTS):
+            return
+        time.sleep(3)
+
+
+def upload_filesystem(source, target, env):
+    espota(build_filesystem(), filesystem=True)
 
 
 env.AddCustomTarget(
     name="ota",
     dependencies="$BUILD_DIR/${PROGNAME}.bin",
-    actions=upload_firmware,
+    actions=upload_release,
     title="Upload OTA",
-    description="Upload firmware over Wi-Fi",
+    description="Upload filesystem, then firmware, over Wi-Fi",
 )
 
 env.AddCustomTarget(