frontend-ota (#1)

Reviewed-on: #1

Provider/Documentation/build_frontend.md

@@ -0,0 +1,82 @@
+# Building and Flashing the Frontend
+
+The Calendink Provider uses a modern Svelte 5 frontend, built with Vite and TailwindCSS. The frontend is served directly from the ESP32's `www_0` or `www_1` LittleFS partition, allowing the user interface to be updated completely independently from the underlying firmware.
+
+## 1. Prerequisites
+
+Before you can build the frontend, make sure you have [Node.js](https://nodejs.org/) installed on your machine. All frontend code is located inside the `frontend/` directory.
+
+```bash
+cd frontend
+npm install
+```
+
+## 2. Development Mode
+
+During development, you don't need to rebuild and reflash the ESP32 every time you change a button color! You can run the Vite development server on your PC, and it will proxy API requests to the ESP32 over WiFi.
+
+1. Ensure the ESP32 is powered on and connected to your local network.
+2. Update `frontend/.env.development` with the IP address of your ESP32 (e.g., `VITE_API_BASE=http://192.168.50.216`).
+3. Start the dev server:
+
+```bash
+npm run dev
+```
+
+## 3. Building for Production (ESP32)
+
+When you are ready to deploy your frontend changes to the ESP32, you must package everything into a single file and compress it. Our custom build script handles this for you.
+
+Run the following command inside the `frontend/` folder:
+
+```bash
+npm run build:esp32
+```
+
+**What this does:**
+1. Runs Vite's production build.
+2. Inlines all CSS and JS into `index.html` (thanks to `vite-plugin-singlefile`).
+3. Runs `scripts/gzip.js` to heavily compress `index.html` down to an `index.html.gz` file (~15-20KB).
+4. Outputs the final files to the `frontend/dist/` directory.
+
+## 4. Flashing the Filesystem
+
+Now that `frontend/dist/` contains your compressed web app, you must tell the ESP-IDF build system to turn that folder into a LittleFS binary image and flash it.
+
+In your standard ESP-IDF terminal (from the project root, not the `frontend/` folder):
+
+1. **Enable Web Deployment via Menuconfig (if not already done):**
+   ```bash
+   idf.py menuconfig
+   # Navigate to: Calendink Configuration -> Deploy Web Pages
+   # Make sure it is checked (Y)
+   ```
+
+2. **Build and Flash:**
+   ```bash
+   idf.py build
+   idf.py flash
+   ```
+
+Because `CONFIG_CALENDINK_DEPLOY_WEB_PAGES` is enabled, CMake will automatically:
+1. Detect your `frontend/dist/` folder.
+2. Run `mklittlefs` to package it into `www.bin`.
+3. Flash `www.bin` directly to the active `www_0` partition on the ESP32!
+
+## 5. Over-The-Air (OTA) Updates
+
+Once the backend supports it (Phase 2+), you can update the frontend without using USB or `idf.py`.
+
+1. **Build the assets**: `npm run build:esp32`
+2. **Package the image**: `npm run ota:package`
+   - This generates a versioned binary in `frontend/bin/` (e.g., `www_v1.0.5.bin`).
+   - **Configuration**: If the tool is not in your PATH, add its path to `frontend/.env`:
+     ```env
+     MKLITTLEFS_PATH=C:\path\to\mklittlefs.exe
+     ```
+     *(Note: The script also supports `littlefs-python.exe` usually found in the `build/littlefs_py_venv/Scripts/` folder).*
+3. **Upload via Dashboard**: 
+   - Open the dashboard in your browser.
+   - Go to the **Frontend Update** section.
+   - Select the `www.bin` file and click **Flash**.
+   - The device will automatically write to the inactive partition and reboot.