Write the web front end's shared half once

[theAndreas]

Stage A+B of lifting the web front end into firmware/. Routes, asset serving and dispatch (C) and the simulator's transport (D) are deliberately not here.

What was wrong

The front end was written for the ESP32 and copied to the RP2350. handleCommands was byte-identical in both, comments included; so were toUtf8, handleDisplay's body, broadcastLine's UTF-8 widening, and broadcastFrame's rate limit / gather / compare. ChunkWriter — the thing that already separated what is written from where it goes — was defined twice.

The risk that made this worth doing is not tidiness. Both pages parse the catalog JSON, and each web_test.cpp asserts on the bytes its own route wrote, never on what a page makes of them. A divergence between two hand-maintained generators would have surfaced in a browser and nowhere else.

The seam

No new abstraction style: the repo's existing contract is a header the core reaches by name, provided per platform, with concrete types — Pixels.h, Storage.h, System.h. WebTransport.h joins that table in platform/avr-dx/README.md.

Two implementation findings changed the shape from the approved plan, both for the better:

• WebTransport.h names no framework type by value. It cannot: the firmware includes it and cannot promise the include order each backend's Arduino.h needs. It forward-declares struct httpd_req / AsyncWebServerRequest instead. This also dodged a trap — httpd_handle_t is void* in the IDF but struct httpd_t* in the test stub, so a handle in that header would not have compiled against both.
• No WebTransport.cpp was needed. Both classes are defined inside each WebInterface.cpp, beside the server handle and client table they reach. Two fewer files than planned.

What stays per backend

Starting a server, registering routes, the password (the ESP32 decodes the header itself because its core cannot decode base64; the RP2350 lets its library compare), and the update — a spare partition on one, a file plus a PicoOTA command page on the other.

Line count, honestly

Roughly neutral, not a win: 832 code lines across the two backends become 639 there, plus 195 in the firmware and 114 of seam. I estimated "~250 duplicated lines gone" when proposing this; that was true of the duplication but not of the total, because the seam costs about what the duplication saved. The win is one generator instead of two, and the seam stages C/D need. The line deletion comes in D, when serve.js (226 lines), webhost.cpp (145) and the faked httpd_* layer go.

Verified

• All four targets build warning-free — simulator, avr-dx, esp32, rp2350.
• The AVR-Dx image is byte-identical to master: 48078 / 1700. WebFrontend.cpp is compiled there (the .obj exists) and guarded to nothing — that identity is what proves WEB_FRONTEND_SUPPORT does not leak.
• Both host suites pass, -Wall -Wextra -Werror.
• tools/documented-sizes.py --elf … --rp2350-elf … passes, all four checks.
• The panel was driven in a real browser against the rebuilt firmware: 14 of 111 cells lit, plate reading "ES IST HALB ZWÖLF", time 11:31, brightness 255 read back over the socket, no console errors.

One structural consequence worth knowing: WebFrontend.cpp is excluded from the CORE glob in both run.sh and picked up with the backend's own web source, because serial_test and ds3231_test deliberately do not link WebInterface.cpp — the same split those files already made.

Two pre-existing finds fixed in passing

• WEB_INTERFACE_MAX_CLIENTS on the RP2350 sized a constant nothing read — AsyncWebSocket owns the list. Removed rather than left documenting a limit nothing enforces.
• The two macros that moved are WEB_FRONTEND_* now, after the module that owns them.

One find NOT fixed here

platform/esp32/README.md contradicts itself and is stale: its "Verification status" block says Flash: 17.5% of 3.2 MB (≈585 KB) while the same file's "Which ESP32 this needs" says "the image is about 1.05 MB" — and the build reports 1 100 421 bytes, i.e. 32.9%. RAM likewise reads 10.8% against an actual 15.9%. This predates this branch by a wide margin (nothing here adds 500 KB) and the ESP32's figures are the ones documented-sizes.py does not check. Left alone deliberately — it is a separate change, and it suggests the script should grow an ESP32 check rather than the line being hand-corrected again.

🤖 Generated with Claude Code