From b1e0736e8eafad038407917bb66c47458d2fe7b4 Mon Sep 17 00:00:00 2001
From: znetsixe <zn375ix3@gmail.com>
Date: Mon, 18 May 2026 21:31:23 +0200
Subject: [PATCH] docs: propagate folder-naming convention + bump submodules
 for editor refresh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Convention:
* CLAUDE.md (root): new "Folder & File Layout (READ BEFORE CREATING NEW FILES)"
  section with required-name table and explicit legacy-drift list (mgc, vgc,
  dashboardapi).
* .claude/rules/node-architecture.md: file-naming convention + src/editor/
  module layout sections; serving recipe for /<nodeName>/editor/:file.

Submodule bumps:
* generalFunctions: shared output-format picker, redesigned position SVGs,
  tighter asset wizard, restored curve preview size.
* rotatingMachine: pump banner, circular state diagram, mode icon cards,
  picker integration, CLAUDE.md update.
* 10 others: per-node CLAUDE.md "Folder & File Layout" sections — 3 of
  them (machineGroupControl, valveGroupControl, dashboardAPI) carry inline
  warnings about their entry-filename drift.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/rules/node-architecture.md | 54 ++++++++++++++++++++++++++++++
 CLAUDE.md                          | 29 ++++++++++++++--
 nodes/dashboardAPI                 |  2 +-
 nodes/diffuser                     |  2 +-
 nodes/generalFunctions             |  2 +-
 nodes/machineGroupControl          |  2 +-
 nodes/measurement                  |  2 +-
 nodes/monster                      |  2 +-
 nodes/pumpingStation               |  2 +-
 nodes/reactor                      |  2 +-
 nodes/rotatingMachine              |  2 +-
 nodes/settler                      |  2 +-
 nodes/valve                        |  2 +-
 nodes/valveGroupControl            |  2 +-
 14 files changed, 93 insertions(+), 14 deletions(-)

diff --git a/.claude/rules/node-architecture.md b/.claude/rules/node-architecture.md
index 07f051e..563fe7b 100644
--- a/.claude/rules/node-architecture.md
+++ b/.claude/rules/node-architecture.md
@@ -23,9 +23,63 @@ Every node follows entry → nodeClass → specificClass:
 - Port 1: InfluxDB telemetry payload
 - Port 2: Registration/control plumbing (parent-child handshakes)
 
+## File-Naming Convention
+The folder name is the canonical node name and every per-node file MUST match it
+exactly (case-sensitive). No abbreviations.
+
+| Path | Required name |
+|---|---|
+| Folder | `nodes/<nodeName>/` |
+| Entry file | `nodes/<nodeName>/<nodeName>.js` |
+| Editor HTML | `nodes/<nodeName>/<nodeName>.html` |
+| nodeClass | `nodes/<nodeName>/src/nodeClass.js` |
+| specificClass | `nodes/<nodeName>/src/specificClass.js` |
+| Editor JS modules | `nodes/<nodeName>/src/editor/*.js` |
+
+`machineGroupControl/mgc.js`, `valveGroupControl/vgc.js`, and
+`dashboardAPI/dashboardapi.js` are legacy drift. New nodes MUST use the full
+folder name; legacy nodes get renamed when next touched (rename = update entry
+file, HTML file, `package.json#node-red.nodes`, and any test imports in one
+commit).
+
+## Editor JS Layout — `src/editor/`
+Editor-side JavaScript that exceeds a couple of dozen lines lives in modular
+files under `nodes/<nodeName>/src/editor/`, served by the entry file via:
+
+```js
+const path = require('path');
+RED.httpAdmin.get(`/${nameOfNode}/editor/:file`, (req, res) => {
+  const safe = String(req.params.file || '').replace(/[^a-zA-Z0-9._-]/g, '');
+  if (!safe.endsWith('.js')) return res.status(400).send('// invalid');
+  res.type('application/javascript');
+  res.sendFile(path.join(__dirname, 'src', 'editor', safe), (err) => {
+    if (err && !res.headersSent) res.status(404).send('// editor module not found');
+  });
+});
+```
+
+The HTML file then loads them as plain `<script src="/<nodeName>/editor/<file>.js">`
+tags. Conventional modules:
+
+| File | Purpose |
+|---|---|
+| `index.js` | Namespace setup (`window.EVOLV.nodes.<nodeName>.editor = …`), shared helpers |
+| `oneditprepare.js` | Implementation called from the `.html`'s `oneditprepare` hook |
+| `oneditsave.js` | Implementation called from the `.html`'s `oneditsave` hook |
+| Feature modules | One per visual concern, e.g. `basin-diagram.js`, `mode-cards.js`, `timing-donut.js`, `hover-couple.js` |
+
+The `.html` shrinks to: register defaults, declare HTML template, delegate
+`oneditprepare`/`oneditsave` to the modules. Inline JS in the `.html` is fine
+for **trivial** nodes (≤ ~50 lines of editor JS); past that, extract.
+
+Reference implementations: `pumpingStation/src/editor/` and
+`machineGroupControl/src/editor/`. `rotatingMachine` is currently inline and
+should be migrated when the editor JS next grows.
+
 ## Admin Endpoints
 - `GET /<nodeName>/menu.js` — Dynamic menu configuration for editor
 - `GET /<nodeName>/configData.js` — Runtime configuration for editor
+- `GET /<nodeName>/editor/:file` — (when present) editor JS modules from `src/editor/`
 
 ## Submodule Awareness
 Most `nodes/*` directories are git submodules. Keep edits scoped to the target node's directory.
diff --git a/CLAUDE.md b/CLAUDE.md
index a8be7e3..c9c9e85 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,10 +9,35 @@ Node-RED custom nodes package for wastewater treatment plant automation. Develop
 
 ## Architecture
 Each node follows a three-layer pattern:
-1. **Node-RED wrapper** (`<name>.js`) - registers the node type, sets up HTTP endpoints
+1. **Node-RED wrapper** (`<nodeName>.js`) - registers the node type, sets up HTTP endpoints
 2. **Node adapter** (`src/nodeClass.js`) - bridges Node-RED API with domain logic, handles config loading, tick loops, events
 3. **Domain logic** (`src/specificClass.js`) - pure business logic, no Node-RED dependencies
 
+## Folder & File Layout (READ BEFORE CREATING NEW FILES)
+Every per-node file MUST use the folder name **exactly** (case-sensitive). No
+abbreviations. Quick reference:
+
+| Path | Required name |
+|---|---|
+| Entry file | `nodes/<nodeName>/<nodeName>.js` |
+| Editor HTML | `nodes/<nodeName>/<nodeName>.html` |
+| Node adapter | `nodes/<nodeName>/src/nodeClass.js` |
+| Domain logic | `nodes/<nodeName>/src/specificClass.js` |
+| Editor JS modules | `nodes/<nodeName>/src/editor/*.js` (extract when inline editor JS exceeds ~50 lines) |
+| Tests | `nodes/<nodeName>/test/{basic,integration,edge}/*.test.js` |
+| Example flows | `nodes/<nodeName>/examples/*.flow.json` |
+
+Full rule + serving recipe for `src/editor/`: `.claude/rules/node-architecture.md`.
+
+**Legacy drift to rename when the file is next touched** (do not introduce new
+mismatches in the meantime):
+
+| Node | Currently | Should be |
+|---|---|---|
+| `machineGroupControl` | `mgc.{js,html}` | `machineGroupControl.{js,html}` |
+| `valveGroupControl` | `vgc.{js,html}` | `valveGroupControl.{js,html}` |
+| `dashboardAPI` | `dashboardapi.{js,html}` | `dashboardAPI.{js,html}` |
+
 ## Key Shared Library: `nodes/generalFunctions/`
 - `logger` - structured logging (use this, NOT console.log)
 - `MeasurementContainer` - chainable measurement storage (type/variant/position)
@@ -27,7 +52,7 @@ Each node follows a three-layer pattern:
 - S88 color scheme: Area=#0f52a5, ProcessCell=#0c99d9, Unit=#50a8d9, Equipment=#86bbdd, ControlModule=#a9daee
 - Config JSON files in `generalFunctions/src/configs/` define defaults, types, enums per node
 - Tick loop runs at 1000ms intervals for time-based updates
-- Output ports + 3-tier architecture: see `.claude/rules/node-architecture.md`
+- Output ports + 3-tier architecture + file-naming + `src/editor/` layout: see `.claude/rules/node-architecture.md`
 - **Multi-tab demo flows**: see `.claude/rules/node-red-flow-layout.md` for the tab/link-channel/spacing rule set used by `examples/`
 - **Output coverage** (every output, every state, every layer): see `.claude/rules/output-coverage.md` — manifest + populated/degraded tests are mandatory for any change that touches Port 0/1/2 keys, function-node fan-outs, telemetry fields, or dashboard widget sources
 
diff --git a/nodes/dashboardAPI b/nodes/dashboardAPI
index f0a7904..a6f09d8 160000
--- a/nodes/dashboardAPI
+++ b/nodes/dashboardAPI
@@ -1 +1 @@
-Subproject commit f0a7904985bdba995a3cf1bb49cad34019ca1b04
+Subproject commit a6f09d821d9e7ce92c84705b1e07715669ba73cc
diff --git a/nodes/diffuser b/nodes/diffuser
index 37a8569..4973a8b 160000
--- a/nodes/diffuser
+++ b/nodes/diffuser
@@ -1 +1 @@
-Subproject commit 37a85690d1110b139c50286f732726fad1cada36
+Subproject commit 4973a8bcfc4fecd190c54f369faa74acf07eda42
diff --git a/nodes/generalFunctions b/nodes/generalFunctions
index 49c77f2..ab48135 160000
--- a/nodes/generalFunctions
+++ b/nodes/generalFunctions
@@ -1 +1 @@
-Subproject commit 49c77f262f684769b074102f22d8e353d365eebb
+Subproject commit ab481357d21c5ab9a3cf29359d242bc94f1d1c4d
diff --git a/nodes/machineGroupControl b/nodes/machineGroupControl
index 6833e9f..998e9bd 160000
--- a/nodes/machineGroupControl
+++ b/nodes/machineGroupControl
@@ -1 +1 @@
-Subproject commit 6833e9f3a8d7835cfae2a22649da1bd0e42e62a7
+Subproject commit 998e9bd758862c3f88bcc2dfc9af3ccbf95d8d63
diff --git a/nodes/measurement b/nodes/measurement
index ffc0358..b884c0f 160000
--- a/nodes/measurement
+++ b/nodes/measurement
@@ -1 +1 @@
-Subproject commit ffc03584edf6bac78c5b2d3cefbf2c3a867b40eb
+Subproject commit b884c0f085319429af2da41da8362a2eb65162a9
diff --git a/nodes/monster b/nodes/monster
index 59ff4d2..cd185dc 160000
--- a/nodes/monster
+++ b/nodes/monster
@@ -1 +1 @@
-Subproject commit 59ff4d230eedf90e2578f64515fc5780699b3ebc
+Subproject commit cd185dcd82685dd14fbd3ebf95e21ddf2d232c41
diff --git a/nodes/pumpingStation b/nodes/pumpingStation
index 2c7fe17..03440e1 160000
--- a/nodes/pumpingStation
+++ b/nodes/pumpingStation
@@ -1 +1 @@
-Subproject commit 2c7fe1792f68937f0f9dc3409fd1debd12bd3454
+Subproject commit 03440e1e6c6d181ab42850507e75574db53921b8
diff --git a/nodes/reactor b/nodes/reactor
index d735f94..0e34403 160000
--- a/nodes/reactor
+++ b/nodes/reactor
@@ -1 +1 @@
-Subproject commit d735f9485ce732d128ad8a1b305266d6b38ced74
+Subproject commit 0e34403c5d2293fce392391781dca10c3b3f042d
diff --git a/nodes/rotatingMachine b/nodes/rotatingMachine
index 5ea0b0b..426c1a6 160000
--- a/nodes/rotatingMachine
+++ b/nodes/rotatingMachine
@@ -1 +1 @@
-Subproject commit 5ea0b0bda67ab98ccbee9898d0026cf048435b27
+Subproject commit 426c1a606b11ee453b07845ec2509d7c66c90d03
diff --git a/nodes/settler b/nodes/settler
index 98052a1..a3583a3 160000
--- a/nodes/settler
+++ b/nodes/settler
@@ -1 +1 @@
-Subproject commit 98052a16e73a89c194115c736b87d353a4209d0c
+Subproject commit a3583a3edbe628d15bcefe41e7c38954b3b77b76
diff --git a/nodes/valve b/nodes/valve
index 68ebe4e..8c2b2c0 160000
--- a/nodes/valve
+++ b/nodes/valve
@@ -1 +1 @@
-Subproject commit 68ebe4ebce06817ea8396054551c0cbab18d2646
+Subproject commit 8c2b2c0f9c63e1b7f4971510d8636cedfc076493
diff --git a/nodes/valveGroupControl b/nodes/valveGroupControl
index 618ad27..b20a573 160000
--- a/nodes/valveGroupControl
+++ b/nodes/valveGroupControl
@@ -1 +1 @@
-Subproject commit 618ad27e037abbaefd16e457468241dde6a343a9
+Subproject commit b20a57360d5ac595d11dc1b5b8e8ff5f687a2fdc