Add demo mode: virtual hardware sandbox for testing without real devices

Demo mode provides a complete sandbox environment with:
- Virtual capture engine (radial rainbow test pattern on 3 displays)
- Virtual audio engine (synthetic music-like audio on 2 devices)
- Virtual LED device provider (strip/60, matrix/256, ring/24 LEDs)
- Isolated data directory (data/demo/) with auto-seeded sample entities
- Dedicated config (config/demo_config.yaml) with pre-configured API key
- Frontend indicator (DEMO badge + dismissible banner)
- Engine filtering (only demo engines visible in demo mode)
- Separate entry point: python -m wled_controller.demo (port 8081)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plans/demo-mode/CONTEXT.md

@@ -0,0 +1,30 @@
+# Feature Context: Demo Mode
+
+## Current State
+Starting implementation. No changes made yet.
+
+## Key Architecture Notes
+- `EngineRegistry` (class-level dict) holds capture engines, auto-registered in `capture_engines/__init__.py`
+- `AudioEngineRegistry` (class-level dict) holds audio engines, auto-registered in `audio/__init__.py`
+- `LEDDeviceProvider` instances registered via `register_provider()` in `led_client.py`
+- Already has `MockDeviceProvider` + `MockClient` (device type "mock") for testing
+- Config is `pydantic_settings.BaseSettings` in `config.py`, loaded from YAML + env vars
+- Frontend header in `templates/index.html` line 27-31: title + version badge
+- Frontend bundle: `cd server && npm run build` (esbuild)
+- Data stored as JSON in `data/` directory, paths configured via `StorageConfig`
+
+## Temporary Workarounds
+- None yet
+
+## Cross-Phase Dependencies
+- Phase 1 (config flag) is foundational — all other phases depend on `is_demo_mode()`
+- Phase 2 & 3 (engines) can be done independently of each other
+- Phase 4 (seed data) depends on knowing what entities to create, which is informed by phases 2-3
+- Phase 5 (frontend) depends on the system info API field from phase 1
+- Phase 6 (engine resolution) depends on engines existing from phases 2-3
+
+## Implementation Notes
+- Demo mode activated via `WLED_DEMO=true` env var or `demo: true` in YAML config
+- Isolated data directory `data/demo/` keeps demo entities separate from real config
+- Demo engines use `ENGINE_TYPE = "demo"` and are always registered but return `is_available() = True` only in demo mode
+- The existing `MockDeviceProvider`/`MockClient` can be reused or extended for demo device output

plans/demo-mode/PLAN.md

@@ -0,0 +1,44 @@
+# Feature: Demo Mode
+
+**Branch:** `feature/demo-mode`
+**Base branch:** `master`
+**Created:** 2026-03-20
+**Status:** 🟡 In Progress
+**Strategy:** Big Bang
+**Mode:** Automated
+**Execution:** Orchestrator
+
+## Summary
+Add a demo mode that allows users to explore and test the app without real hardware. Virtual capture engines, audio engines, and device providers replace real hardware. An isolated data directory with seed data provides a fully populated sandbox. A visual indicator in the UI makes it clear the app is running in demo mode.
+
+## Build & Test Commands
+- **Build (frontend):** `cd server && npm run build`
+- **Typecheck (frontend):** `cd server && npm run typecheck`
+- **Test (backend):** `cd server && python -m pytest ../tests/ -x`
+- **Server start:** `cd server && python -m wled_controller.main`
+
+## Phases
+
+- [x] Phase 1: Demo Mode Config & Flag [domain: backend] → [subplan](./phase-1-config-flag.md)
+- [x] Phase 2: Virtual Capture Engine [domain: backend] → [subplan](./phase-2-virtual-capture-engine.md)
+- [x] Phase 3: Virtual Audio Engine [domain: backend] → [subplan](./phase-3-virtual-audio-engine.md)
+- [x] Phase 4: Demo Device Provider & Seed Data [domain: backend] → [subplan](./phase-4-demo-device-seed-data.md)
+- [x] Phase 5: Frontend Demo Indicator & Sandbox UX [domain: fullstack] → [subplan](./phase-5-frontend-demo-ux.md)
+- [x] Phase 6: Demo-only Engine Resolution [domain: backend] → [subplan](./phase-6-engine-resolution.md)
+
+## Phase Progress Log
+
+| Phase | Domain | Status | Review | Build | Committed |
+|-------|--------|--------|--------|-------|-----------|
+| Phase 1: Config & Flag | backend | ✅ Done | ✅ | ✅ | ⬜ |
+| Phase 2: Virtual Capture Engine | backend | ✅ Done | ✅ | ✅ | ⬜ |
+| Phase 3: Virtual Audio Engine | backend | ✅ Done | ✅ | ✅ | ⬜ |
+| Phase 4: Demo Device & Seed Data | backend | ✅ Done | ✅ | ✅ | ⬜ |
+| Phase 5: Frontend Demo UX | fullstack | ✅ Done | ✅ | ✅ | ⬜ |
+| Phase 6: Engine Resolution | backend | ✅ Done | ✅ | ✅ | ⬜ |
+
+## Final Review
+- [ ] Comprehensive code review
+- [ ] Full build passes
+- [ ] Full test suite passes
+- [ ] Merged to `master`

plans/demo-mode/phase-1-config-flag.md

@@ -0,0 +1,42 @@
+# Phase 1: Demo Mode Config & Flag
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Add a `demo` boolean flag to the application configuration and expose it to the frontend via the system info API. When demo mode is active, the server uses an isolated data directory so demo entities don't pollute real user data.
+
+## Tasks
+
+- [ ] Task 1: Add `demo: bool = False` field to `Config` class in `config.py`
+- [ ] Task 2: Add a module-level helper `is_demo_mode() -> bool` in `config.py` for easy import
+- [ ] Task 3: Modify `StorageConfig` path resolution: when `demo=True`, prefix all storage paths with `data/demo/` instead of `data/`
+- [ ] Task 4: Expose `demo_mode: bool` in the existing `GET /api/v1/system/info` endpoint response
+- [ ] Task 5: Add `WLED_DEMO=true` env var support (already handled by pydantic-settings env prefix `WLED_`)
+
+## Files to Modify/Create
+- `server/src/wled_controller/config.py` — Add `demo` field, `is_demo_mode()` helper, storage path override
+- `server/src/wled_controller/api/routes/system.py` — Add `demo_mode` to system info response
+- `server/src/wled_controller/api/schemas/system.py` — Add `demo_mode` field to response schema
+
+## Acceptance Criteria
+- `Config(demo=True)` is accepted; default is `False`
+- `WLED_DEMO=true` activates demo mode
+- `is_demo_mode()` returns the correct value
+- When demo mode is on, all storage files resolve under `data/demo/`
+- `GET /api/v1/system/info` includes `demo_mode: true/false`
+
+## Notes
+- The env var will be `WLED_DEMO` because of `env_prefix="WLED_"` in pydantic-settings
+- Storage path override should happen at `Config` construction time, not lazily
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->

plans/demo-mode/phase-2-virtual-capture-engine.md

@@ -0,0 +1,48 @@
+# Phase 2: Virtual Capture Engine
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Create a `DemoCaptureEngine` that provides virtual displays and produces animated test pattern frames, allowing screen capture workflows to function in demo mode without real monitors.
+
+## Tasks
+
+- [ ] Task 1: Create `server/src/wled_controller/core/capture_engines/demo_engine.py` with `DemoCaptureEngine` and `DemoCaptureStream`
+- [ ] Task 2: `DemoCaptureEngine.ENGINE_TYPE = "demo"`, `ENGINE_PRIORITY = 1000` (highest in demo mode)
+- [ ] Task 3: `is_available()` returns `True` only when `is_demo_mode()` is True
+- [ ] Task 4: `get_available_displays()` returns 3 virtual displays:
+  - "Demo Display 1080p" (1920×1080)
+  - "Demo Ultrawide" (3440×1440)
+  - "Demo Portrait" (1080×1920)
+- [ ] Task 5: `DemoCaptureStream.capture_frame()` produces animated test patterns:
+  - Horizontally scrolling rainbow gradient (simple, visually clear)
+  - Uses `time.time()` for animation so frames change over time
+  - Returns proper `ScreenCapture` with RGB numpy array
+- [ ] Task 6: Register `DemoCaptureEngine` in `capture_engines/__init__.py`
+
+## Files to Modify/Create
+- `server/src/wled_controller/core/capture_engines/demo_engine.py` — New file: DemoCaptureEngine + DemoCaptureStream
+- `server/src/wled_controller/core/capture_engines/__init__.py` — Register DemoCaptureEngine
+
+## Acceptance Criteria
+- `DemoCaptureEngine.is_available()` is True only in demo mode
+- Virtual displays appear in the display list API when in demo mode
+- `capture_frame()` returns valid RGB frames that change over time
+- Engine is properly registered in EngineRegistry
+
+## Notes
+- Test patterns should be computationally cheap (no heavy image processing)
+- Use numpy operations for pattern generation (vectorized, fast)
+- Frame dimensions must match the virtual display dimensions
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->

plans/demo-mode/phase-3-virtual-audio-engine.md

@@ -0,0 +1,47 @@
+# Phase 3: Virtual Audio Engine
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Create a `DemoAudioEngine` that provides virtual audio devices and produces synthetic audio data, enabling audio-reactive visualizations in demo mode.
+
+## Tasks
+
+- [ ] Task 1: Create `server/src/wled_controller/core/audio/demo_engine.py` with `DemoAudioEngine` and `DemoAudioCaptureStream`
+- [ ] Task 2: `DemoAudioEngine.ENGINE_TYPE = "demo"`, `ENGINE_PRIORITY = 1000`
+- [ ] Task 3: `is_available()` returns `True` only when `is_demo_mode()` is True
+- [ ] Task 4: `enumerate_devices()` returns 2 virtual devices:
+  - "Demo Microphone" (input, not loopback)
+  - "Demo System Audio" (loopback)
+- [ ] Task 5: `DemoAudioCaptureStream` implements:
+  - `channels = 2`, `sample_rate = 44100`, `chunk_size = 1024`
+  - `read_chunk()` produces synthetic audio: a mix of sine waves with slowly varying frequencies to simulate music-like beat patterns
+  - Returns proper float32 ndarray
+- [ ] Task 6: Register `DemoAudioEngine` in `audio/__init__.py`
+
+## Files to Modify/Create
+- `server/src/wled_controller/core/audio/demo_engine.py` — New file: DemoAudioEngine + DemoAudioCaptureStream
+- `server/src/wled_controller/core/audio/__init__.py` — Register DemoAudioEngine
+
+## Acceptance Criteria
+- `DemoAudioEngine.is_available()` is True only in demo mode
+- Virtual audio devices appear in audio device enumeration when in demo mode
+- `read_chunk()` returns valid float32 audio data that varies over time
+- Audio analyzer produces non-trivial frequency band data from the synthetic signal
+
+## Notes
+- Synthetic audio should produce interesting FFT results (multiple frequencies, amplitude modulation)
+- Keep it computationally lightweight
+- Must conform to `AudioCaptureStreamBase` interface exactly
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->

plans/demo-mode/phase-4-demo-device-seed-data.md

@@ -0,0 +1,54 @@
+# Phase 4: Demo Device Provider & Seed Data
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Create a demo device provider that exposes discoverable virtual LED devices, and build a seed data generator that populates the demo data directory with sample entities on first run.
+
+## Tasks
+
+- [ ] Task 1: Create `server/src/wled_controller/core/devices/demo_provider.py` — `DemoDeviceProvider` extending `LEDDeviceProvider`:
+  - `device_type = "demo"`
+  - `capabilities = {"manual_led_count", "power_control", "brightness_control", "static_color"}`
+  - `create_client()` returns a `MockClient` (reuse existing)
+  - `discover()` returns 3 pre-defined virtual devices:
+    - "Demo LED Strip" (60 LEDs, ip="demo-strip")
+    - "Demo LED Matrix" (256 LEDs / 16×16, ip="demo-matrix")
+    - "Demo LED Ring" (24 LEDs, ip="demo-ring")
+  - `check_health()` always returns online with simulated ~2ms latency
+  - `validate_device()` returns `{"led_count": <from url>}`
+- [ ] Task 2: Register `DemoDeviceProvider` in `led_client.py` `_register_builtin_providers()`
+- [ ] Task 3: Create `server/src/wled_controller/core/demo_seed.py` — seed data generator:
+  - Function `seed_demo_data(storage_config: StorageConfig)` that checks if demo data dir is empty and populates it
+  - Seed entities: 3 devices (matching discover results), 2 output targets, 2 picture sources (using demo engine), 2 CSS sources (gradient + color_cycle), 1 audio source (using demo engine), 1 scene preset, 1 automation
+  - Use proper ID formats matching existing conventions (e.g., `dev_<hex>`, `tgt_<hex>`, etc.)
+- [ ] Task 4: Call `seed_demo_data()` during server startup in `main.py` when demo mode is active (before stores are loaded)
+
+## Files to Modify/Create
+- `server/src/wled_controller/core/devices/demo_provider.py` — New: DemoDeviceProvider
+- `server/src/wled_controller/core/devices/led_client.py` — Register DemoDeviceProvider
+- `server/src/wled_controller/core/demo_seed.py` — New: seed data generator
+- `server/src/wled_controller/main.py` — Call seed on demo startup
+
+## Acceptance Criteria
+- Demo devices appear in discovery results when in demo mode
+- Seed data populates `data/demo/` with valid JSON files on first demo run
+- Subsequent demo runs don't overwrite existing demo data
+- All seeded entities load correctly in stores
+
+## Notes
+- Seed data must match the exact schema expected by each store (look at existing JSON files for format)
+- Use the entity dataclass `to_dict()` / store patterns to generate valid data
+- Demo discovery should NOT appear when not in demo mode
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->

plans/demo-mode/phase-5-frontend-demo-ux.md

@@ -0,0 +1,50 @@
+# Phase 5: Frontend Demo Indicator & Sandbox UX
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Add visual indicators in the frontend that clearly communicate demo mode status to the user, including a badge, dismissible banner, and engine labeling.
+
+## Tasks
+
+- [ ] Task 1: Add `demo_mode` field to system info API response schema (if not already done in Phase 1)
+- [ ] Task 2: In frontend initialization (`app.ts` or `state.ts`), fetch system info and store `demoMode` in app state
+- [ ] Task 3: Add `<span class="demo-badge" id="demo-badge" style="display:none">DEMO</span>` next to app title in `index.html` header
+- [ ] Task 4: CSS for `.demo-badge`: amber/yellow pill shape, subtle pulse animation, clearly visible but not distracting
+- [ ] Task 5: On app load, if `demoMode` is true: show badge, set `document.body.dataset.demo = 'true'`
+- [ ] Task 6: Add a dismissible demo banner at the top of the page: "You're in demo mode — all devices and data are virtual. No real hardware is used." with a dismiss (×) button. Store dismissal in localStorage.
+- [ ] Task 7: Add i18n keys for demo badge and banner text in `en.json`, `ru.json`, `zh.json`
+- [ ] Task 8: In engine/display dropdowns, demo engines should display with "Demo: " prefix for clarity
+
+## Files to Modify/Create
+- `server/src/wled_controller/templates/index.html` — Demo badge + banner HTML
+- `server/src/wled_controller/static/css/app.css` — Demo badge + banner styles
+- `server/src/wled_controller/static/js/app.ts` — Demo mode detection and UI toggle
+- `server/src/wled_controller/static/js/core/state.ts` — Store demo mode flag
+- `server/src/wled_controller/static/locales/en.json` — i18n keys
+- `server/src/wled_controller/static/locales/ru.json` — i18n keys
+- `server/src/wled_controller/static/locales/zh.json` — i18n keys
+
+## Acceptance Criteria
+- Demo badge visible next to "LED Grab" title when in demo mode
+- Demo badge hidden when not in demo mode
+- Banner appears on first demo visit, can be dismissed, stays dismissed across refreshes
+- Engine dropdowns clearly label demo engines
+- All text is localized
+
+## Notes
+- Badge should use `--warning-color` or a custom amber for the pill
+- Banner should be a thin strip, not intrusive
+- `localStorage` key: `demo-banner-dismissed`
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->

plans/demo-mode/phase-6-engine-resolution.md

@@ -0,0 +1,46 @@
+# Phase 6: Demo-only Engine Resolution
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Ensure demo engines are the primary/preferred engines in demo mode, and are hidden when not in demo mode. This makes demo mode act as a "virtual platform" where only demo engines resolve.
+
+## Tasks
+
+- [ ] Task 1: Modify `EngineRegistry.get_available_engines()` to filter out engines with `ENGINE_TYPE == "demo"` when not in demo mode (they report `is_available()=False` anyway, but belt-and-suspenders)
+- [ ] Task 2: Modify `AudioEngineRegistry.get_available_engines()` similarly
+- [ ] Task 3: In demo mode, `get_best_available_engine()` should return the demo engine (already handled by priority=1000, but verify)
+- [ ] Task 4: Modify the `GET /api/v1/config/displays` endpoint: in demo mode, default to demo engine displays if no engine_type specified
+- [ ] Task 5: Modify the audio engine listing endpoint similarly
+- [ ] Task 6: Ensure `DemoDeviceProvider.discover()` only returns devices when in demo mode
+- [ ] Task 7: End-to-end verification: start server in demo mode, verify only demo engines/devices appear in API responses
+
+## Files to Modify/Create
+- `server/src/wled_controller/core/capture_engines/factory.py` — Filter demo engines
+- `server/src/wled_controller/core/audio/factory.py` — Filter demo engines
+- `server/src/wled_controller/api/routes/system.py` — Display endpoint defaults
+- `server/src/wled_controller/api/routes/audio_templates.py` — Audio engine listing
+- `server/src/wled_controller/core/devices/demo_provider.py` — Guard discover()
+
+## Acceptance Criteria
+- In demo mode: demo engines are primary, real engines may also be listed but demo is default
+- Not in demo mode: demo engines are completely hidden from all API responses
+- Display list defaults to demo displays in demo mode
+- Audio device list defaults to demo devices in demo mode
+
+## Notes
+- This is the "demo OS identifier" concept — demo mode acts as a virtual platform
+- Be careful not to break existing behavior when demo=False (default)
+- The demo engines already have `is_available() = is_demo_mode()`, so the main concern is UI defaults
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->