WLED_MM_Infinity/.github/copilot-instructions.md

# WLED-MM — ESP32 LED Controller Firmware

WLED is a fast, feature-rich ESP32/ESP8266 webserver for controlling NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI-based chipsets. 
WLED-MM is a fork focused on higher performance (ESP32, ESP32-S3, PSRAM boards), large installs, and advanced audio analysis.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

## Setup

- Node.js 20+ (see `.nvmrc`)
- Install dependencies: `npm ci`
- PlatformIO (required only for firmware compilation): `pip install -r requirements.txt`

## Hardware Targets

| Target | Status |
|---|---|
| ESP32 (classic Xtensa dual-core) | **Primary target** |
| ESP32-S3 | **Primary target** — preferred for larger installs and HUB75 matrix |
| ESP32-S2, ESP32-C3 | Supported |
| ESP32-P4/-C5/-C6 | Will be supported in the future |
| ESP8266 | Deprecated — should still compile, but not actively maintained |

## Build and Test

| Command | Purpose | Typical Time |
|---|---|---|
| `npm run build` | Build web UI → generates `wled00/html_*.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 |

**Always run `npm ci; npm run build` before `pio run`.** The web UI build generates `wled00/html_*.h` header files required by firmware compilation.

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

```text
wled00/                 # Firmware source (C++)
  ├── data/             # Web UI source (HTML, CSS, JS)
  ├── src/              # Core modules, fonts, dependencies
  ├── html_*.h          # Auto-generated (DO NOT EDIT OR COMMIT)
  └── wled.h            # Main firmware configuration, and global variables
usermods/               # Community addons (.h files, included via usermods_list.cpp)
lib/                    # Project specific custom libraries. PlatformIO will compile them to separate static libraries and link them
platformio.ini          # Build targets and configuration
platformio_override.sample.ini # examples for custom build configurations - entries must be copied into platformio_override.ini to use them.
                               # platformio_override.ini is _not_ stored in the WLED repository!

pio-scripts/            # Build tools (platformio)
tools/                  # Build tools (Node.js), partition files, and generic utilities
tools/cdata.js          # Web UI → header build script
tools/cdata-test.js     # Test suite
package.json            # Node.js scripts and release ID
.github/workflows/      # CI/CD pipelines
```

Main development branch: `mdev`

## 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.
- **When unsure, say so.** Gather more information rather than guessing.
- **Acknowledge good patterns** when you see them.
- **Provide references** when making analyses or recommendations. Base them on the correct branch or PR.
- **Look for user-visible "breaking" changes**. Ask for confirmation that these were made intentionally.
- **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.

### 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).
- Make sure AI-generated code is well documented.

### 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.
- **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.