fix: update web ui and add some documentation

closes #188

Author: ph1p

README.md

@@ -653,7 +653,27 @@ Create a second automation or condition to call `rest_command.obegraensad_bright
 
 **Structure:**
 
-- `frontend/` - Web UI code
+- `frontend/` - Web UI code built with solidjs
+- `frontend/src/` - Source files
+- `frontend/dist/` - Built files (generated)
+
+**Prerequisites:**
+
+This project uses [pnpm](https://pnpm.io/) as the package manager. pnpm is an alternative to npm.
+
+**Install pnpm:**
+
+```bash
+# Using npm
+npm install -g pnpm
+
+# Using Homebrew (macOS)
+brew install pnpm
+
+# Using Corepack (Node.js 16.13+)
+corepack enable
+corepack prepare pnpm@latest --activate
+```
 
 **Setup:**
 
@@ -664,15 +684,35 @@ pnpm install
 
 **Configuration:**
 
-- Set device IP in `.env`
+Create a `.env` file in the `frontend/` directory and set your device IP:
+
+```bash
+VITE_DEVICE_IP=192.168.178.50
+```
+
+This allows the development server to proxy API requests to your device during development.
 
 **Commands:**
 
-- `pnpm dev` - Start development server
-- `pnpm build` - Build and generate `webgui.cpp`
+- `pnpm dev` - Start development server with hot reload (usually at `http://localhost:5173`)
+- `pnpm build` - Build optimized production bundle and generate `webgui.cpp` for ESP32
+- `pnpm preview` - Preview production build locally
+- `pnpm lint` - Run linter to check code quality
+- `pnpm format` - Format code with Prettier
+
+**Development Workflow:**
+
+1. Start the development server: `pnpm dev`
+2. Make changes to files in `frontend/src/`
+3. Changes will hot-reload in your browser
+4. Test your changes against a running device
+5. When ready, run `pnpm build` to generate the embedded web UI
+6. The build process creates `src/webgui.cpp` which is compiled into the firmware
 
 **Docker Build:**
 
+If you prefer using Docker instead of installing Node.js and pnpm locally:
+
 ```bash
 docker compose run node
 ```

frontend/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
   "assist": {
     "actions": {
       "source": {

frontend/package.json

@@ -10,7 +10,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
+    "@biomejs/biome": "^2.3.11",
     "@gfx/zopfli": "^1.0.15",
     "@types/node": "^25.0.3",
     "@types/offscreencanvas": "^2019.7.3",
@@ -35,5 +35,5 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss-animate": "^1.0.7"
   },
-  "packageManager": "pnpm@10.26.1"
+  "packageManager": "pnpm@10.27.0"
 }

frontend/pnpm-lock.yaml

@@ -1,4 +1,4 @@
-import { type Component, createMemo, onCleanup, Show } from "solid-js";
+import { type Component, createMemo, Show } from "solid-js";
 
 import { Layout } from "./components/layout/layout";
 import Sidebar from "./components/layout/sidebar";
@@ -12,56 +12,6 @@ export const App: Component = () => {
   const [store, actions] = useStore();
   const { toast } = useToast();
 
-  // Fix iOS Safari WebSocket hanging bug using alternating RAF/setTimeout pattern
-  // Source - https://stackoverflow.com/a/42036303
-  // iOS has a bug where rapid WebSocket sends during pointer events can hang the connection
-  // Solution: alternate between requestAnimationFrame and setTimeout to break the pattern
-  let scheduledId: number | undefined;
-  let pendingLedData: { index: number; status: number } | null = null;
-  let useRaf = true;
-  let frametime = 0;
-  let lastframe = Date.now();
-
-  const deferredLedSend = (data: { index: number; status: number }) => {
-    pendingLedData = data;
-
-    if (scheduledId) return;
-
-    const sendLed = () => {
-      frametime = Date.now() - lastframe;
-      lastframe = Date.now();
-
-      if (pendingLedData) {
-        actions.send(
-          JSON.stringify({
-            event: "led",
-            ...pendingLedData,
-          }),
-        );
-        pendingLedData = null;
-      }
-
-      scheduledId = undefined;
-      useRaf = !useRaf;
-    };
-
-    if (useRaf) {
-      scheduledId = requestAnimationFrame(sendLed);
-    } else {
-      scheduledId = setTimeout(sendLed, Math.max(0, frametime)) as unknown as number;
-    }
-  };
-
-  onCleanup(() => {
-    if (scheduledId) {
-      if (useRaf) {
-        cancelAnimationFrame(scheduledId);
-      } else {
-        clearTimeout(scheduledId);
-      }
-    }
-  });
-
   const rotatedMatrix = createMemo(() => rotateArray(store.indexMatrix, store.rotation));
 
   const wsMessage = (
@@ -177,7 +127,7 @@ export const App: Component = () => {
             indexData={rotatedMatrix()}
             brightness={store.brightness ?? 255}
             onSetLed={(data) => {
-              deferredLedSend(data);
+              wsMessage("led", data);
             }}
             onSetMatrix={(data) => {
               actions?.setLeds([...data]);

frontend/src/app.tsx

@@ -169,31 +169,34 @@ export const LedMatrix: Component<Props> = (props) => {
 
   return (
     <div
-      ref={containerRef}
-      class={`
-        p-4 bg-[#111111]
-        shadow-lg
-        relative mx-auto
-        transition-all duration-300
-        ${visible() ? "opacity-100" : "opacity-50"}
-        ${props.disabled ? "opacity-30" : ""}
-        ${isDrawing() ? "ring-2 ring-blue-500/50" : ""}
-        max-w-full max-h-full
-        aspect-9/13
-      `}
+      class="p-4 bg-[#111111] shadow-lg mx-auto"
       style={{
         width: "min(100%, 700px, (100vh - 16rem) * 9 / 13)",
-        height: "auto",
       }}
     >
-      <canvas
-        ref={canvasRef}
-        class="w-full h-full self-center"
-        style={{
-          "image-rendering": "pixelated",
-          "touch-action": "none",
-        }}
-      />
+      <div
+        ref={containerRef}
+        class={`
+          relative
+          transition-all duration-300
+          ${visible() ? "opacity-100" : "opacity-50"}
+          ${props.disabled ? "opacity-30" : ""}
+          ${isDrawing() ? "ring-2 ring-blue-500/50" : ""}
+          max-w-full max-h-full
+          aspect-9/13
+        `}
+      >
+        <canvas
+          ref={canvasRef}
+          class="w-full"
+          style={{
+            "image-rendering": "pixelated",
+            "touch-action": "none",
+            "aspect-ratio": "9 / 13",
+            height: "auto",
+          }}
+        />
+      </div>
     </div>
   );
 };