Merge branch 'MoonModules:mdev' into mdev

Author: troyhacks

.coderabbit.yaml

@@ -3,10 +3,10 @@
 # CodeRabbit configuration — references existing guideline files to avoid
 # duplicating conventions.  See:
 #   .github/copilot-instructions.md   — project overview & general rules
-#   .github/cpp.instructions.md       — C++ coding conventions
-#   .github/web.instructions.md       — Web UI coding conventions
-#   .github/cicd.instructions.md      — GitHub Actions / CI-CD conventions
-#   .github/esp-idf.instructions.md   — ESP-IDF / chip-specific coding guidelines
+#   docs/cpp.instructions.md          — C++ coding conventions
+#   docs/web.instructions.md          — Web UI coding conventions
+#   docs/cicd.instructions.md         — GitHub Actions / CI-CD conventions
+#   docs/esp-idf.instructions.md      — ESP-IDF / chip-specific coding guidelines
 #                                       (apply when code directly uses ESP-IDF APIs:
 #                                        esp_idf_*, I2S, RMT, ADC, GPIO, heap_caps, etc.)
 #
@@ -17,14 +17,27 @@
 language: en-US
 
 reviews:
+  # generic review setting, see https://docs.coderabbit.ai/reference/configuration#reference
+  auto_apply_labels: true
+  # abort_on_close: false
+  high_level_summary: true
+  review_status: true
+  collapse_walkthrough: false
+  poem: false
+  # sequence_diagrams: false
+  auto_review:
+    enabled: true
+    ignore_title_keywords:
+      - WIP
+
   path_instructions:
     - path: "**/*.{cpp,h,hpp,ino}"
       instructions: >
-        Follow the C++ coding conventions documented in .github/cpp.instructions.md
+        Follow the C++ coding conventions documented in docs/cpp.instructions.md
         and the general project guidelines in .github/copilot-instructions.md.
         If the code under review directly uses ESP-IDF APIs (e.g. heap_caps_malloc,
         I2S, RMT, ADC, GPIO, esp_timer, or any esp_idf_* / soc_* symbols), also
-        apply the guidelines in .github/esp-idf.instructions.md.
+        apply the guidelines in docs/esp-idf.instructions.md.
 
         Key rules: 2-space indentation (no tabs), camelCase functions/variables,
         PascalCase classes, UPPER_CASE macros. Mark WLED-MM-specific changes with
@@ -36,10 +49,10 @@ reviews:
 
     - path: "wled00/data/**"
       instructions: >
-        Follow the web UI conventions documented in .github/web.instructions.md.
+        Follow the web UI conventions documented in docs/web.instructions.md.
 
         Key rules: indent HTML and JavaScript with tabs, CSS with tabs or spaces.
-        Files here are built into wled00/html_*.h by tools/cdata.js — never
+        Files here are built into wled00/html_*.h and wled00/js_*.h by tools/cdata.js — never
         edit those generated headers directly.
 
     - path: "wled00/html_*.h"
@@ -48,17 +61,23 @@ reviews:
         They must never be manually edited or committed. Flag any PR that
         includes changes to these files.
 
+    - path: "wled00/js_*.h"
+      instructions: >
+        These files are auto-generated from wled00/data/ by tools/cdata.js.
+        They must never be manually edited or committed. Flag any PR that
+        includes changes to these files.
+
     - path: "usermods/**"
       instructions: >
         Usermods are community add-ons following the upstream WLED 0.15.x style.
         Each usermod lives in its own directory under usermods/ and is implemented
         as a .h file that is pulled in by wled00/usermods_list.cpp (guarded by
         #ifdef). Usermods do not use library.json. Follow the same C++ conventions
-        as the core firmware (.github/cpp.instructions.md).
+        as the core firmware (docs/cpp.instructions.md).
 
     - path: ".github/workflows/*.{yml,yaml}"
       instructions: >
-        Follow the CI/CD conventions documented in .github/cicd.instructions.md.
+        Follow the CI/CD conventions documented in docs/cicd.instructions.md.
 
         Key rules: 2-space indentation, descriptive name: on every workflow/job/step.
         Third-party actions must be pinned to a specific version tag — branch pins
@@ -67,7 +86,7 @@ reviews:
         into run: steps — pass them through an env: variable to prevent script
         injection. Do not use pull_request_target unless fully justified.
 
-    - path: ".github/*.instructions.md"
+    - path: "**/*.instructions.md"
       instructions: |
         This file contains both AI-facing rules and human-only reference sections.
         Human-only sections are enclosed in `<!-- HUMAN_ONLY_START -->` /
@@ -81,4 +100,14 @@ reviews:
         2. Flag any HUMAN_ONLY section whose content has drifted from the surrounding
            AI-facing rules due to edits introduced in this PR.
         3. If new AI-facing rules were added without updating a related HUMAN_ONLY
-           reference section, note this as a suggestion (not a required fix).
+           reference section, note this as a suggestion (not a required fix).
+
+  finishing_touches:
+    # Docstrings | Options for generating Docstrings for your PRs/MRs.
+    docstrings:
+      # Docstrings | Allow CodeRabbit to generate docstrings for PRs/MRs.
+      # default: true - disabled in WLED-MM: has caused confusion in the past
+      enabled: false
+    unit_tests:
+      # default: true - disabled in WLED-MM: we don't have a unit test framework, this option just confuses contributors
+      enabled: false

.github/ISSUE_TEMPLATE/bug.yml

@@ -5,7 +5,9 @@ body:
   - type: markdown
     attributes:
       value: |
-        Please quickly search existing issues first before submitting a bug.
+        Please quickly search existing issues first before submitting a bug.  
+        Please don't submit long error analyses created by an AI agent, these are often totally wrong.  
+        Just describe the problem in your own words.
   - type: textarea
     id: what-happened
     attributes:

.github/agent-build.instructions.md

@@ -11,7 +11,7 @@ Use these timeout values when running builds:
 
 | Command | Typical Time | Minimum Timeout | Notes |
 |---|---|---|---|
-| `npm run build` | ~3 s | 30 s | Web UI → `wled00/html_*.h` headers |
+| `npm run build` | ~3 s | 30 s | Web UI → `wled00/html_*.h` `wled00/js_*.h` headers |
 | `npm test` | ~40 s | 2 min | Validates build system |
 | `npm run dev` | continuous | — | Watch mode, auto-rebuilds on changes |
 | `pio run -e <env>` | 15–20 min | 30 min | First build downloads toolchains; subsequent builds are faster |
@@ -20,16 +20,21 @@ Use these timeout values when running builds:
 
 ## Development Workflow
 
+### Code Style Summary
+- **C++** files in `wled00/` and `usermods/`: 2-space indentation (no tabs), camelCase functions/variables, PascalCase classes, UPPER_CASE macros. No C++ exceptions — use return codes and debug macros.
+- **Web UI** files in `wled00/data`: indent HTML and JavaScript with tabs, CSS with tabs.
+- **CI/CD workflows** in `.github/workflows`: 2-space indentation, descriptive `name:` on every workflow/job/step. Third-party actions must be pinned to a specific version tag — branch pins such as `@main` or `@master` are not allowed. SHA pinning recommended.
+
 ### Web UI Changes
 
 1. Edit files in `wled00/data/`
-2. Run `npm run build` to regenerate `wled00/html_*.h` headers
+2. Run `npm run build` to regenerate `wled00/html_*.h` `wled00/js_*.h` headers
 3. Test with local HTTP server (see Manual Testing below)
 4. Run `npm test` to validate
 
 ### Firmware Changes
 
-1. Edit files in `wled00/` (but **never** `html_*.h` files)
+1. Edit files in `wled00/` (but **never** `html_*.h` and `js_*.h` files)
 2. Ensure web UI is built first: `npm run build`
 3. Build firmware: `pio run -e esp32_4MB_V4_M` (set timeout ≥ 30 min)
 4. Flash to device: `pio run -e [target] --target upload`
@@ -85,8 +90,8 @@ Test these scenarios after every web UI change:
 ### Recovery Steps
 
 - **Force web UI rebuild**: `npm run build -- -f`
-- **Clear generated files**: `rm -f wled00/html_*.h` then `npm run build`
-- **Clean PlatformIO cache**: `pio run --target clean`
+- **Clear generated files**: `rm -f wled00/html_*.h wled00/js_*.h` then `npm run build`
+- **Clean PlatformIO build artifacts**: `pio run --target clean`
 - **Reinstall Node deps**: `rm -rf node_modules && npm ci`
 
 ## CI/CD Validation
@@ -106,7 +111,8 @@ Match this workflow in local development to catch failures before pushing.
 
 ## Important Reminders
 
-- **Never edit or commit** `wled00/html_*.h` — auto-generated from `wled00/data/`
+- Always **commit source code**
+- **Never edit or commit** `wled00/html_*.h` and  `wled00/js_*.h` — auto-generated from `wled00/data/`
 - Web UI rebuild is part of the PlatformIO firmware compilation pipeline
-- Common firmware environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S3_8MB_PSRAM_M_qspi`, `esp32_16MB_V4_M_eth`, `esp8266_4MB_S` (deprecated), `esp32dev_compat`
+- Common firmware environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S3_8MB_PSRAM_M_qspi`, `esp32S3_16MB_PSRAM_M_HUB75`, `esp32_16MB_V4_M_eth` (ethernet support), `esp32_16MB_V4_M_debug` (debug), `esp8266_4MB_S` (deprecated), `esp32dev_compat` (V3 legacy framework)
 - List all PlatformIO targets: `pio run --list-targets`

.github/copilot-instructions.md

@@ -33,29 +33,28 @@ Always reference these instructions first and fallback to search or bash command
 
 | Command | Purpose | Typical Time |
 |---|---|---|
-| `npm run build` | Build web UI → generates `wled00/html_*.h` headers | ~3 s |
+| `npm run build` | Build web UI → generates `wled00/html_*.h` and `wled00/js_*.h` headers | ~3 s |
 | `npm test` | Run test suite | ~40 s |
 | `npm run dev` | Watch mode — auto-rebuilds web UI on file changes | — |
 | `pio run -e <env>` | Build firmware for a hardware target | 15–20 min |
 
 <!-- HUMAN_ONLY_END -->
 
-**Always run `npm ci; npm run build` before `pio run`.** The web UI build generates `wled00/html_*.h` header files required by firmware compilation.
-**Build firmware to validate code changes**: `pio run -e esp32_4MB_V4_M` — must succeed, never skip this step.
-Common firmware environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S3_8MB_PSRAM_M_qspi`, `esp32_16MB_V4_M_eth`, `esp32dev_compat`, `esp8266_4MB_S` (deprecated)
+- **Always run `npm run build` before any `pio run`** (and run `npm ci` first on fresh clones or when lockfile/dependencies change).
+- The web UI build generates required `wled00/html_*.h` and `wled00/js_*.h` headers for firmware compilation.
+- **Build firmware to validate code changes**: `pio run -e esp32_4MB_V4_M` — must succeed, never skip this step.
+- Common firmware environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S3_8MB_PSRAM_M_qspi`, `esp32_16MB_V4_M_eth`, `esp32dev_compat`, `esp8266_4MB_S` (deprecated)
 
 For detailed build timeouts, development workflows, troubleshooting, and validation steps, see [agent-build.instructions.md](agent-build.instructions.md).
 
 ## Repository Structure
 
 tl;dr: 
-* Firmware source: `wled00/` (C++).
-* Build targets: `platformio.ini`.
-* Web UI source: `wled00/data/`.
-* Auto-generated headers: `wled00/html_*.h` — **never edit or commit**.
-* ArduinoJSON + AsyncJSON: `wled00/src/dependencies/json`
+* Firmware source: `wled00/` (C++). Web UI source: `wled00/data/`. Build targets: `platformio.ini`.
+* Auto-generated headers: `wled00/html_*.h` and `wled00/js_*.h` — **never edit or commit**.
+* ArduinoJSON + AsyncJSON: `wled00/src/dependencies/json` (included via `wled.h`). CI/CD: `.github/workflows/`.
 * Usermods: `usermods/` (`.h` files, included via `usermods_list.cpp`).
-* CI/CD: `.github/workflows/`.
+* Contributor docs: `docs/` (coding guidelines, design docs).
 
 Main development trunk: `mdev` branch. Make PRs against this branch.
 
@@ -79,31 +78,60 @@ tools/                      # Build tools (Node.js), partition files, and generi
 tools/cdata.js              # Web UI → header build script
 tools/cdata-test.js         # Test suite
 package.json                # Node.js scripts and release ID
+docs/                       # Contributor docs: coding guidelines and design documentation
 .github/workflows/          # CI/CD pipelines
 ```
-<!-- HUMAN_ONLY_END -->
 
+<!-- HUMAN_ONLY_END -->
 ## General Guidelines
 
-- **Never edit or commit** `wled00/html_*.h` — auto-generated from `wled00/data/`.
 - **Repository language is English.** Suggest translations for non-English content.
 - **Use VS Code with PlatformIO extension** for best development experience.
+- **Never edit or commit** `wled00/html_*.h` and `wled00/js_*.h` — auto-generated from `wled00/data/`.
 - **When unsure, say so.** Gather more information rather than guessing.
-- **Acknowledge good patterns** when you see them. Summarize good practices as part of your review - positive feedback always helps.
+- **Acknowledge good patterns** when you see them. Positive feedback always helps.
 - **Provide references** when making analyses or recommendations. Base them on the correct branch or PR.
-- **Look for user-visible breaking changes and ripple effects**. Ask for confirmation that these were introduced intentionally.
+- **Highlight user-visible breaking changes and ripple effects**. Ask for confirmation that these were introduced intentionally.
 - **Unused / dead code must be justified or removed**. This helps to keep the codebase clean, maintainable and readable.
 - **C++ formatting available**: `clang-format` is installed but not in CI
-- No automated linting is configured — match existing code style in files you edit. See `cpp.instructions.md` and `web.instructions.md` for language-specific conventions, and `cicd.instructions.md` for GitHub Actions workflows.
+- No automated linting is configured — match existing code style in files you edit. 
+
+Refer to `docs/cpp.instructions.md`, `docs/esp-idf.instructions.md` and `docs/web.instructions.md` for language-specific conventions, and `docs/cicd.instructions.md` for GitHub Actions workflows.
+
+### Feature Flags
+- **Verify feature-flag names.** Every `WLED_ENABLE_*` / `WLED_DISABLE_*` flag must exactly match one of the names below — misspellings are silently ignored by the preprocessor (e.g. `WLED_IR_DISABLE` instead of `WLED_DISABLE_INFRARED`), causing silent build variations. Flag unrecognised names as likely typos and suggest the correct spelling.
+
+**`WLED_DISABLE_*`**: `2D`, `ADALIGHT`, `ALEXA`, `BROWNOUT_DET`, `ESPNOW`, `FILESYSTEM`, `HUESYNC`, `IMPROV_WIFISCAN`, `INFRARED`, `LOXONE`, `MQTT`, `OTA`, `PARTICLESYSTEM1D`, `PARTICLESYSTEM2D`, `PIXELFORGE`, `WEBSOCKETS`
+
+**`WLED_ENABLE_*`**: `ADALIGHT`, `AOTA`, `DMX`, `DMX_INPUT`, `DMX_OUTPUT`, `FS_EDITOR`, `GIF`, `HUB75MATRIX`, `JSONLIVE`, `LOXONE`, `MQTT`, `PIXART`, `PXMAGIC`, `USERMOD_PAGE`, `WEBSOCKETS`, `WPA_ENTERPRISE`
+
+<!-- HUMAN_ONLY_START -->
+```cpp
+#ifdef WLED_DMX_ENABLED // wrong flag - initialization silently skipped
+  initDMX();
+#endif
+
+#ifdef WLED_ENABLE_DMX // correct flag - initialization performed only when the build supports DMX
+  initDMX();  
+#endif
+```
+<!-- HUMAN_ONLY_END -->
+
 
 ### Attribution for AI-generated code
 Using AI-generated code can hide the source of the inspiration / knowledge / sources it used. 
 - Document attribution of inspiration / knowledge / sources used in the code, e.g. link to GitHub repositories or other websites describing the principles / algorithms used.
-- When a larger block of code is generated by an AI tool, mark it with an `// AI: below section was generated by an AI` comment (see C++ guidelines).
+- When a larger block of code is generated by an AI tool, embed it into `// AI: below section was generated by an AI` ... `// AI: end` comments (see C++ guidelines).
 - Every non-trivial AI-generated function should have a brief comment describing what it does. Explain parameters when their names alone are not self-explanatory.
-- AI-generated code must be well documented; comment-to-code ratio > 15% is expected. Do not rephrase source code, but explain the concepts/logic behind the code.
+- AI-generated code must be well documented with meaningful comments that explain intent, assumptions, and non-obvious logic. Do not rephrase source code; explain concepts and reasoning.
 
 ### Pull Request Expectations
 
 - **No force-push on open PRs.** Once a pull request is open and being reviewed, do not force-push (`git push --force`) to the branch. Force-pushing rewrites history that reviewers may have already commented on, making it impossible to track incremental changes. Use regular commits or `git merge` to incorporate feedback; the branch will be squash-merged when it is accepted.
+- **Modifications to ``platformio.ini`` MUST be approved explicitly** by a *maintainer* or *WLED organisation Member*. Modifications to the global build environment may break github action builds. Always flag them.
 - **Document your changes in the PR.** Every pull request should include a clear description of *what* changed and *why*. If the change affects user-visible behavior, describe the expected impact. Link to related issues where applicable. Provide screenshots to showcase new features.
+
+### Supporting Reviews and Discussions
+- **For "is it worth doing?" debates** about proposed reliability, safety, or data-integrity mechanisms (CRC checks, backups, power-loss protection): suggest a software **FMEA** (Failure Mode and Effects Analysis). 
+  Clarify the main feared events, enumerate failure modes, assess each mitigation's effectiveness per failure mode, note common-cause failures, and rate credibility for the typical WLED use case.
+