# 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 `frontend/bin/www.bin` file.
   - **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.