refactor(http): rewrite the web UI in TypeScript and Preact, clean up the firmware HTTP layer

.cursor/rules/sync-api-endpoints.mdc

@@ -1,18 +1,18 @@
 ---
-description: When HTTP routes change, update the HTML index page and API docs together.
+description: When HTTP routes change, update the web UI API page and API docs together.
 globs: src/http/**/*
 alwaysApply: false
 ---
 
 # Sync HTTP endpoints across firmware and docs
 
-When adding, removing, or changing the method, path, or query parameters of any HTTP route, update all of the following in the same change:
+When adding, removing, or changing the method, path, or parameters of any HTTP route, update all of the following in the same change:
 
-1. **HTML index** — [`src/http/index_page.cpp`](src/http/index_page.cpp): main endpoint table matches all routes; parameter sections for `/anim`, `/settings`, and `/test/servo` list every supported value and range
+1. **Web UI API page** — [`ui/src/views/ApiReference.tsx`](ui/src/views/ApiReference.tsx): main endpoint table matches all routes; parameter sections for `/anim`, `/settings`, and `/test/servo` list every supported value and range
 2. **API reference** — [`docs/api.md`](docs/api.md): full section per endpoint (curl, JSON, params, errors)
 3. **Summaries** — if the endpoint list, params, or boot URLs changed, also update [`README.md`](README.md) and [`docs/hardware/testing.md`](docs/hardware/testing.md)
-4. **405 paths** — if new `/test/*` or similar paths get wrong-method handling, update `isHttpTestPath()` in [`src/http/test_handlers.cpp`](src/http/test_handlers.cpp) and [`handleNotFound`](src/http/routes.cpp) as needed
+4. **Route table** — add the route to `kRoutes` in [`src/http/routes.cpp`](src/http/routes.cpp) with its access rule. 404 and 405 answers come from that table
 
-Do not duplicate long behavioral docs (animation behavior tables, RGB LED) in the HTML index — one-line route descriptions only, except the supported-parameter lists for `/anim`, `/settings`, and `/test/servo`.
+Do not duplicate long behavioral docs (animation behavior tables, RGB LED) in the web UI API page — one-line route descriptions only, except the supported-parameter lists for `/anim`, `/settings`, and `/test/servo`.
 
-Parameter values in the HTML index must match [`docs/api.md`](docs/api.md) exactly.
+Parameter values in the web UI API page must match [`docs/api.md`](docs/api.md) exactly.

.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-cli` / `…/tiny-engineer-cursor` / `…/tiny-engineer-antigravity` / `…/tiny-engineer-claude-code` when that package changed
-- [ ] HTTP: HTML index (`ui/index.html`) + `docs/api.md` (and README / `docs/hardware/testing.md` if the route list changed)
+- [ ] HTTP: web UI API page (`ui/src/views/ApiReference.tsx`) + `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

AGENTS.md

@@ -11,7 +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 it into one minified page and embeds it gzipped in the firmware |
+| `ui/` | Web control panel (Vite, TypeScript, Preact); `pio run` builds it into one minified page and embeds it gzipped in the firmware |
 | `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) |
@@ -55,12 +55,12 @@ 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** — [`ui/index.html`](ui/index.html): endpoint table and param lists for `/anim`, `/settings`, `/test/servo`
+1. **Web UI API page** — [`ui/src/views/ApiReference.tsx`](ui/src/views/ApiReference.tsx): 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/`
+4. **Route table** — add the route to `kRoutes` in [`src/http/routes.cpp`](src/http/routes.cpp) with its access rule. 404 and 405 answers come from that table
 
-HTML index: one-line route descriptions only (except supported-parameter lists). Param values must match `docs/api.md` exactly.
+Web UI API page: one-line route descriptions only (except supported-parameter lists). Param values must match `docs/api.md` exactly.
 
 ## Commits
 
@@ -76,6 +76,8 @@ Breaking rules, SemVer mapping, and examples: [CONTRIBUTING.md](CONTRIBUTING.md)
 
 - **Firmware** — `pio run`; also `pio test -e native` when touching settings validation. Pin changes update `include/pins.h` **and** `docs/hardware/` together.
 - **Settings** — layer checklist in [docs/settings.md](docs/settings.md). Never log raw `access_token`.
+- **HTTP routes** — add the route to `kRoutes` in `src/http/routes.cpp` with its `Access` level; `Refusal::check` enforces it. Routes with fields read a JSON body through `readJsonBody`; only `POST /anim` (`name`) and `/play` take other input, because the agent packages depend on them.
+- **Web UI** — Preact + TypeScript in `ui/src`, plain `preact` / `preact/hooks` imports (no compat). One component per file; shared components in `ui/src/components`, helpers in `ui/src/lib`. `npm run lint --prefix ui` runs `tsc` and type-checked ESLint, which forbids `.then` / `.catch` chains (use try/catch). Keep markup and class names when refactoring: the CSS styles them by class and id.
 - **Integrations** — add/extend package tests; prefer short timeouts and ignore network errors so a missing robot does not stall the agent.
 - **CAD** — edit `.f3d` **and** export affected `3mf`. CERN-OHL-S. Do not swap `AiEmblem.3mf` as branding. New parts: [docs/3d/adding-parts.md](docs/3d/adding-parts.md).
 - **Mods** — optional add-ons under `mods/<mod_name>/`. Models live in `3d_models/{cad,parts}/`. Commit `type(mods)` and name the mod in the summary. `feat(mods)` / `fix(mods)` do not version stock CAD. See [mods/README.md](mods/README.md).

CONTRIBUTING.md

@@ -60,7 +60,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 ([`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).
+**HTTP / API.** Same PR must update the web UI API page ([`ui/src/views/ApiReference.tsx`](ui/src/views/ApiReference.tsx)) 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).