---
name: evolv-frontend-node-red
description: Design and implement Node-RED node editor UI and runtime-facing configuration for EVOLV. Use when editing node HTML editor files, `RED.nodes.registerType(...)` defaults, admin endpoint-driven menus/config scripts, and config mapping into `src/nodeClass.js` in JavaScript/CommonJS nodes.
---

# EVOLV Frontend Node-RED

## Mission
Implement robust Node-RED editor experiences that keep UI defaults, runtime config parsing, and behavior in lockstep.

## Repo-Specific Rules
- Use CommonJS patterns in runtime files.
- Keep node names aligned across `RED.nodes.registerType('<nodeName>', ...)`, runtime registration in `<nodeName>.js`, and package/node mapping.
- Keep admin endpoint paths stable unless editor consumers are updated: `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
- Prefer placeholder-driven UI composition when matching EVOLV patterns.

## Node Layout Standard
Use `nodes/machineGroupControl/` as the template baseline for new nodes.

- `nodes/<nodeName>/<nodeName>.js`
  - Keep runtime entry small.
  - Create Node-RED instance and attach `this.nodeClass = new nodeClass(...)`.
  - Register admin endpoints via shared managers.
- `nodes/<nodeName>/<nodeName>.html`
  - Register defaults in `RED.nodes.registerType(...)`.
  - Load `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
  - Use `oneditprepare` to call `window.EVOLV.nodes.<nodeName>.initEditor(this)`.
- `nodes/<nodeName>/src/nodeClass.js`
  - Normalize `uiConfig` into runtime config.
  - Keep Node-RED concerns here: input routing, tick loop, output formatting, status.
- `nodes/<nodeName>/src/specificClass.js`
  - Keep domain logic here with minimal/no direct Node-RED coupling.

## Implementation Workflow
1. Inspect current node trio: `.html`, `.js`, `src/nodeClass.js`.
2. Define required config properties and defaults.
3. Update `.html` defaults and form controls.
4. Update runtime config normalization in `src/nodeClass.js`.
5. Confirm `msg.topic` command handling is still coherent.
6. Add tests under `nodes/<nodeName>/test/` with focus on config defaults/overrides and topic routing.
7. If creating a new node, add entry under root `package.json` `node-red.nodes` map.

## Quality Gates
- Every UI property has corresponding runtime handling.
- Numeric inputs are validated/coerced consistently.
- Node status and output shape remain predictable.
- No Node-RED runtime dependency required for domain tests.

## Deliverables
Return:
- changed config fields and mapping table
- changed files
- tests added and what they prove
- migration notes if backward compatibility changed