feat: device-free Web-UI demo on GitHub Pages

Build a self-contained static demo of the management interface and
publish it to GitHub Pages so the UI can be tried in the browser without
any hardware.

- tools/build_demo.py turns html/ into demo_dist/: rewrites absolute
  asset paths to be document-relative (works from the /leoino/ sub-path),
  disables the service worker, points the cover image at a bundled SVG,
  injects the mock loader + a demo banner, emits index.html + .nojekyll.
- tools/demo/demo-mock.js fakes the WebSocket and every REST endpoint
  (settings, trackinfo, cover, explorer tree, RFID list, version, info,
  trackprogress, ...). Write actions are no-ops. Content is copyright-free
  (public-domain Grimm/Andersen fairy tales + classical works).
- .github/workflows/demo-pages.yml rebuilds and redeploys on every push
  so the demo never goes stale.
- README: live-demo link + local build instructions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fhirschmann

.github/workflows/demo-pages.yml

@@ -0,0 +1,50 @@
+name: Deploy Web-UI demo to GitHub Pages
+
+# Builds a self-contained, device-free demo of the management web interface
+# (mock WebSocket + REST, copyright-free content) and publishes it to GitHub
+# Pages so the UI can be tried out in the browser without any hardware.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "html/**"
+      - "tools/demo/**"
+      - "tools/build_demo.py"
+      - ".github/workflows/demo-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, don't cancel in-progress runs.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build demo
+        run: python3 tools/build_demo.py demo_dist
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: demo_dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -21,4 +21,5 @@ html/locales/*.min.json
 html/REST_API.yaml
 html/js/*.min.min.js
 html/js/swaggerInitializer.min.js
+demo_dist/
 managed_components/

README.md

@@ -86,6 +86,28 @@ fork-specific features. The full interface (default RFID tab shown below, live f
 
 </div>
 
+### // Live demo
+
+Try the web interface in your browser — **no hardware required**:
+
+<div align="center">
+
+**▶ [fhirschmann.github.io/leoino](https://fhirschmann.github.io/leoino/)**
+
+</div>
+
+It is the real management page with a small mock layer that fakes the WebSocket and every
+REST endpoint, filled with copyright-free content (public-domain fairy tales and classical
+works). Every screen is clickable; write actions (save, restart, …) are no-ops. The demo is
+rebuilt and redeployed automatically on every push by
+[`build_demo.py`](tools/build_demo.py) → GitHub Pages, so it never goes stale. To build it
+locally:
+
+```bash
+python3 tools/build_demo.py demo_dist
+python3 -m http.server --directory demo_dist 8000   # open http://localhost:8000/
+```
+
 ## // Differences to upstream
 
 All changes compared to upstream/`dev`, each with a reference to its commit.
@@ -124,7 +146,7 @@ neon logo that doubles as the SVG favicon ([`7be5254`](../../commit/7be5254)):
 | **Listening statistics**: per-day listening time (today / yesterday / 7 d / 30 d) in a 365-day NVS ring buffer, plus a most-played-cards top list — shown in the info dialog (`GET /info`, `GET /topcards`). The info dialog also draws a **30-day bar chart** (inline SVG, themed, no chart lib) and offers a **CSV export** of the full daily series (`GET /stats.csv`, `date,seconds`) | [`af6c8d3`](../../commit/af6c8d3) · [`c2e7d44`](../../commit/c2e7d44) |
 | **Full backup**: export/import all settings + RFID assignments + per-path EQ rules + listening stats as one JSON file; passwords are only included when explicitly ticked, so a shared backup doesn't leak credentials | [`4c90ff4`](../../commit/4c90ff4) · [`646ec5c`](../../commit/646ec5c) |
 | **Home Assistant MQTT discovery**: auto-registers all entities under one HA device — track/status/firmware/WiFi/battery sensors, volume & LED-brightness numbers, lock & ambient-light switches, equalizer select, transport/update/shutdown buttons | [`db73db1`](../../commit/db73db1) |
-| **Apple HomeKit + Siri** (`HOMEKIT_ENABLE`, via [HomeSpan](https://github.com/HomeSpan/HomeSpan)): pair the player straight into the Home app as a bridge with named tiles — **Playback** (play/pause + battery), **Volume** (brightness dimmer) and **Button-lock** — all controllable by Siri and usable in automations. State is mirrored back, so changes from buttons/RFID show up on the iPhone. Each device generates its **own random pairing code** on first boot (persisted in NVS) instead of a shared hard-coded one, so multiple ESPuinos — and everyone running this firmware — stay distinct and private. A dedicated **HomeKit settings section** shows the scannable pairing **QR code** + that setup code and a "reset pairing" button. Pairs over the existing WiFi (no MFi chip needed); the HAP server runs on its own port and the poll task is pinned to core 0 so it never disturbs the audio pipeline on core 1 | [`6387563`](../../commit/6387563) |
+| **Apple HomeKit + Siri** (`HOMEKIT_ENABLE`, via [HomeSpan](https://github.com/HomeSpan/HomeSpan)): pair the player straight into the Home app as a bridge with named tiles — **Playback** (play/pause + battery), **Volume** (brightness dimmer) and **Button-lock** — all controllable by Siri and usable in automations. State is mirrored back, so changes from buttons/RFID show up on the iPhone. Each device generates its **own random pairing code** on first boot (persisted in NVS) instead of a shared hard-coded one, so multiple ESPuinos — and everyone running this firmware — stay distinct and private. A dedicated **HomeKit settings section** shows the scannable pairing **QR code** + that setup code, a "reset pairing" button and an **on/off switch** to disable HomeKit entirely (HomeSpan then never starts, so it costs nothing at boot). HomeSpan now also comes up **lazily after boot** instead of inside `setup()`, so its multi-second start-up no longer stalls the boot LED. Pairs over the existing WiFi (no MFi chip needed); the HAP server runs on its own port and the poll task is pinned to core 0 so it never disturbs the audio pipeline on core 1 | [`6387563`](../../commit/6387563) |
 | **Control tab**: Repeat / Sleep-Timer (live countdown) / Night-Mode / button-lock / FTP start-stop and a Bluetooth-mode picker (Normal / Speaker / Headphones) right in the control tab; mobile-optimised (full-width louder/quieter buttons instead of the fiddly slider) | [`88a742c`](../../commit/88a742c) · [`520815a`](../../commit/520815a) · [`d57f24a`](../../commit/d57f24a) · [`aef1765`](../../commit/aef1765) |
 | **Battery-backed RTC (DS3231)**: optional real-time clock on the external I²C bus so the time stays correct without WiFi/NTP (seeds the clock at boot, NTP disciplines it); time + die-temperature in the info dialog and via MQTT/HA | [`bf90f66`](../../commit/bf90f66) |
 | **State-driven control LEDs**: the optional control LEDs can mirror a runtime state (key-lock / repeat mode / Bluetooth / battery level) instead of a static colour, per-slot configurable, with a master mute (command **121** / MQTT `control_leds`) | [`d12a496`](../../commit/d12a496) |

tools/build_demo.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Build a self-contained ESPuino Web-UI demo for GitHub Pages.
+
+Takes the regular firmware UI in ``html/`` and turns it into a static
+site that needs no ESP32: a mock layer (``tools/demo/demo-mock.js``)
+fakes the WebSocket and every REST endpoint. The result is written to an
+output directory (default ``demo_dist/``) that can be published as the
+Pages artifact.
+
+Transformations applied to ``management.html`` -> ``index.html``:
+  * absolute asset paths (``/css``, ``/js``, ``/logo.svg`` ...) are made
+    document-relative so the site works from a project sub-path
+    (``user.github.io/leoino/``);
+  * the service worker is disabled (it caches device endpoints);
+  * the cover-image URL is pointed at the bundled demo SVG;
+  * the mock script is injected first in <head>;
+  * a "demo" banner is added.
+
+Usage:  python3 tools/build_demo.py [output_dir]
+"""
+import re
+import shutil
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+HTML = ROOT / "html"
+DEMO = ROOT / "tools" / "demo"
+
+# Static asset trees/files copied verbatim from html/ into the demo.
+COPY_ITEMS = [
+    "css", "js", "fonts", "webfonts", "jstree", "locales",
+    "logo.svg", "appicon.svg", "manifest.json",
+]
+
+# Extra demo-only assets.
+DEMO_ASSETS = ["demo-mock.js", "demo-cover.svg", "demo.css"]
+
+
+def transform_html(src: str) -> str:
+    out = src
+
+    # 1) make head asset references document-relative
+    replacements = {
+        'href="/manifest.json"': 'href="manifest.json"',
+        'href="/logo.svg"': 'href="logo.svg"',
+        'href="/appicon.svg"': 'href="appicon.svg"',
+        'href="/favicon.ico"': 'href="favicon.ico"',
+        'href="/css/vendor.min.css"': 'href="css/vendor.min.css"',
+        'src="/js/vendor.min.js"': 'src="js/vendor.min.js"',
+        'src="/logo"': 'src="logo.svg"',
+    }
+    for a, b in replacements.items():
+        out = out.replace(a, b)
+
+    # 2) disable the service worker (it would cache device-only endpoints)
+    out = out.replace("if ('serviceWorker' in navigator) {", "if (false) {")
+
+    # 3) cover image -> bundled demo SVG (avoids http/mixed-content + 404)
+    out = out.replace('"http://" + host + "/cover?"', '"demo-cover.svg?"')
+
+    # 4) inject the mock loader as the very first <head> child, plus demo CSS
+    head_inject = (
+        '<head>\n'
+        '\t<!-- ESPuino demo: mock layer must load before any app code -->\n'
+        '\t<script src="demo-mock.js"></script>\n'
+        '\t<link rel="stylesheet" href="demo.css">\n'
+    )
+    out = out.replace("<head>\n", head_inject, 1)
+
+    # 5) demo banner right after <body>
+    banner = (
+        '\n\t<div id="demoBanner">\n'
+        '\t\t<span class="demo-pill">DEMO</span>\n'
+        '\t\t<span>Statische Vorschau des ESPuino-Webinterface &ndash; kein Geraet verbunden, Aktionen ohne Wirkung.</span>\n'
+        '\t\t<a href="https://github.com/fhirschmann/leoino" target="_blank" rel="noopener">Projekt auf GitHub</a>\n'
+        '\t</div>\n'
+    )
+    out = re.sub(r"(<body[^>]*>)", lambda m: m.group(1) + banner, out, count=1)
+
+    return out
+
+
+def main() -> int:
+    out_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "demo_dist"
+    out_dir = out_dir.resolve()
+
+    if out_dir.exists():
+        shutil.rmtree(out_dir)
+    out_dir.mkdir(parents=True)
+
+    # copy static assets
+    for item in COPY_ITEMS:
+        src = HTML / item
+        if not src.exists():
+            print(f"  skip (missing): {item}")
+            continue
+        dst = out_dir / item
+        if src.is_dir():
+            shutil.copytree(src, dst)
+        else:
+            shutil.copy2(src, dst)
+
+    # demo-only assets
+    for item in DEMO_ASSETS:
+        shutil.copy2(DEMO / item, out_dir / item)
+
+    # transformed entry point
+    html = (HTML / "management.html").read_text(encoding="utf-8")
+    (out_dir / "index.html").write_text(transform_html(html), encoding="utf-8")
+
+    # disable Jekyll so files/dirs starting with "_" are served untouched
+    (out_dir / ".nojekyll").write_text("", encoding="utf-8")
+
+    print(f"Demo built -> {out_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())