Refactoring for better maintenance and improve reliability

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npm run validate:config
+      - run: npm run build

.gitignore

@@ -3,3 +3,4 @@ node_modules
 .vscode
 build/*.map
 tmp/
+

CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to ESP3D-Configurator
+
+Thank you for helping improve the configurator. This guide covers local development; the configuration schema is documented in [API.md](API.md).
+
+## Getting started
+
+### Requirements
+
+- Node.js **20+**
+- npm
+
+### Setup
+
+```bash
+git clone https://github.com/luc-github/ESP3D-Configurator.git
+cd ESP3D-Configurator
+npm ci
+npm run dev
+```
+
+The `dev` script runs the webpack dev server and the small Express server in `config/server.js`. Use the URL from the terminal output.
+
+Production build (static site, e.g. GitHub Pages):
+
+```bash
+npm run build
+```
+
+Output is under `build/` (mainly `index.html` and bundled assets).
+
+## Scripts
+
+| Command | When to use |
+|---------|-------------|
+| `npm run dev` | Day-to-day UI work |
+| `npm run build` | Before PR; verify production bundle |
+| `npm run validate:config` | After editing any `src/configuration/tabs/*.json` or `boardPresets.json` |
+| `npm run sync:pin-roles` | After editing `pinUsageRoles.json` (writes `pinRole` into tab JSON) |
+| `npm run check:esp3d` | Optional: compare camera models to a local ESP3D clone in `tmp/esp3d` |
+
+## Pull request checklist
+
+- [ ] `npm run validate:config` passes
+- [ ] `npm run build` passes (same as CI)
+- [ ] New field ids are **unique** across all tab JSON files
+- [ ] New UI strings added to `src/translations/en.json`
+- [ ] Manually tested: affected wizard tab(s), Download preview, import/preset if touched
+- [ ] [API.md](API.md) updated if you change schema, export format, presets, or tooling
+
+CI (`.github/workflows/ci.yml`) runs `validate:config` + `build` on pushes and PRs to `main` / `master`.
+
+## Common change types
+
+### New firmware option (define)
+
+1. Add control in the right `src/configuration/tabs/<section>.json`.
+2. Set `define`, `type`, `setting`, `depend` as needed.
+3. Confirm the macro exists in [ESP3D](https://github.com/luc-github/ESP3D) firmware.
+4. See **Quick checklist: new feature flag** in [API.md](API.md).
+
+### New board preset
+
+1. Edit `src/configuration/boardPresets.json`.
+2. `npm run validate:config`
+3. Test on Features → preset dropdown.
+
+### Pin / GPIO behaviour
+
+- Lists: `src/tabs/step/pins.json`, `ports.json`
+- MCU rules: `pinCapabilities.js`, `mcuPinDefaults.js`, `psramReservedPins.js`
+- Roles: `pinUsageRoles.json` + `npm run sync:pin-roles`
+
+Details: [API.md — Pin and port allocation](API.md#pin-and-port-allocation).
+
+### Import / snapshot format
+
+Logic: `src/configuration/configurationSnapshot.js`. Do not break markers `ESP3D_CONFIG_SNAPSHOT_BEGIN` / `END` without a version bump and migration note in API.md.
+
+## Optional: ESP3D reference tree
+
+To run `npm run check:esp3d`:
+
+```text
+tmp/
+  esp3d/          # clone of ESP3D repo
+  platformio.ini  # optional reference copy
+```
+
+## Code style
+
+- Match existing patterns in the file you edit (Preact, Spectre CSS, JSON-driven config).
+- Prefer small, focused diffs; avoid unrelated refactors in the same PR.
+- Comments only for non-obvious behaviour (see project conventions in existing modules).
+
+## Questions
+
+Open a [GitHub issue](https://github.com/luc-github/ESP3D-Configurator/issues) for bugs or feature discussion. For schema questions, cite [API.md](API.md) and the relevant `tabs/*.json` path.

README.md

@@ -3,25 +3,67 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-Project of Web Configurator to generate ESP3D configuration file.
+Web configurator to build **ESP3D 3.x** firmware settings: wizard UI → `configuration.h` and `platformio.ini`.
 
-Using github-action / issues form bring too many constraints with not really great user experience, so I went for
-a standalone html file instead, and it is hosted in github static page area
-It use same element as ESP3D-WebUI to save development time (yeah I am super lazy...):
+**Live demo:** [luc-github.github.io](https://luc-github.github.io/)
 
--   nodejs
--   webpack
--   spectre.css
--   Preact
+## Features (overview)
 
-It should be something similar to https://www.repetier.com/firmware/v100/index.php but in one static page so it should work online hosted by github or offline on user PC
+- Step-by-step wizard (Features, Network, Filesystems, Devices, …)
+- Board **presets** and **import** of a previous `configuration.h` (JSON snapshot at end of file)
+- Pin conflict detection before download
+- Light / dark UI theme
 
-> [!WARNING]
->### Disclaimer
-> The software is provided 'as is,' without any warranty of any kind, expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. 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.
->It is essential that you carefully read and understand this disclaimer before using this software and its components. If you do not agree with any part of this disclaimer, please refrain from using the software.  
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [API.md](API.md) | Configuration schema, tabs, pins, export/import, presets, planned work |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, npm scripts, PR checklist, CI |
+
+## Development
+
+**Requirements:** Node.js 20+, npm.
+
+```bash
+npm ci
+npm run dev      # local development
+npm run build    # production bundle in build/
+```
+
+**Quality checks (run before a PR):**
+
+```bash
+npm run validate:config
+npm run build
+```
+
+CI runs the same steps on GitHub Actions (see `.github/workflows/ci.yml`).
+
+### Stack
 
-The configurator is available [here](https://luc-github.github.io/)
+- Node.js, webpack
+- [Preact](https://preactjs.com/)
+- [Spectre.css](https://picturepan2.github.io/spectre/)
+
+The UI reuses patterns from ESP3D-WebUI to keep maintenance aligned across projects.
+
+## Using the configurator (makers)
+
+1. Walk the wizard tabs and set your board (MCU, flash, WiFi, pins, …).
+2. On **Download**, resolve any **pin conflicts**, then download `configuration.h` and `platformio.ini`.
+3. To restore settings later: **Features** → **Import configuration.h** (file must have been generated by this tool so the JSON snapshot is present).
+
+See [API.md — Configuration snapshot](API.md#configuration-snapshot-in-configurationh-only) for technical details.
+
+## Project history
+
+GitHub issue forms were dropped in favour of a **single static page** (works hosted on GitHub Pages or offline), similar in spirit to [Repetier’s firmware configurator](https://www.repetier.com/firmware/v100/index.php).
+
+> [!WARNING]
+> ### Disclaimer
+> The software is provided "as is," without any warranty of any kind, expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. 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.
+> It is essential that you carefully read and understand this disclaimer before using this software and its components. If you do not agree with any part of this disclaimer, please refrain from using the software.
 
 ## Contributors ✨
 
@@ -43,4 +85,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

docs/esp3d-camera-custom-pins.md

@@ -0,0 +1,14 @@
+# ESP3D — Camera CUSTOM pins and configurator
+
+When **Camera type = Custom**, the configurator emits camera GPIO overrides in `configuration.h`:
+
+```c
+#define CAMERA_DEVICE CAMERA_MODEL_CUSTOM
+#define PWDN_GPIO_NUM 32
+#define XCLK_GPIO_NUM 0
+// ...
+```
+
+ESP3D loads `configuration.h` before `esp3d_pins.h`. The firmware **CUSTOM** pin block must use `#ifndef` / `#define` / `#endif` so these values take effect (see ESP3D `esp3d/src/include/esp3d_pins.h`).
+
+Predefined models use fixed maps in firmware; the configurator shows those pins read-only from `src/configuration/cameraPinMaps.json`.

info.json

@@ -1,3 +1,3 @@
 {
-    "version": "1.0.34"
+    "version": "1.1.0"
   }

package.json

@@ -8,7 +8,10 @@
     "front": "webpack serve --config config/webpack.dev.js ",
     "server": "nodemon config/server.js",
     "dev": "concurrently \"npm run server\" \"npm run front\"",
-    "build": "webpack --config config/webpack.prod.js"
+    "build": "webpack --config config/webpack.prod.js",
+    "validate:config": "node tools/validate_configuration.js",
+    "sync:pin-roles": "node tools/sync_pin_roles.js",
+    "check:esp3d": "node tools/check_esp3d_reference.js"
   },
   "author": "",
   "license": "ISC",

src/components/App/version.js

@@ -16,4 +16,4 @@
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 import { h } from "preact"
-export const Version = "1.0.34"
+export const Version = "1.1.0"