frugal-iot-client 1.3.15 → 2.0.1

package/CLAUDE.md

@@ -14,24 +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`, `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);
-`login.html` → `login.js`, which imports only `core.js` — that is why `mqtt-login` is not in
-`admin.js`; `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
 
@@ -40,6 +48,10 @@ deferred work is L-n, and it is the place to argue with a choice rather than re-
 - **Comments**: explain WHY, not WHAT. One short line is enough; do not restate what the code clearly shows. No multi-line docstrings.
   - Good: `// topicSetPath throws when this.node is null — guard before calling`
   - Bad: `// Check if topic starts with the set path`
+- **A comment says what is true now, not what used to break.** When fixing a bug, state the
+  constraint that still holds; the diagnosis — what it threw, where, why one deployment differed —
+  belongs in the pull request or the chat, not in the source, where it buries the one line that
+  still matters.
 - **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 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.
@@ -283,9 +295,9 @@ 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.
@@ -340,9 +352,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