# ForkDrift Build Configurator

Static web UI for picking firmware features, previewing settings and screens, and exporting build configuration.

| URL | Use |
|-----|-----|
| [Published copy](https://unintendedsideeffects.github.io/ForkDrift-crosspointReader/configurator/) | GitHub Pages |
| `http://localhost:3000/configurator/` | Local browser-sync (default port; see startup output if busy) |
| `http://<LAN-IP>:3000/configurator/` | Cursor embedded browser (if `localhost` fails; LAN port matches startup output) |

The docs root [`../index.html`](../index.html) redirects here.

## Local development

```bash
cd crosspoint-reader/docs/configurator
npm install   # first time only
npm run dev
```

`npm run dev` starts [browser-sync](https://browsersync.io/) serving the `crosspoint-reader/docs/` tree with start path `/configurator/`. Live reload watches `index.html`. browser-sync prints the LAN URL on startup.

From the ForkDrift monorepo root, the same path is `crosspoint-reader/docs/configurator`.

## Generated assets

| File | Regenerate with |
|------|-----------------|
| `settings-schema.generated.js` | `uv run python scripts/generate_configurator_settings_schema.py` (from `crosspoint-reader/`) |
| `screen-previews/manifest.json` + PNGs | See [Screen previews](#screen-previews) |

Check schema freshness without writing:

```bash
cd crosspoint-reader
uv run python scripts/generate_configurator_settings_schema.py --check
```

Or from this directory:

```bash
npm run schema:check
npm run schema:generate
```

The schema is compiled from firmware settings code (`CrossPointSettings.cpp`, `JsonSettingsIO.cpp`) via a host-side exporter in `test/tools/export_configurator_settings_schema.cpp`.

## Screen previews

Preview images under `screen-previews/` are generated by the firmware UI harness, not hand-edited.

From `crosspoint-reader/`:

```bash
tools/screen-harness/render_screens.sh build/screen-previews
tools/screen-harness/pbm_to_png.py build/screen-previews docs/configurator/screen-previews
python tools/screen-harness/write_preview_manifest.py docs/configurator/screen-previews
```

CI runs the equivalent workflow (`.github/workflows/update-screen-previews.yml`). The configurator reads `screen-previews/manifest.json` and maps home themes via `home_themes`.

## After configuring

Generate `platformio-custom.ini`, then build:

```bash
cd crosspoint-reader
uv run python scripts/generate_build_config.py --profile standard
uv run pio run -e custom
```

From the ForkDrift monorepo root: `./build-firmware.sh standard`

See [BUILD_CONFIGURATION.md](../BUILD_CONFIGURATION.md) for profiles, feature flags, and GitHub Actions builds.