frugal-iot-client 1.3.14 → 2.0.0

package/CLAUDE.md

@@ -14,22 +14,32 @@ it loadable on its own, and it is maintained by reaching the display elements **
 | `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` |
+| `admin.js` | core | `mqtt-admin` — one admin section, rendered per card by `cards.js` |
+| `login.js` | core | `mqtt-login` — sign in, register, forgot/reset password; light DOM |
 
-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.
+Every page loads the modules it needs; there is no file that loads everything.
+
+| Page | Loads |
+|---|---|
+| `index.html` | `dashboard.js` — the card UI |
+| `login.html` | `login.js`, which imports only `core.js` — that is why `mqtt-login` is not in `admin.js` |
+| `index-embedded.html`, `dashboard_example.html` | `core.js` + `widgets.js` + `graph.js` |
+
+Retired with the pre-cards UI: `index-old.html`, `index-project.html`, `nodeview.js` and
+`webcomponents.js` (the shim that loaded everything), `mqtt-admin`'s tab strip, and the wrapper's
+`headless` attribute — the data tree is all it builds now. `mqtt-admin` renders one section, chosen
+by its `section` attribute; the cards on a project's back make one per card.
 
 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.
+`docs/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. `docs/CARDS_PLAN.md` is how it was built, including the bugs found on the way.
+`docs/FLASH_PLAN.md` and `HEADLESS_PLAN.md` cover their own areas. Comments throughout the code cite
+these by bare filename (`see CARDS_UX.md 4.7`); they all live in `docs/` except `HEADLESS_PLAN.md`.
 
 ## Code style
 
@@ -93,7 +103,7 @@ Helper functions: `topicTwig(path)` → twig, `topicLeaf(path)` → leaf, `twigA
 - `mt.twig` — stored twig string (e.g. `sht/temperature`)
 - `mt.leaf` — getter, last segment of twig
 - `mt.topicPath` — getter, full path including node prefix
-- `mt.topicSetPath` — getter, write path (`…/set/…`); **throws when `this.node` is null** — only call on topics that are known to be part of the node hierarchy (i.e. `this.node` is set). Project-level or standalone topics (e.g. those created by an embedded `mqtt-graphdataset`) have no real node and must not reach this getter.
+- `mt.topicSetPath` — getter, write path (`…/set/…`); **throws when `this.nodeMt` is null** — only call on topics that are part of the node hierarchy. Project-level topics have no node and must not reach this getter. Topics built by `standaloneTopic()` do have a `nodeMt` (a stub), so an embedded widget's set path resolves.
 - `mt.element` — back-reference to the DOM element currently bound to this topic (null in headless mode or before binding)
 - `el.mt` — forward-reference from a DOM element to its `MqttTopic`
 
@@ -159,10 +169,12 @@ HTMLElementExtended          (from html-element-extended)
       MqttGroupFrugalIot     the frugal_iot system group (name, battery, OTA…)
   MqttClient                 MQTT connection UI element
   MqttWrapper                top-level entry point; fetches config, builds tree
-  MqttLogin                  login/register form
   MqttAdmin                  admin panel (OTA, permissions, node table)
   LanguagePicker             language selector
   TabbedDisplay              generic tab UI
+HTMLElementExtendedMinimum   (light DOM - no shadow root, so frugaliot.css reaches inside)
+  MqttLogin                  sign in / register / forgot / reset, one card and four modes
+  MqttDeviceCard, MqttDeviceGrid, MqttProjectBack, MqttDashboard   the card UI
 ```
 
 ### Adding a new display element
@@ -186,8 +198,8 @@ a control shows a rule. Then:
 
 ### 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`).
+- `mqtt-devicecard`, `mqtt-devicegrid` and `mqtt-login` 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`:
@@ -233,6 +245,18 @@ if (prevBarMt) prevBarMt.element = null;
 prevBarMt = sensorMt;
 ```
 
+### Embedded widgets (no wrapper)
+
+`index-embedded.html` puts an `mqtt-bar`/`mqtt-toggle`/`mqtt-graphdataset` on a page with nothing
+else — no `mqtt-wrapper`, no discovery tree, no `/config.json`. `standaloneTopic(path, o)` in
+`core.js` builds the one topic such a widget needs, giving it a stub `nodeMt` so `topicPath`,
+`topicSetPath` and `groupMt` all resolve. It also sets `mt.standalone`, which is what makes
+`canWrite` true: there is no permission list to consult, and the broker enforces the credentials on
+the `mqtt-client` element instead. `test/embedded.test.js` guards this — it has broken twice
+unnoticed.
+
+Still not available on such a page: graph history (`addDataFrom` needs `server_config.logger.url`).
+
 ### Looking up topics
 
 Use `wrapper.projectMt.findTopic(fullPath)` — never fabricate a new `MqttTopic` with partial paths:
@@ -267,14 +291,27 @@ Each of these cost real time. They are not obvious from reading the code.
   `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.
+  which is now retired — so these rules have no page they were drawn for. The card page opts out by
+  setting `--fi-chrome-font: 1rem`, which the rules read. They still reach the login page and the
+  embedded examples, so removing them is a visual change to those and wants looking at on a phone.
 - **`: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.
+- **A card's own gestures eat keystrokes and drags meant for a widget inside it.** `mqtt-devicecard`
+  listens for `keydown` (space picks it up) and `pointerdown` (drag to reorder) on itself, so a text
+  field on the back had every space `preventDefault`ed and a mouse selection of its text lifted the
+  card. Both handlers now bail on `isEditableTarget(e)` from `core.js`, which reads
+  `composedPath()[0]` — the target a card sees has been retargeted to the widget host, so
+  `e.target.tagName` is `MQTT-TEXT`, never `INPUT`.
 - **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.
+- **A node reports in a burst**, publishing its whole topic set at once, so gaps between messages
+  are milliseconds. `MqttTopicNode.noteMessage` ignores anything closer than `REPORT_BURST_MS` when
+  learning the reporting interval — without that the interval collapses and every device reads as
+  offline seconds after reporting. Status is also floored by `MIN_REPORT_INTERVAL_MS`.
+- **A device going quiet sends nothing**, so nothing prompts a re-render. `status` is derived rather
+  than timed, but a card still needs a slow interval to re-read it, or it shows whatever it showed
+  when the last message arrived.
 - **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
@@ -311,9 +348,9 @@ regress unnoticed; regenerate deliberately with `npm run test:update` and read t
 
 ## Internationalisation
 
-The master language table is `const languages` in `webcomponents.js`. Dashboard-specific strings are added via `addVocabulary(yamlString)` in the dashboard's `<script>`.
+The master language table is `const languages` in `core.js`. Dashboard-specific strings are added via `addVocabulary(yamlString)` in the dashboard's `<script>`.
 
-Every `addVocabulary` block must include **all four** language sections (EN, FR, HI, ID). Strings absent from `webcomponents.js` must be explicitly added in the dashboard block — do not assume the core file covers them.
+Every `addVocabulary` block must include **all four** language sections (EN, FR, HI, ID). Strings absent from `core.js` must be explicitly added in the dashboard block — do not assume the core file covers them.
 
 ### How a string gets translated