frugal-iot-client 1.3.11

package/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node --check webcomponents.js)",
+      "Bash(node --check /Users/mitra/git/github_mitra42/frugal-iot-client/webcomponents.js)",
+      "Bash(git -C /Users/mitra/git/github_mitra42/frugal-iot-client status)",
+      "Bash(git -C /Users/mitra/git/github_mitra42/frugal-iot-client stash list)",
+      "Bash(git -C /Users/mitra/git/github_mitra42/frugal-iot-client show dashboard_example2:dashboard_example2.html)",
+      "Bash(git -C /Users/mitra/git/github_mitra42/frugal-iot-client branch -a)",
+      "Bash(git -C /Users/mitra/git/github_mitra42/frugal-iot-client show 73-headless:dashboard_example2.html)",
+      "Bash(git *)",
+      "WebFetch(domain:github.com)",
+      "Bash(curl -sL -H \"Accept: image/svg+xml\" \"https://github.com/user-attachments/assets/9d83e51f-a392-454f-860d-a855658ccdfb\")",
+      "Bash(curl -sL \"https://github.com/user-attachments/assets/9d83e51f-a392-454f-860d-a855658ccdfb?raw=true\")",
+      "Bash(curl -sL \"https://github.com/user-attachments/assets/9d83e51f-a392-454f-860d-a855658ccdfb\")",
+      "Read(//tmp/**)",
+      "Bash(curl -s -I \"https://github.com/user-attachments/assets/9d83e51f-a392-454f-860d-a855658ccdfb\")",
+      "Bash(curl -s -I \"https://github.com/user-attachments/assets/6c6bc26c-bf02-4def-a6f2-1e0ee00aa399\")",
+      "Bash(curl -s \"https://github-production-user-asset-6210df.s3.amazonaws.com/2242709/501137168-f4cc6bf7-0c67-4e9c-b597-7a17c155bb3a.svg\")",
+      "Bash(curl -s \"https://github-production-user-asset-6210df.s3.amazonaws.com/2242709/604453755-9d83e51f-a392-454f-860d-a855658ccdfb.svg\")",
+      "Bash(curl -s \"https://github-production-user-asset-6210df.s3.amazonaws.com/2242709/604454647-6c6bc26c-bf02-4def-a6f2-1e0ee00aa399.svg\")",
+      "Bash(curl *)",
+      "Bash(grep -n \"el\\('p', {}, \\\\[\\\\\"\" webcomponents.js)",
+      "Bash(grep -n \"el\\('h[1-5]', {}, \\\\[\\\\\"\" webcomponents.js)",
+      "Bash(grep -n \"^const languages\\\\|^EN:\\\\|^FR:\\\\|^HI:\\\\|^ID:\\\\|^\\\\`\\);\" /Users/mitra/git/github_mitra42/frugal-iot-client/webcomponents.js)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,263 @@
+# Frugal IoT Client
+
+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
+
+`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.
+
+Dashboards (e.g. `dashboard_example2.html`) are thin HTML pages that import selectively from `webcomponents.js`.
+
+## Code style
+
+- **Indentation**: 2 spaces throughout.
+- **Async style**: prefer callback-style async (using the `async` library from `caolan/async`) over Promise chains. Existing `fetch` calls that use `.then()` are legacy patterns; new async code should use callbacks or `async.waterfall` / `async.parallel` etc.
+- **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`
+- **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.
+
+---
+
+## Naming conventions
+
+### Topic path segments
+
+```
+org / project / nodeId / group / leaf                         read
+org / project / nodeId / set / group / leaf                   write
+org / project / nodeId / set / group / leaf / wired           wiring
+org / project / nodeId / set / group / leaf / parameter       parameter (e.g. max, min)
+```
+
+Concrete examples:
+```
+dev/myproject/node42/sht/temperature
+dev/myproject/node42/set/sht/temperature
+dev/myproject/node42/set/sht/temperature/wired
+dev/myproject/node42/set/sht/temperature/max
+```
+
+| Term | Meaning | Example |
+|---|---|---|
+| `path` / `topicPath` | Full path from root | `dev/myproject/node42/sht/temperature` |
+| `twig` | From group onward; strips org/project/node prefix and `set/` | `sht/temperature` |
+| `leaf` | Last segment only | `temperature` |
+| `parameter` | Sub-path under the set path | `max`, `min`, `wired` |
+
+Helper functions: `topicTwig(path)` → twig, `topicLeaf(path)` → leaf, `twigAttribute(path)` → `sht_temperature`, `leafAttribute(path)` → `temperature_max` (slashes replaced with underscores for DOM attributes).
+
+### Variable suffixes
+
+| Suffix | Points to | Example |
+|---|---|---|
+| `Mt` | An `MqttTopic` instance | `sensorMt`, `nodeMt`, `groupMt`, `projectMt` |
+| `Twig` | A string starting at group/leaf | `sht/temperature` |
+| `Leaf` | A string holding just the final segment | `temperature` |
+| `Path` | A full MQTT path string | `dev/myproject/node42/sht/temperature` |
+| `El` | A DOM element | `barEl`, `groupEl` |
+
+### Object properties on `MqttTopic`
+
+- `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.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`
+
+---
+
+## Architecture
+
+### Global state (module-level)
+
+| Variable | Purpose |
+|---|---|
+| `mqtt_client` | The live MQTT connection (mqtt.js) |
+| `mqtt_subscriptions` | `[{topic, cb}]` — all active subscriptions |
+| `server_config` | Config JSON fetched from `/config.json` at startup |
+| `graph` | The default `MqttGraph` created on first graphing action |
+| `preferedLanguages` | Array of language codes, e.g. `['EN']` |
+
+### Class hierarchy
+
+Data-tree classes are always instantiated. UI element classes are only instantiated when not in headless mode.
+
+**Data-tree** (plain JS, no HTMLElement):
+```
+MqttTopic          leaf data node — history, metadata, subscribe/publish logic
+  (future: MqttTopicProject → MqttTopicNode → MqttTopicGroup, see HEADLESS_PLAN.md)
+Watchdog           offline detection timer per node
+```
+
+**UI elements** (extend HTMLElementExtended):
+```
+HTMLElementExtended          (from html-element-extended)
+  MqttElement                attributeChangedCallback, typeOfAttribute
+    MqttReceiver             topicValueSet, valueSet, parameterSet, render helpers
+      MqttTransmitter        publish, valueGet
+        MqttText             text/number input
+        MqttColor            color picker input
+        MqttToggle           boolean checkbox
+        MqttSlider           drag slider
+      MqttBar                progress bar display
+      MqttGauge              dial-gauge display
+      MqttProject            manages a project and its nodes     ← not created in headless
+      MqttNode               manages a single IoT node           ← not created in headless
+    MqttChooseTopic          dropdown to wire one topic to another
+    MqttGraph                Chart.js wrapper (time-series graph)
+    MqttGraphDataset         one dataset/line within a MqttGraph
+    MqttGroup                collapsible group of topics         ← not created in headless
+      MqttSummaryGroup       base for groups with a summary line
+        MqttGroupLedbuiltin  LED on/off indicator dot
+        MqttGroupRelay       relay on/off symbol
+        MqttGroupSht         temperature + humidity summary
+        MqttGroupSoil        soil moisture %
+        MqttGroupDS18B20     DS18B20 temperature °C
+        MqttGroupBattery     battery mV
+        MqttGroupOta         OTA key display
+        MqttGroupControlHysteresis   control loop summary
+        MqttGroupControlHysterisis   legacy spelling alias
+      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
+```
+
+### Adding a new display element
+
+1. Create a class extending `MqttReceiver` (read-only) or `MqttTransmitter` (read/write).
+2. Override `valueSet(val)` to update the DOM in-place (set `elements.*` refs in `render()`); return `false` to skip full re-render.
+3. Override `render()` to return the initial shadow-DOM tree using the local `el()` helper.
+4. Register with `customElements.define('mqtt-<name>', MyClass)`.
+5. Add a `case '<display-name>':` in `MqttTopic.createElement()`.
+
+### 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.
+
+---
+
+## 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.
+
+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.
+- Must call `setWired` when a `wired` parameter arrives.
+- Must fire `frugaliot:groupchanged` to notify dashboards of state changes.
+
+---
+
+## Dashboard patterns
+
+### Prefer getters on `MqttTopic` over dashboard logic
+
+When a dashboard needs derived data (usable name, min/max, wired source), add a `get` on `MqttTopic` rather than computing it in the dashboard. Dashboards should just read `mt.someGetter`.
+
+### Binding elements to data-tree topics
+
+Always pre-bind before `appendChild`, otherwise `connectedCallback` calls `createTopic()` and fabricates a wrong-path subscription:
+
+```javascript
+const barEl = el('mqtt-bar', { topic: sensorMt.topicPath, ... });
+barEl.mt = sensorMt;       // prevents createTopic() from running
+sensorMt.element = barEl;  // routes wildcard subscription messages to this element
+barContainer.appendChild(barEl);
+```
+
+Clear back-references when rebuilding so stale elements don't receive messages:
+
+```javascript
+if (prevBarMt) prevBarMt.element = null;
+prevBarMt = sensorMt;
+```
+
+### Looking up topics
+
+Use `wrapper.projectMt.findTopic(fullPath)` — never fabricate a new `MqttTopic` with partial paths:
+
+```javascript
+const mt = document.querySelector('mqtt-wrapper')?.projectMt?.findTopic(this.state.topic);
+```
+
+### Events
+
+| Event | Fired by | Carries | Typical use |
+|---|---|---|---|
+| `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 |
+
+---
+
+## Internationalisation
+
+The master language table is `const languages` in `webcomponents.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.
+
+### How a string gets translated
+
+There are three ways a piece of UI text is translated. If a string doesn't go through one of these, it silently stays in English regardless of the selected language:
+
+1. **Direct call to `getString(tag)`** — looks the string up in `languages`, falling back to the English value, falling back to `tag` itself. Used for names built dynamically (e.g. a graph's scale/axis name at `text: getString(this.name...)`).
+2. **Via `el(tag, attributes, children)`** — `el()` auto-translates certain *attributes* on certain *tags*, per the `i8ntags` table (currently `label`, `button`, `span`, `option`, `p`, `h1`–`h5`, `th`, all via their `textContent` attribute). Add a tag/attribute pair to `i8ntags` when a new kind of element needs translated text. Excluded even on a listed tag: values containing `:` or `/` (these are usually paths or key:value pairs, not prose), and values not starting with a letter (emoji/symbol-only content). Pass `i8n: false` on an element you know is untranslatable (a proper name, an id, dynamic per-row data).
+3. **Via a graph's scale name** — same as (1), a direct `getString()` call when building the Chart.js scale config.
+
+**Only `textContent` is translated — never a literal string passed as a DOM `children` argument.** `el('p', {}, ["Some text"])` bypasses the mechanism entirely because the filter inspects `attributes`, not `children`. Always write `el('p', {textContent: "Some text"})` instead. This applies to `p`, `h1`–`h5`, `span`, and any other tag in `i8ntags`.
+
+When adding a new UI string: add matching entries to all four language sections in `languages` (or the dashboard's `addVocabulary` block) — even if you only have the English text, add the same text under EN so `getString` doesn't silently fall through and hide missing translations.
+
+---
+
+## Key helpers
+
+- `el(tag, attributes, children)` — local wrapper around `EL` that applies i18n translation to label/button/span text. Pass `i8n: false` in attributes to suppress translation for names/IDs.
+- `getString(tag)` — look up a string in the current language(s); falls back to English.
+- `mqtt_subscribe(topic, cb)` — registers a subscription; replays on reconnect.
+- `GET(url, opts, cb)` — from `html-element-extended`; callback-style HTTP GET returning parsed JSON.
+- `XXX(args)` — debug log with a breakpoint hook; use for unexpected states. Leave calls in place.
+- `XXY(args)` — debug log for known-legacy paths; returns `false` so it can be used in `&&` guards. Don't add new calls.
+
+---
+
+## Dependencies
+
+| Package | Role |
+|---|---|
+| `html-element-extended` | Base class `HTMLElementExtended`, `EL`, `GET`, `toBool` |
+| `mqtt` | MQTT over WebSocket |
+| `js-yaml` | Parse YAML in discovery messages and i18n config |
+| `async` | Callback-style async utilities (preferred over Promises) |
+| `csv-parse` | Parse historical CSV data from the logger |
+| `chart.js` | Time-series graphs |
+| `luxon` | Date/time for Chart.js (adapter inlined in webcomponents.js) |
+| `dial-gauge` | Gauge web component |
+
+---
+
+## Running locally
+
+```bash
+npm install
+# run frugal-iot-server pointing htmldir at this directory
+node ../frugal-iot-server/frugal-iot-server.js
+# open https://localhost:8080
+```
+
+## Debugging tips
+
+- Sprinkle `XXX("label")` calls and set a breakpoint inside `XXX` to trace execution.
+- `XXY` is for legacy twigs that should eventually disappear — don't add new `XXY` calls.
+- `this.state.elements` holds named refs to live DOM nodes updated without full re-render.
+- `server_config` (fetched from `/config.json`) drives schema, modules, topics, and org/project/node hierarchy.

package/HEADLESS_PLAN.md

@@ -0,0 +1,167 @@
+# Plan: Headless Data-Tree Mode for mqtt-wrapper
+
+## Goal
+
+Allow `mqtt-wrapper` to operate without building any DOM elements for the project/node/group/leaf UX. The `MqttTopic` data tree becomes the single source of truth, shared across all dashboards. DOM elements become optional UX decorations layered on top. In headless mode, a dashboard may still create individual standalone elements by calling `MqttTopic.createElement()` directly.
+
+---
+
+## New Class Hierarchy
+
+Four data-tree classes, all subclasses of `MqttTopic`, paired with optional UX element classes:
+
+| Data-tree class | UX element class | Contains |
+|---|---|---|
+| `MqttTopicProject` | `MqttProject` | `nodes: { nodeId → MqttTopicNode }` |
+| `MqttTopicNode` | `MqttNode` | `groups: { groupId → MqttTopicGroup }` |
+| `MqttTopicGroup` | `MqttGroup` (and subclasses) | `topics: { leaf → MqttTopic }` |
+| `MqttTopic` | `MqttBar`, `MqttText`, etc. | `data[]` (time-series history) |
+
+In full-UI mode all four levels have both a data object and a paired element. In headless mode only the data objects are created; individual elements can still be created on demand via `MqttTopic.createElement()`.
+
+The tree structure makes the data hierarchy explicit and matches the MQTT topic path structure:
+```
+org / project / nodeId / groupId / leaf
+  Project       Node      Group    Topic
+```
+
+---
+
+## Proposed Changes
+
+### 1. Add a `headless` attribute to `mqtt-wrapper`
+
+When set, the wrapper does not build any DOM for project/node/group/leaf display. The `mqtt-client` connection UI still renders (unless separately suppressed).
+
+In headless mode:
+- `MqttTopicProject` is created but `MqttProject` (the element) is not.
+- `MqttTopicNode` is created but `MqttNode` (the element) is not.
+- `MqttTopicGroup` is created but `MqttGroup` (the element) is not.
+- Leaf `MqttTopic` objects are created as normal — the data tree is fully populated.
+- A dashboard can still call `mt.createElement()` on any individual leaf `MqttTopic` to get a standalone renderable element for that topic.
+
+`headless` propagates from `mqtt-wrapper` → `MqttTopicProject` → `MqttTopicNode` → `MqttTopicGroup` so each level knows whether to instantiate its paired element.
+
+---
+
+### 2. Introduce `MqttTopicGroup` and restructure the topic index
+
+Currently `MqttTopicNode` holds a flat map of all leaf topics keyed by twig (`group/leaf`). This is replaced by a two-level structure:
+
+- `MqttTopicNode.groups[groupId]` → `MqttTopicGroup`
+- `MqttTopicGroup.topics[leaf]` → `MqttTopic`
+
+`MqttTopicGroup` is a subclass of `MqttTopic`. It holds:
+- `topics` — the leaf topics for this group
+- State fields for the group (name, `on`, `now_wired`, `out_wired`, etc.) — see change 3
+
+**Impact on `findTopic`** (currently line 2898): navigates directly through the grouped structure:
+```javascript
+// old: this.state.nodes[nodeId].state.topics[`${group}/${leaf}/#`]
+// new:
+const node = this.nodes[nodeId];           // MqttTopicNode
+const group = node && node.groups[groupId]; // MqttTopicGroup
+return group && group.topics[leaf];         // MqttTopic
+```
+
+**Impact on `controlGroups` getter** (currently derives groups by filtering the flat topics map): now reads directly from `MqttTopicNode.groups` filtered by `groupId.startsWith('control')` — simpler and no derivation needed.
+
+**Impact on `sendMessageToMatchingTopics` / MQTT routing**: currently iterates `state.topics[twig + "/#"]` with wildcard matching. With two-level storage, routing splits the twig on `/` to reach `groups[groupId].topics[leaf]` directly, which is O(1) rather than a scan. The wildcard case (messages arriving at sub-paths like `control/now/wired`) is handled by looking up `groups[groupId].topics[leaf]` and then forwarding the sub-path to that topic's `message_received`.
+
+**Existing `MqttTopic.groups` getter** (lines 812–820, derives groups from flat topics) is removed; callers use `MqttTopicNode.groups` directly.
+
+---
+
+### 3. Move MQTT message routing from `MqttNode` to `MqttTopicNode`
+
+**This is the largest change.**
+
+`MqttNode.topicValueSet` (lines 3004–3090) strips the node prefix and `set/`, applies legacy-topic filtering, auto-creates groups from templates, and dispatches to `sendMessageToMatchingTopics`. This is data-tree logic, not UX logic.
+
+**New structure:**
+
+- `MqttTopicNode.topicValueSet(topicPath, message)` carries the full routing and group-creation logic. Where the existing code performs UX-specific actions (appending elements to the DOM, triggering re-renders, rebuilding dropdowns), it calls a method on `this.element` (the paired `MqttNode`), guarded by `if (this.element)`.
+- `MqttNode.topicValueSet` becomes a thin override that calls `super` and handles only its UX-specific additions.
+- `MqttTopicProject.topicValueSet` mirrors the same split for the project level.
+- `MqttTopic.message_received` calls `this.node.topicValueSet(...)` directly, targeting the `MqttTopicNode`.
+
+The legacy-topic filter (the long chain of `twig.startsWith` / `twig.endsWith` guards) stays in `MqttTopicNode.topicValueSet` — it is data routing logic, not UX.
+
+Group auto-creation (`addGroupFromTemplate`) moves to `MqttTopicNode` and produces a `MqttTopicGroup`. If an element is present, the element's equivalent is then created and linked.
+
+---
+
+### 4. Move leaf and group state from element `state` to data-tree objects
+
+**No parallel copies — state moves, not duplicates.**
+
+State that describes the observed data (rather than UX presentation) moves from element `this.state` to the corresponding data-tree object:
+
+- Leaf state (`value`, `wired`, `min`, `max`, `color`, `type`, `rw`, …) moves to `MqttTopic.state`.
+- Group state (`name`, `on`, `now_wired`, `out_wired`, `limit_wired`, …) moves to `MqttTopicGroup.state`.
+
+Names are preserved: `element.state.wired` becomes `topic.state.wired`, `element.state.on` becomes `groupTopic.state.on`, etc. UX elements read these fields from their associated topic via `this.mt.state.*`.
+
+The `this.data` array on `MqttTopic` (time-series history for graphing) is not affected.
+
+**Roll-up (leaf → group):** Currently `MqttReceiver.topicValueSet` calls `groupElement.setAttribute('now_wired', value)` (lines 2067–2078). This becomes: write to `this.mt.groupTopic.state.now_wired = value` (the `MqttTopicGroup` for this leaf's group). If a group element exists it is notified separately. This is also what enables the `frugaliot:groupchanged` event (change 7).
+
+**`MqttTopic.groupName` / `usableName`:** currently reads `groupEl.state.name`. After this change it reads `this.groupMt.state.name` (the `MqttTopicGroup`) — no element traversal.
+
+---
+
+### 5. `MqttProject.state.nodes` goes away
+
+`this.mt.nodes[id]` (keyed nodeId → `MqttTopicNode`) is the authoritative index; it already exists (line 2856). `MqttProject.state.nodes[id]` (which stores the element) is removed. UX code that currently reads `state.nodes` is updated to use `this.mt.nodes` and reach the element via `nodeMt.element` where needed.
+
+`findTopic` (updated in change 2) navigates through `this.mt.nodes` and the grouped structure.
+
+---
+
+### 6. `wiredTopic` — replace DOM traversal with a direct data reference
+
+Current: `this.project` → `this.node.project` → `this.node.closest("mqtt-project")` — DOM traversal.
+
+New: `fromTemplate` (and the equivalent initialisers on `MqttTopicNode` / `MqttTopicGroup`) stores a direct reference to the `MqttTopicProject` as `this.projectMt`. `wiredTopic` becomes `this.projectMt.findTopic(this.wired)` — no DOM required. Also a correctness improvement for temporarily detached elements.
+
+---
+
+### 7. Replace the element reference in `frugaliot:topicschanged`
+
+Current: `{ project: this }` where `this` is the `MqttProject` element.
+
+New: `{ project: this.mt }` — the `MqttTopicProject`. Dashboards that already access `wrapper.projectMt` need no change.
+
+---
+
+### 8. Replace `MutationObserver` with a `frugaliot:groupchanged` event
+
+`dashboard_example2.html` uses a `MutationObserver` on the group element to detect `now_wired`, `out_wired`, and `on` attribute changes, then re-runs `wireUpDashboard`.
+
+Once group state lives on `MqttTopicGroup` (change 4), `MqttTopicNode.topicValueSet` fires a `frugaliot:groupchanged` CustomEvent whenever a group-level state field changes. The event carries `{ nodeMt, groupId, changed: ['now_wired'] }`.
+
+Dashboards subscribe to this event instead of observing DOM mutations. This works in headless mode and removes the dependency on the group element being in the DOM.
+
+---
+
+## What Does NOT Need to Change
+
+- `MqttTopic.message_received` already has a headless path: if `this.element` is absent it stores into `this.data[]`. After change 4 it also updates `this.state.value`. No restructuring of this method is needed.
+- `setWired` / `publishWired` work on `MqttTopic` directly — no element required.
+- `frugaliot:controlgroup` already fires with data-tree references only — no change needed.
+- `mqtt-choosetopic` still needs a DOM element to render a `<select>`, but it reads options from the data tree.
+- The graph (`MqttGraph`, `MqttGraphDataset`) operates on `MqttTopic` directly — no change required.
+- `MqttTopic.createElement()` continues to work in headless mode — dashboards can call it on any leaf topic to get a standalone renderable element.
+
+---
+
+## Sequencing (suggested)
+
+1. **5** (`MqttProject.state.nodes` → `this.mt.nodes`) — isolated, removes a redundant map  
+2. **6** (`this.project` via direct reference) — isolated, correctness improvement  
+3. **7** (`frugaliot:topicschanged` payload) — small, any time  
+4. **2** (introduce `MqttTopicGroup`, restructure node topics into groups) — enables cleaner state migration  
+5. **4** (state moves from element to data-tree objects) — depends on 2 for group state  
+6. **3** (introduce `MqttTopicNode`/`MqttTopicProject`, move routing) — largest change; depends on 2 + 4  
+7. **8** (replace `MutationObserver` with `frugaliot:groupchanged`) — depends on 3 + 4  
+8. **1** (add `headless` attribute) — gates actual UI suppression; can be added once 3–5 are done  

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mitra Ardron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# Frugal IoT client
+
+This is a javascript based client for the Frugal IoT project, in particular it has the 
+following features
+
+* Can connect to MQTT.
+* Understands the discovery messages of Frugal IoT so can determine what sensors are available
+* Can display results from sensors in Bar graphs, toggles, with other UX coming soon
+* Can control nodes including both direct control
+  e.g. toggling a relay - and configuting various parameters.
+* Can show graph results for multiple readings
+
+There is much still to do - see https://github.com/mitra42/frugal-iot-client. 
+This repo was spun out of the main repo https://github.com/mitra42/frugal-iot 
+which is still the best place to post complex issues involving client / server and node. 
+
+## Test and demonstration
+
+Connect to https://frugaliot.naturalinnovation  it will server up the current UI.
+
+## Installation for development
+
+Note this process will probably change to make configuration changes for development easier.
+
+This should work on Linux or a Mac - (instructions on windows welcome as a PR)
+Clone this repo, 
+```
+git clone https://github.com/mitra42/frugal-iot-client.git
+cd frugal-iot-client; npm install
+cd ..
+```
+Clone and run the server
+```
+git clone https://github.com/mitra42/frugal-iot-server.git
+cd frugal-iot-server; npm install
+```
+Edit `frugal-iot-server.js` and uncomment the line hear the top
+that sets `htmldir` to the `../frugal-iot-client`
+```
+node frugal-iot-server.js
+```
+Point your browser at `https://localhost:8080`
+
+You should see a series of dialogues allowing you to select a project.
+Choosing `dev` and `lotus` will often get one of the test nodes I'm running at home.
+
+
+