feat(simulator): add GUI runner, stubs, and workspace assets

Add host simulator scaffolding, examples, and docs so led-driver main can run end-to-end with MicroPython module stubs.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,2 +1,48 @@
 # led-simulator
 
+Graphical **NeoPixel** simulator for host Python. It uses the same layout as device flash:
+
+- **`led-driver/src`** → flash root **`/`** (application modules, `patterns/`, `presets.json`, …)
+- **`led-driver/lib`** → **`/lib`** (Microdot, utemplate, …)
+
+It runs the **whole application**: **`led-driver/src/main.py`** as **`__main__`** (`runpy.run_path(..., run_name="__main__")` → `asyncio.run(main(port=…))`). Startup matches the device — **`Settings`**, **`presets.load`**, **default preset** from settings, **`patterns/`**, **Microdot** **`/ws`**, **`presets_loop`**, **UDP hello**. Only **`machine`**, **`neopixel`**, **`network`**, **`utime`**, and **`ubinascii`** are stubbed (`stubs/`).
+
+The GUI sets **`LED_SIM_ROOT`** so **`main.py`** can register the Microdot app for **Stop**, and **`LED_SIM_PORT`** for the HTTP/WebSocket listen port (default **80** on device when unset). On the ESP32 those variables are unset.
+
+## Requirements
+
+- Python 3.10+
+- Tk (e.g. `python3-tk` on Debian/Ubuntu if the window fails to open)
+
+## Run
+
+From the repository root:
+
+```bash
+pipenv install   # optional; Microdot is vendored under led-driver/lib
+python3 led-simulator/gui_main.py
+```
+
+## UI
+
+- **Start** / **Stop**: start or stop the full **`main.py`** process (same code path as the chip).
+- **HTTP / WS port**: Microdot listen port; WebSocket URL **`ws://127.0.0.1:<port>/ws`** (JSON **v1**).
+
+Configure the app like on flash: **`workspace/settings.json`** (patched as device settings path), **`presets.json`** and **`patterns/`** under **`led-simulator/workspace/`** when the simulator creates symlinks from **`src/`**, or edit files directly under **`led-driver/src/`** if you use a real **`patterns/`** directory there.
+
+Example pattern modules: **`led-simulator/examples/`** (`Blink`, `Chase`). Copy into **`patterns/`** as on the device.
+
+## Notes
+
+- Changing the port spinbox only takes effect on the next **Start**.
+- If **`led-driver/src/patterns`** already exists as a normal directory, the simulator leaves it in place.
+
+## Shell (no GUI)
+
+```bash
+cd led-driver/src
+PYTHONPATH="../lib:../../led-simulator/stubs" LED_SIM_ROOT="../../led-simulator" LED_SIM_PORT=8765 \
+  python3 main.py
+```
+
+(Adjust paths from your checkout root; **`LED_SIM_ROOT`** must point at **`led-simulator/`** so **Stop**-style hooks work if you use them.)