frugal-iot-client 1.3.13 → 1.3.14

package/CLAUDE.md

@@ -2,11 +2,34 @@
 
 JavaScript/Web Components MQTT client for the Frugal IoT project. Connects to an MQTT broker, auto-discovers nodes via discovery messages, and renders live sensor data using custom HTML elements.
 
-## Main file
+## Modules
 
-`webcomponents.js` — the entire client lives here (~3600 lines). All web components, MQTT logic, graphing, i18n, and admin UI are defined in this one file.
+The client was one file; it is now split. `core.js` imports none of the others — that is what keeps
+it loadable on its own, and it is maintained by reaching the display elements **by tag name**
+(`el('mqtt-bar', …)`), never by importing their classes.
 
-Dashboards (e.g. `dashboard_example2.html`) are thin HTML pages that import selectively from `webcomponents.js`.
+| File | Imports | Holds |
+|---|---|---|
+| `core.js` | none | MQTT plumbing, the `MqttTopic*` data tree, `Watchdog`, i18n and `el`, `server_config`, `MqttClient`, `MqttWrapper` |
+| `widgets.js` | core | `mqtt-bar`, `mqtt-text`, `mqtt-toggle`, `mqtt-gauge`, `mqtt-slider`, `mqtt-color`, `mqtt-choosetopic` — all shadow DOM |
+| `graph.js` | core, widgets | `mqtt-graph`, `mqtt-graphdataset` — pulls Chart.js |
+| `cards.js` | core | the card UI: `mqtt-devicecard`, `mqtt-devicegrid`, `mqtt-projectback`, `mqtt-dashboard`, the layout store |
+| `nodeview.js` | core, widgets | the old node/group UI — **retires with `index-old.html`**; nothing new belongs here |
+| `flash.js` | core | `mqtt-flash` — pulls esptool-js |
+| `admin.js` | core | `mqtt-admin`, `mqtt-login`, `tabbed-display` |
+
+Entry points: `index.html` → `dashboard.js` (the card UI, everything but `nodeview.js`);
+`index-old.html` → `webcomponents.js` (everything, and the only remaining user of it);
+`index-embedded.html` needs only `core.js` + `widgets.js` and must keep working.
+
+Dashboards (e.g. `dashboard_example.html`) are thin HTML pages importing selectively.
+
+## Design documents
+
+`CARDS_UX.md` is the design for the card UI — every decision is numbered (D-n) with its reasoning,
+deferred work is L-n, and it is the place to argue with a choice rather than re-deciding it in code.
+`CARDS_PLAN.md` is how it was built, including the bugs found on the way. `FLASH_PLAN.md` and
+`HEADLESS_PLAN.md` cover their own areas.
 
 ## Code style
 
@@ -17,7 +40,13 @@ Dashboards (e.g. `dashboard_example2.html`) are thin HTML pages that import sele
   - Bad: `// Check if topic starts with the set path`
 - **No trailing summaries** — do not add a comment block or prose after a method explaining what it does.
 - **Getters**: prefer `get foo()` over plain property access whenever a value is derived or retrieved by traversing connected objects (e.g. `this.node.project`, `this.parentElement`, `this.mt.node.groups[this.group]`). Getters make the dependency chain explicit and let callers read `thing.project` naturally.
-- **Dashboard functionality**: prefer adding reusable behaviour to `webcomponents.js` over implementing it inside a custom dashboard file. If a dashboard needs to traverse the topic tree, compute a list, or fire an event, that logic belongs on the relevant class as a getter or method.
+- **Dashboard functionality**: prefer adding reusable behaviour to the shared modules over implementing it inside a custom dashboard file. If a dashboard needs to traverse the topic tree, compute a list, or fire an event, that logic belongs on the relevant class as a getter or method.
+- **A view must not walk the tree.** The cards read `nodeMt.frontRows`, `.summaryChips`, `.status`,
+  `mt.formatted` — resolved values, computed once on the data tree and testable with no DOM. A card
+  that starts iterating groups and topics has had logic put in the wrong place.
+- **One gate, asked once.** `mt.canWrite` is checked in `renderMaybeWired` — the single point where
+  every widget decides between an input and a display — so a control cannot end up editable on one
+  screen and read-only on another. Resist per-widget permission checks.
 
 ---
 
@@ -86,11 +115,17 @@ Helper functions: `topicTwig(path)` → twig, `topicLeaf(path)` → leaf, `twigA
 
 Data-tree classes are always instantiated. UI element classes are only instantiated when not in headless mode.
 
-**Data-tree** (plain JS, no HTMLElement):
+**Data-tree** (plain JS, no HTMLElement, all in `core.js`). This is where derived values live, and
+it works with no DOM at all — which is what lets the cards run headless and be tested without a
+browser.
 ```
-MqttTopic          leaf data node — history, metadata, subscribe/publish logic
-  (future: MqttTopicProject → MqttTopicNode → MqttTopicGroup, see HEADLESS_PLAN.md)
-Watchdog           offline detection timer per node
+MqttTopic            leaf data node — history, metadata, subscribe/publish, formatted, canWrite
+  MqttTopicGroup     one module on a node — summaryText/summaryShort roll up here, not on the element
+    MqttTopicGroupRelay / …Ota / …ControlHysteresis   only where a reading list is the wrong shape
+  MqttTopicProject   discovery; nodes
+  MqttTopicNode      status, deviceConfig, frontRows, summaryChips — what a card reads
+Watchdog             offline detection timer per node (old UI only; the data tree derives status
+                     from message arrival instead, with no timer)
 ```
 
 **UI elements** (extend HTMLElementExtended):
@@ -140,16 +175,32 @@ HTMLElementExtended          (from html-element-extended)
 
 ### Adding a new group summary
 
-1. Extend `MqttSummaryGroup`.
-2. Declare `static get observedAttributes()` and the matching type arrays (`floatAttributes`, `boolAttributes`, etc.).
-3. Implement `summaryText()` returning a short string.
-4. Register as `mqtt-group<groupid>` — `MqttNode.addGroupFromTemplate` will pick it up automatically.
+Usually nothing to do: `MqttTopicGroup.summaryText()` already returns the module's own readings,
+formatted by the schema and capped at two, which suits 26 of the 33 modules. Write a subclass only
+when a list of readings is the wrong shape — `relay` wants its name beside a tick, `ota` shows a key,
+a control shows a rule. Then:
+
+1. Extend `MqttTopicGroup` in **`core.js`** (not the element — a card has no elements to ask).
+2. Implement `summaryText()`, and `summaryShort()` too if the chip form differs from the row form.
+3. Add it to `topicGroupClasses`, keyed by module id.
+
+### The card UI
+
+- `mqtt-devicecard` and `mqtt-devicegrid` are **light DOM** (`HTMLElementExtendedMinimum`), so
+  `frugaliot.css` reaches them directly. That needs html-element-extended ≥ 0.1.7 (`renderRoot`).
+- A light-DOM element has no `<slot>`, and `renderAndReplace` **clears its own children** — so the
+  grid renders once with `render0()` and mutates in place, and a card builds every child itself.
+- Widgets in a card are pre-bound (`el.mt = mt`) but deliberately **not** registered as `mt.element`:
+  only one element may hold that, and binding would have a card competing with a graph, a second
+  card, or the old UI for the same topic. The card pushes values into its own children instead.
+- Which readings a device shows comes from `config.d/schema/devices.yaml`, keyed by OTA key and
+  matched by prefix. `nodeMt.deviceConfig` resolves it.
 
 ---
 
 ## Headless mode
 
-`<mqtt-wrapper headless>` builds the full data tree without creating any DOM elements for the project/node/group/leaf UX. Dashboards subscribe to document events and create individual standalone elements on demand.
+`<mqtt-wrapper headless>` builds the full data tree without creating any DOM elements for the project/node/group/leaf UX. Dashboards subscribe to document events and create individual standalone elements on demand. **The card UI runs this way** — `index.html` uses a headless wrapper for the connection, the selectors and the tree, and the cards render from it. So headless is the main path now, not a special case for custom dashboards, and anything that only works with `this.element` set is broken for the primary UI.
 
 Key points for `MqttTopic.message_received` headless path (the `else` branch when `this.element` is null):
 - Must set `this.state.value` so that getters like `usableName` and `wiredTopic` work without a DOM element.
@@ -196,7 +247,65 @@ const mt = document.querySelector('mqtt-wrapper')?.projectMt?.findTopic(this.sta
 |---|---|---|---|
 | `frugaliot:controlgroup` | `MqttGroupControlHysteresis` | `{ nodeMt, groupId, topics }` | populate node/group dropdowns |
 | `frugaliot:groupchanged` | `MqttTopic.message_received` (headless) | `{ nodeMt, groupId, groupMt, changed }` | re-run `wireUpDashboard` on wired/on state changes |
-| `frugaliot:topicschanged` | `MqttProject` | `{ project }` | retry wiring after late-arriving nodes |
+| `frugaliot:topicschanged` | `MqttProject`, `MqttTopicProject.addNode` | `{ project }` | retry wiring, and add a card, after late-arriving nodes |
+| `frugaliot:projectchanged` | `MqttWrapper.addProject` | `{ projectMt, organization, project }` | a project now exists — `topicschanged` is too late, it needs a node |
+| `frugaliot:organizationchanged` | `MqttWrapper.onOrganization` | `{ organization }` | capabilities are per organization, so this precedes any project |
+| `frugaliot:cardmove` / `cardmoveover` | `mqtt-devicecard` | `{ nodeId, delta }` / `{ nodeId, targetNodeId }` | the card asks to be moved; the grid decides what that means |
+| `frugaliot:cardmode` | `mqtt-devicecard` | `{ nodeId, mode }` | so the grid can remember what was open |
+
+---
+
+## Traps
+
+Each of these cost real time. They are not obvious from reading the code.
+
+- **A page stylesheet cannot reach inside a shadow root.** `frugaliot.css` is loaded *into* each
+  shadow root as well as onto the page, so `.mqtt-text input` works from within but
+  `.fi-when input` (a light-DOM ancestor) never matches. **Custom properties are the only thing that
+  crosses the boundary** — set `--fi-…` outside, read it in a rule that lives inside.
+- **`el()` assigns only `onclick`, `onchange` and `onsubmit`** (plus `textContent`, `style`,
+  `innerHTML`, `action`) as properties. **Any other function is silently put in `el.state`** and
+  never wired up: `el({onpointerdown: fn})` does nothing at all. Use `addEventListener`.
+- **`@media (max-width: 1001px)` in `frugaliot.css`** inflates fonts and icons for the node/group UI,
+  where a node is one wide block. Inside a card it makes everything wider than the card. Those rules
+  read `var(--fi-chrome-font, …)`; the card page sets it to `1rem`. Anything new that is not
+  `nodeview.js` should opt out the same way. Replace them properly when `nodeview.js` goes.
+- **`:host-context(details[open]) div { display: block }`** near the top of `frugaliot.css` has
+  specificity (0,2,2) and overrides most rules for any div in a shadow root inside an open
+  `<details>` — which is every widget in the old UI.
+- **Assets resolve against the module, not the document**: `CssUrl` and `ImagesUrl` use
+  `import.meta.url`, or a page in a subdirectory 404s every stylesheet and icon.
+- **Timestamps go through `nowMs()`**, never `Date.now()`, or a replayed history collapses onto one
+  instant and a graph has nothing to draw. `setClock()` is how tests decide what "now" is.
+- **Caching will lie to you.** `/node_modules` and the client directory are served
+  `immutable, max-age=86400`, *and* `frugal-iot-server/public/service-worker.js` caches the libraries
+  cache-first at scope `/`. A stale library shows up as a null `append` inside `renderAndReplace`.
+  Devtools "disable cache" does not stop a service worker: unregister it.
+- **Schema is mastered in `frugal-iot-server/config.d/schema/`.** Edit there, then
+  `scripts/copy-schema-to-examples.zsh`; `scripts/check-schema.js` verifies. Never edit a copy.
+
+---
+
+## Testing
+
+`npm test` runs `node --test` over `test/*.test.js` — no browser, no broker. `test/setup.js` supplies
+a jsdom DOM, an in-memory `localStorage`, and a resolve hook for the client's `/node_modules/…`
+imports.
+
+Messages are injected with `mqtt_deliver`, the same call the real client makes for every message, so
+scenarios in `test/mock.js` drive the whole tree with nothing mocked below it. **`test/mock.html`
+(served at `/dashboard/test/mock.html`) replays those scenarios in a browser** — pick one, switch
+between the card UI, the old UI and the data tree, and see the messages that produced it.
+
+Two lessons worth keeping:
+
+- **Calling a handler directly does not test that it is wired.** `card.onPointerDown(...)` passed
+  against code that was never connected to the DOM. Dispatch real events.
+- **Shadow content is not in `textContent` and not reachable by `card.querySelector`.** A test
+  asserting `querySelector('mqtt-choosetopic')` is null passes whether or not the chooser exists.
+
+Snapshots in `test/snapshots/` record the rendered tree of both UIs. They exist so the old UI cannot
+regress unnoticed; regenerate deliberately with `npm run test:update` and read the diff.
 
 ---
 
@@ -248,6 +357,11 @@ When adding a new UI string: add matching entries to all four language sections
 
 ## Running locally
 
+The card UI is `index.html`, served at `/dashboard/`. The node/group UI it replaced is
+`index-old.html`, linked from the project's home page. `frugal-iot-server` must be running: it serves
+`/config.json`, `/node_modules`, the OTA files and the login flow, so the client cannot be opened as
+a file.
+
 ```bash
 npm install
 # run frugal-iot-server pointing htmldir at this directory

package/FLASH_PLAN.md

@@ -113,9 +113,16 @@ Flash mode (`qio` vs `dio`) is **not detectable** from the chip, and the bootloa
 `dio` works on every board (`qio` is merely faster), so shipping only the `dio_80m` bootloader
 removes the variable entirely.
 
-Pass `flashSize: "detect"` (a legal `FlashSizeValues` member) and let esptool-js patch the bootloader
-header from the real chip, rather than threading a detected string through for that purpose. The
-capacity byte is still read separately, to *choose the partition table*.
+Pass `flashSize` as the **literal detected size string** (`"4MB"`), not `"detect"`. `"detect"` is a
+legal `FlashSizeValues` member but *not* on this code path: `writeFlash` calls `flashSizeBytes()`,
+which only parses `"KB"`/`"MB"` substrings and returns `-1` for anything else. Every file then fails
+`data.length + address > -1`, so `writeFlash` throws `File 1 doesn't fit in the available flash`
+before erasing or writing a single byte — a silent-looking failure with no board activity at all.
+(`parseFlashSizeArg()` would likewise reject it, since `chip.FLASH_SIZES` only has `1MB`…`128MB`.)
+
+Passing the real size is better than the other legal option, `"keep"`: `"keep"` skips the bounds check
+entirely, whereas a literal size both patches the header correctly and gives a free
+does-it-fit-in-flash guard on top of our own app-partition check.
 
 Pass **`flashMode: "keep"` and `flashFreq: "keep"`** rather than naming `dio`/`80m` explicitly. The
 shipped bootloaders are already built `dio_80m`, so `keep` preserves exactly the intended settings —
@@ -549,6 +556,94 @@ an iframe, the *parent* page needs `allow="serial"` on the iframe.
 | 4 | ⚡ on the OTA file list — flash a server-hosted binary | `/ota_get` route | built |
 | 5 | *(optional)* serial config hand-off, needs a firmware addition | none | not started |
 
+### The bootloader must come from the same framework as the firmware
+
+**This was the root cause of a long debug and is the single most important thing on this page.**
+
+Base bootloaders must be generated from the framework the firmware is *built against*, not from
+whatever ESP32 core happens to be installed. Frugal IoT builds with **pioarduino's**
+platform-espressif32, so:
+
+```bash
+esptool --chip esp32c3 elf2image --flash-mode dio --flash-freq 80m --flash-size 4MB \
+  -o base/bootloader/esp32c3.bin \
+  ~/.platformio/packages/framework-arduinoespressif32-libs/esp32c3/bin/bootloader_qio_80m.elf
+```
+
+Note it is the **`qio_80m` ELF with the header patched to DIO** — that is what pioarduino does, and the
+result is byte-identical to `.pio/build/<env>/bootloader.bin`. The Arduino IDE core's `dio_80m` ELF
+produces a *different* binary (18688 vs 19520 bytes) which does not work.
+
+**The symptom is deeply misleading.** With a mismatched bootloader the board boots, the app runs, and
+sensors, WiFi scanning and MQTT queuing all work — but LittleFS fails:
+
+```
+E esp_littlefs: lfs.c:1383:error: Corrupted dir pair at {0x0, 0x1}
+E esp_littlefs: mount failed,  (-84)
+E [LittleFS.cpp:107] format(): Formatting LittleFS failed! Error: -1
+```
+
+Nothing points at the bootloader. Hours went into littlefs disk formats before spotting it.
+
+**The diagnostic that finds it in seconds:** compare the ROM banner's second-stage loader sizes
+between a known-good IDE flash and one of ours.
+
+| | |
+|---|---|
+| after an IDE flash (works) | `load:0x3fcd5820,len:0x110c` `len:0xb54` `len:0x2f8c` |
+| after ours, wrong bootloader | `load:0x3fcd5820,len:0x1010` `len:0x9f4` `len:0x2ea4` |
+
+Different lengths mean different bootloaders. Always check this first when a provisioned board
+misbehaves in any way.
+
+### The filesystem partition is left erased — the firmware formats it
+
+Provisioning writes **four** regions (bootloader, partition table, otadata, app) and deliberately does
+*not* touch the filesystem partition. `LittleFS.begin(true)` formats it on first boot, and the log
+reads:
+
+```
+LittleFS E esp_littlefs: ... Corrupted dir pair at {0x0, 0x1}   <- expected, partition is erased
+E esp_littlefs: mount failed,  (-84)                             <- expected
+[E] disableCore0WDT()                                            <- format() running
+initialization done.                                             <- formatted and mounted
+Creating:/frugal_iot ... Creating:/mqtt                          <- directories created
+```
+
+Those first two error lines are normal on a freshly provisioned board and are **not** a fault.
+
+This was not obvious. An earlier iteration shipped pre-formatted blank images because `format()` was
+failing with `-1` — but that turned out to be the bootloader mismatch above, and once the bootloader
+was right the firmware formatted its own partition without help. The machinery was removed. Recorded
+in case it is ever needed again (an **ESP8266** would need it, since its `ESPFS.begin()` takes no
+format-on-fail argument):
+
+- pioarduino's builder uses **`littlefs-python`**, not `mklittlefs`, with
+  `read_size=1, prog_size=1, cache_size=block_size, lookahead_size=32, block_cycles=500, name_max=64,
+  disk_version=2.1`. `prog_size=1` is the critical one — other tools pad metadata commits to 128 or
+  256 bytes, whose CRCs then fail to validate and produce `Corrupted dir pair`.
+- `mklittlefs` 0.2.3 emits disk 2.0 with 256-byte padding; `@wasm-os/mklfs` 0.1.0 emits disk 2.1 but
+  `name_max` 255, over `CONFIG_LITTLEFS_OBJ_NAME_LEN=64`, with no wasm export to change it. **Neither
+  produces a mountable image.**
+- A blank filesystem is 8 KB whatever the partition size — only the superblock pair has content.
+
+### Other bring-up fixes worth remembering
+
+- **`flashSize` must be a literal size string.** `writeFlash`'s `flashSizeBytes()` only parses
+  `"KB"`/`"MB"`; `'detect'` becomes `-1` and every file fails its fits-in-flash check, throwing before
+  a single byte is written.
+- **Never let a failed diagnostic read default to erasing.** `deviceInspect` originally treated an
+  unreadable board as "needs provisioning", which silently erased a working board.
+- **`readFlash` waits `FLASH_READ_TIMEOUT` = 100 s** for its first packet. Bound every read or Connect
+  appears to hang.
+- **`eraseAll` is silently ignored unless the stub is running** (`IS_STUB && eraseAll`).
+- **`base/` is served `immutable, maxAge: 1 day`.** `boards.json` must be fetched with
+  `cache: 'no-cache'` and the part binaries cache-busted with its `version`, or edits are invisible
+  for a day and you debug a stale manifest.
+- **Verify writes before resetting.** Provisioning reads the partition table back and reports whether
+  it matches. Reading the *filesystem* back after a boot is useless — the app rewrites block 0 on its
+  first mount attempt, so a post-boot readback never shows what was written. That trap cost real time.
+
 ### What is verified, and what still needs a board
 
 Verified without hardware: partition tables round-trip to the intended geometry (app slot identical in
@@ -557,15 +652,161 @@ files, of erased flash, and of garbage; littlefs superblock detection; `imageChi
 internally consistent and every referenced file present; base files served correctly at
 `/dashboard/base/...` and byte-identical over HTTP; `/ota_get` returns 401 unauthenticated.
 
-**Everything that touches a board is untested** — `writeFlash`, the provision/app-only read-back,
-`after("hard_reset")`, and the boot-log reopen have never run against real silicon. Treat the first
-run as a bring-up exercise, ideally on a board you are willing to re-flash over USB by other means.
-The specific things most likely to need adjustment:
+Confirmed on hardware (ESP32-C3, 4 MB): ⚡ selects a server-hosted binary; `Connect board` resolves it
+to `4MB (min_spiffs)`; **app-only flash writes and verifies** — 1365808 bytes (828304 compressed) at
+`0x10000` in 10.8 s, followed by a successful hard reset. `calculateMD5Hash` being omitted is fine —
+`writeFlash` skips verification without complaint.
+
+Three bugs fixed during bring-up:
+
+1. `flashSize: "detect"` made `writeFlash` throw before touching the board (see above).
+2. Any flash attempt releases the loader, so the Flash button correctly stayed disabled but gave no
+   visible reason. Errors now render in the status area with a "reconnect" prompt.
+3. The boot log was hard-coded to 115200 and its read loop could not time out. `reader.read()` never
+   resolves on a silent port and the `while (Date.now() < deadline)` condition is only tested
+   *between* reads, so a quiet board hung the whole operation with no closing marker. The loop now
+   races each read against the deadline, always terminates, and says why it saw nothing.
+
+### Serial monitor
+
+The log is a real monitor, not a fixed capture: it streams until **Stop monitor** is pressed. The
+original 25-second window turned out to be an arbitrary cutoff that ended a working log mid-stream,
+so the timeout now covers only the case where *nothing at all* arrives — once the first byte lands,
+plain `read()` runs indefinitely and `monitorStop()` settles the pending read with `cancel()`, so no
+polling is involved.
+
+`Monitor` also works standalone, requesting a port if none is held, so a running board can be watched
+without flashing it. It is stopped before `Connect` since esptool cannot open a port the monitor holds.
+
+### Serial monitor speed
+
+frugal-iot's `startSerial()` picks the rate by toolchain, so the boot log needs a selector rather
+than a constant:
+
+| Build | Rate |
+|---|---|
+| PlatformIO | `SERIAL_BAUD`, default **460800** |
+| Arduino IDE | **115200** |
+| ESP8266 ROM boot messages | 74880 |
+
+Two further reasons a boot log can be legitimately empty, both reported in the log rather than left
+mysterious: the firmware only prints when built with **`ANY_DEBUG`**, and `startSerial()` deliberately
+waits 5 s before its first line (hence a 25 s capture window).
 
-- whether `writeFlash` tolerates the omitted `calculateMD5Hash` (see Client change 7)
+**Full provisioning is confirmed working** on an ESP32-C3 4 MB (LOLIN C3 Pico, `min_spiffs`): erase,
+bootloader, partition table, otadata, blank filesystem and app in one pass, after which the board
+mounts LittleFS, creates its `/wifi`, `/frugal_iot`, … directories and brings up the captive portal at
+192.168.4.1. App-only update is confirmed too.
+
+Confirmed with the filesystem partition left erased: the firmware formats and mounts it itself, so no
+blank-filesystem image is shipped.
+
+Still untested:
+
+- the **S2 and S3 bootloaders**, generated with the same recipe but never checked against a reference
+  build from those boards
 - whether 921600 baud is reliable on CH340 adapters, or the default should drop to 460800
-- whether the 20-second boot-log window is long enough to see WiFi come up
 - whether unsupported octal flash on an S3 really does surface as the capacity-byte fallback
+- ESP8266 end to end (single whole image at `0x0`, no base bundle)
+
+---
+
+## Next steps
+
+### 1. Arduino-IDE-built firmware probably needs a different bootloader
+
+Almost certainly yes — the Arduino IDE core's `dio_80m` ELF (18688 bytes) is a different binary from
+pioarduino's `qio_80m`-with-DIO-header (19520 bytes), and that mismatch is exactly what broke
+LittleFS. We currently ship only the pioarduino one.
+
+Better than a warning comment on the page: **read the framework out of the app image.** Every ESP-IDF
+app carries an `esp_app_desc_t` at offset `0x20` (24-byte image header + 8-byte segment header), magic
+`0xABCD5432`, with `version`, `project_name`, `time`, `date` and `idf_ver` as fixed-width strings.
+The current `firmware.bin` reports:
+
+```
+idf_ver: v5.5.4    project_name: arduino-lib-builder    date: Jun 2 2026
+```
+
+So the flasher can parse the selected firmware, display what built it, and either pick a matching
+bootloader or refuse when it doesn't match the one on offer — turning an invisible, badly-misleading
+failure into an explicit refusal. Needs `idf_ver` recorded per bootloader in `boards.json`, which
+means capturing it when the bootloader is harvested.
+
+### 2. Writing WiFi config does bring the littlefs machinery back — so don't do it that way
+
+Pre-writing `/wifi/<ssid>` files means *building* a littlefs image, which reintroduces the whole
+generator problem: disk 2.1, `name_max` 64, `prog_size` 1, and no in-browser library that can produce
+that combination (`@wasm-os/mklfs` cannot set `name_max` at all).
+
+Given how sensitive this proved, prefer **serial config hand-off**: after flashing we still hold the
+port, and `System_Captive::dispatch` already consumes `topicTwig value` pairs, with
+`set/wifi/<ssid>` = password being an existing convention. The firmware then writes its own files
+using its own littlefs, so there is no format coupling, a list of networks is natural, and it doubles
+as a re-configure tool for boards already in the field. Small firmware addition; no client-side
+filesystem generation.
+
+**Reuse the intake the node already has.** The firmware does not need a new way to *apply* config —
+only a new way to *receive* it. Today the same values arrive over HTTP: the captive portal builds a
+form from `addString` / `addNumber` / `addBool` / `addButton`, and `addSTARoute` registers POST
+handlers on the station interface, so config comes in as query/form key-value pairs, is turned into
+`topicTwig` + value, and goes through `dispatch()` to `writeConfigToFS()`. MQTT `set/...` messages
+land in the same place.
+
+So the work is a **transport**, not a mechanism: read the same key-value pairs from USB serial and
+feed them into that existing dispatch. That keeps one code path for HTTP, MQTT and USB, and means
+anything configurable through the captive portal is automatically configurable at flash time. Worth
+settling on the serial line format (a `topicTwig value` pair per line is enough, terminated so a
+partial line is never applied) and whether the node echoes each accepted setting so the flasher can
+confirm rather than assume.
+
+### 3. Monitor needs Clear and Copy buttons
+
+The log is hard to work with once long. Two buttons beside Monitor, two new strings in four languages.
+
+### 4. `fs.cpp` reports a scary failure that isn't one
+
+On a freshly provisioned board the normal path prints `Corrupted dir pair`, `mount failed (-84)` and a
+`disableCore0WDT` error before quietly succeeding — and `"initialization done."` is gated behind
+`SYSTEM_LITTLEFS_DEBUG`, so an ordinary build shows only the alarming half. Worth fixing in
+`System_LittleFS::pre_setup`: suppress the component's log level around `begin(true)` (e.g.
+`esp_log_level_set("esp_littlefs", ESP_LOG_NONE)`, restoring afterwards) and print one clear line for
+each outcome, with the failure case *not* gated behind a debug flag. Firmware repo change.
+
+### 5. ESP8266 end to end
+
+Single whole image at `0x0`, no base bundle. Note it cannot format its own filesystem — its
+`ESPFS.begin()` takes no format-on-fail argument — so this is the one case that may genuinely need the
+pre-formatted blank image described above.
+
+### 6. S2 and S3 bootloaders
+
+Generated with the C3 recipe but never checked against a reference build. The check is exactly what
+settled the C3: build the firmware for an S2/S3 env and compare `.pio/build/<env>/bootloader.bin`
+against `base/bootloader/esp32s{2,3}.bin`.
+
+### 7. Auto-detect chip type and refuse a binary built for the wrong chip
+
+Partly built already: `appCheck()` compares the app image's `chip_id` (u16 at byte 12) against
+`esploader.chip.IMAGE_CHIP_ID` and throws on mismatch. But it has never been exercised — every test so
+far used a correctly matched C3 image — so it needs a deliberate wrong-chip attempt to confirm the
+refusal fires, reads clearly, and leaves the board untouched. Also worth checking whether esptool-js
+rejects it independently, so we know whether our check is the only guard or a second one.
+
+Two related refusals in the same code path are likewise untested: an app larger than the app
+partition, and a `<chip>-<flashsize>` combination absent from `boards.json`.
+
+### 8. UI polish
+
+Nothing structural — the flow works but is a little unintuitive. Known rough edges:
+
+- `Flash` is disabled until *both* a board and a firmware are chosen, with no hint saying so; the
+  reason should be visible rather than inferred from a grey button.
+- Provision vs app-only is auto-detected and reported in prose, but the destructive case deserves to
+  read as clearly destructive.
+- A hard reload silently clears the chosen firmware, which is surprising mid-session.
+- Ordering of the controls (file, speed, monitor speed, Connect, Flash, Monitor) has grown by
+  accretion rather than by how it is actually used.
 
 ---