From ce87dff220b835813d6057efa672d5d21dd66c14 Mon Sep 17 00:00:00 2001
From: Kevin Py <pykevin@gmail.com>
Date: Fri, 3 Jul 2026 15:50:26 +0200
Subject: [PATCH 1/3] feat: add image plugin

Adds an Image widget for the ESP32 CYD dashboard:
- New 'image' config field type in the plugin SDK and layout editor
  (file upload, canvas resize to cell size, JPEG base64 <= 48 KB with
  quality step-down and a 96 KB total budget across widgets)
- plugins/image with upload and URL sources, contain/cover fit,
  background color and refresh interval
- Firmware rendering through a single TJpg_Decoder path (mbedtls base64
  for uploads, HTTP(S) fetch for URLs), per-cell render cache and
  Renderer::pushImage primitive

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWQBuM5kVxqNpVsPHKXUPo
---
 app/src/components/Layout.tsx                 |   7 +
 .../LayoutCustomizationPanel.module.css       |  15 +
 .../layout/LayoutCustomizationPanel.tsx       | 142 +++++++
 app/src/lib/imageField.test.ts                |  70 +++
 app/src/lib/imageField.ts                     | 117 +++++
 app/tsconfig.tsbuildinfo                      |   2 +-
 docs/plugins.md                               |   9 +-
 firmware/generated/plugins.ini                |   1 +
 firmware/include/Renderer.h                   |   2 +
 firmware/src/Renderer.cpp                     |   9 +
 .../src/generated/PluginRegistrations.cpp     |   9 +-
 packages/plugin-sdk/src/manifest.test.ts      |  24 ++
 packages/plugin-sdk/src/manifest.ts           |   2 +-
 plugins/generated/manifests.ts                |  94 ++++
 plugins/image/firmware/ImagePlugin.cpp        | 402 ++++++++++++++++++
 plugins/image/firmware/ImagePlugin.h          |   5 +
 plugins/image/library.json                    |  16 +
 plugins/image/manifest.json                   |  71 ++++
 scripts/generate-plugin-registry.mjs          |   3 +-
 19 files changed, 995 insertions(+), 5 deletions(-)
 create mode 100644 app/src/lib/imageField.test.ts
 create mode 100644 app/src/lib/imageField.ts
 create mode 100644 packages/plugin-sdk/src/manifest.test.ts
 create mode 100644 plugins/image/firmware/ImagePlugin.cpp
 create mode 100644 plugins/image/firmware/ImagePlugin.h
 create mode 100644 plugins/image/library.json
 create mode 100644 plugins/image/manifest.json

diff --git a/app/src/components/Layout.tsx b/app/src/components/Layout.tsx
index 5f4f7a6..ab0f3d1 100644
--- a/app/src/components/Layout.tsx
+++ b/app/src/components/Layout.tsx
@@ -14,6 +14,7 @@ import {
   type Orientation,
   orientations,
 } from "../lib/config";
+import { getTotalImageDataLength } from "../lib/imageField";
 import type { LayoutCell } from "../models/LayoutCell";
 import { GlobalVarsDialog } from "./GlobalVarsDialog";
 import styles from "./Layout.module.css";
@@ -101,6 +102,10 @@ export function Layout({
     () => fitCellsToOrientation(cells, orientation),
     [cells, orientation],
   );
+  const totalImageDataLength = useMemo(
+    () => getTotalImageDataLength(fittedCells),
+    [fittedCells],
+  );
   const currentPage = normalizeLayoutPage(activePage);
   const activePageCells = useMemo(
     () => getCellsForPage(fittedCells, currentPage),
@@ -480,6 +485,8 @@ export function Layout({
             manifest={selectedManifest}
             isSettingsOpen={isSettingsOpen}
             selectedArea={selectedArea}
+            orientation={orientation}
+            totalImageDataLength={totalImageDataLength}
             plugins={plugins}
             cellCount={fittedCells.length}
             maxCells={maxLayoutCells}
diff --git a/app/src/components/layout/LayoutCustomizationPanel.module.css b/app/src/components/layout/LayoutCustomizationPanel.module.css
index 188a983..96a5018 100644
--- a/app/src/components/layout/LayoutCustomizationPanel.module.css
+++ b/app/src/components/layout/LayoutCustomizationPanel.module.css
@@ -339,3 +339,18 @@
     padding-top: 0;
   }
 }
+
+.image-field-preview {
+  display: block;
+  max-width: 100%;
+  max-height: 120px;
+  border-radius: 4px;
+  margin-bottom: 6px;
+  object-fit: contain;
+}
+
+.image-field-error {
+  color: var(--color-danger, #e5484d);
+  font-size: 12px;
+  margin: 4px 0 0;
+}
diff --git a/app/src/components/layout/LayoutCustomizationPanel.tsx b/app/src/components/layout/LayoutCustomizationPanel.tsx
index 573847a..33b7d49 100644
--- a/app/src/components/layout/LayoutCustomizationPanel.tsx
+++ b/app/src/components/layout/LayoutCustomizationPanel.tsx
@@ -1,12 +1,20 @@
 import type { PluginConfigField, PluginManifest } from "@budpy/plugin-sdk";
 import { ChevronDown, ClipboardPaste, Trash2, Variable } from "lucide-react";
+import type { ChangeEvent } from "react";
 import { useEffect, useMemo, useState } from "react";
+import type { Orientation } from "../../lib/config";
 import {
   type GlobalVar,
   makeVarRef,
   parseVarRef,
   readGlobalVars,
 } from "../../lib/globalVarsStorage";
+import {
+  encodeImageForCell,
+  getCellPixelSize,
+  type ImageFit,
+  maxTotalImageDataBase64Length,
+} from "../../lib/imageField";
 
 import type { LayoutCell } from "../../models/LayoutCell";
 import styles from "./LayoutCustomizationPanel.module.css";
@@ -17,6 +25,8 @@ interface LayoutCustomizationPanelProps {
   manifest?: PluginManifest;
   isSettingsOpen: boolean;
   selectedArea: CellPlacement | null;
+  orientation: Orientation;
+  totalImageDataLength: number;
   plugins: readonly PluginManifest[];
   cellCount: number;
   maxCells: number;
@@ -31,6 +41,8 @@ interface LayoutCustomizationPanelProps {
 interface PluginSettingsPanelProps {
   cell: LayoutCell;
   manifest: PluginManifest;
+  orientation: Orientation;
+  totalImageDataLength: number;
   onConfigChange: (key: string, value: unknown) => void;
   onDeleteCell: (instanceId: string) => void;
 }
@@ -68,15 +80,117 @@ function getColorInputValue(value: unknown, fallback: unknown): string {
   return "#ffffff";
 }
 
+function ImageFieldInput({
+  field,
+  value,
+  cell,
+  orientation,
+  totalImageDataLength,
+  onConfigChange,
+}: {
+  field: PluginConfigField;
+  value: unknown;
+  cell: LayoutCell;
+  orientation: Orientation;
+  totalImageDataLength: number;
+  onConfigChange: (key: string, value: unknown) => void;
+}) {
+  const [error, setError] = useState<string | null>(null);
+  const [isEncoding, setIsEncoding] = useState(false);
+  const imageData = typeof value === "string" && value.length > 0 ? value : null;
+
+  async function handleFileChange(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (!file) {
+      return;
+    }
+
+    const fit: ImageFit = cell.config["fit"] === "cover" ? "cover" : "contain";
+    const backgroundColor =
+      typeof cell.config["backgroundColor"] === "string" &&
+      colorValuePattern.test(cell.config["backgroundColor"])
+        ? cell.config["backgroundColor"]
+        : "#000000";
+    const size = getCellPixelSize(cell, orientation);
+
+    setError(null);
+    setIsEncoding(true);
+    try {
+      const base64 = await encodeImageForCell(file, size, fit, backgroundColor);
+      const currentLength = typeof value === "string" ? value.length : 0;
+      const nextTotal = totalImageDataLength - currentLength + base64.length;
+      if (nextTotal > maxTotalImageDataBase64Length) {
+        setError("Total image budget exceeded (96 KB across all widgets)");
+        return;
+      }
+      onConfigChange(field.key, base64);
+    } catch (encodeError) {
+      setError(
+        encodeError instanceof Error
+          ? encodeError.message
+          : "Could not process this image",
+      );
+    } finally {
+      setIsEncoding(false);
+    }
+  }
+
+  return (
+    <div className={`form-field ${styles["field"]}`}>
+      <label htmlFor={`field-${field.key}`}>{field.label}</label>
+      {imageData && (
+        <img
+          alt="Widget preview"
+          className={styles["image-field-preview"]}
+          src={`data:image/jpeg;base64,${imageData}`}
+        />
+      )}
+      <div className={styles["field-control"]}>
+        <input
+          accept="image/*"
+          id={`field-${field.key}`}
+          name={field.key}
+          type="file"
+          disabled={isEncoding}
+          onChange={handleFileChange}
+        />
+        {imageData && (
+          <button
+            type="button"
+            className="icon-button icon-button-danger"
+            title="Remove image"
+            aria-label="Remove image"
+            onClick={() => {
+              setError(null);
+              onConfigChange(field.key, "");
+            }}
+          >
+            <Trash2 aria-hidden="true" size={12} />
+          </button>
+        )}
+      </div>
+      {error && <p className={styles["image-field-error"]}>{error}</p>}
+      {field.description && !error && <p>{field.description}</p>}
+    </div>
+  );
+}
+
 function PluginConfigFieldInput({
   field,
   value,
+  cell,
+  orientation,
+  totalImageDataLength,
   globalVars,
   colorVars,
   onConfigChange,
 }: {
   field: PluginConfigField;
   value: unknown;
+  cell: LayoutCell;
+  orientation: Orientation;
+  totalImageDataLength: number;
   globalVars: readonly GlobalVar[];
   colorVars: readonly GlobalVar[];
   onConfigChange: (key: string, value: unknown) => void;
@@ -101,6 +215,19 @@ function PluginConfigFieldInput({
     );
   }
 
+  if (field.type === "image") {
+    return (
+      <ImageFieldInput
+        field={field}
+        value={value}
+        cell={cell}
+        orientation={orientation}
+        totalImageDataLength={totalImageDataLength}
+        onConfigChange={onConfigChange}
+      />
+    );
+  }
+
   if (field.type === "select") {
     return (
       <label className={`form-field ${styles["field"]}`}>
@@ -283,12 +410,16 @@ function PluginConfigFieldInput({
 function PluginConfigFields({
   fields,
   cell,
+  orientation,
+  totalImageDataLength,
   globalVars,
   colorVars,
   onConfigChange,
 }: {
   fields: readonly PluginConfigField[];
   cell: LayoutCell;
+  orientation: Orientation;
+  totalImageDataLength: number;
   globalVars: readonly GlobalVar[];
   colorVars: readonly GlobalVar[];
   onConfigChange: (key: string, value: unknown) => void;
@@ -305,6 +436,9 @@ function PluginConfigFields({
         <PluginConfigFieldInput
           field={field}
           value={cell.config[field.key]}
+          cell={cell}
+          orientation={orientation}
+          totalImageDataLength={totalImageDataLength}
           globalVars={globalVars}
           colorVars={colorVars}
           onConfigChange={onConfigChange}
@@ -385,6 +519,8 @@ function getDefaultOpenGroupKeys(
 function PluginSettingsPanel({
   cell,
   manifest,
+  orientation,
+  totalImageDataLength,
   onConfigChange,
   onDeleteCell,
 }: PluginSettingsPanelProps) {
@@ -493,6 +629,8 @@ function PluginSettingsPanel({
                 <PluginConfigFields
                   fields={group.fields}
                   cell={cell}
+                  orientation={orientation}
+                  totalImageDataLength={totalImageDataLength}
                   globalVars={globalVars}
                   colorVars={colorVars}
                   onConfigChange={onConfigChange}
@@ -572,6 +710,8 @@ export function LayoutCustomizationPanel({
   manifest,
   isSettingsOpen,
   selectedArea,
+  orientation,
+  totalImageDataLength,
   plugins,
   cellCount,
   maxCells,
@@ -607,6 +747,8 @@ export function LayoutCustomizationPanel({
         <PluginSettingsPanel
           cell={selectedCell}
           manifest={manifest}
+          orientation={orientation}
+          totalImageDataLength={totalImageDataLength}
           onConfigChange={onConfigChange}
           onDeleteCell={onDeleteCell}
         />
diff --git a/app/src/lib/imageField.test.ts b/app/src/lib/imageField.test.ts
new file mode 100644
index 0000000..ad41041
--- /dev/null
+++ b/app/src/lib/imageField.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+	computeDrawRect,
+	getCellPixelSize,
+	getTotalImageDataLength,
+} from "./imageField";
+
+describe("getCellPixelSize", () => {
+	it("computes a 2x2 cell in landscape (320x240, 4x3 grid)", () => {
+		expect(getCellPixelSize({ colSpan: 2, rowSpan: 2 }, "90")).toEqual({
+			width: 160,
+			height: 160,
+		});
+	});
+
+	it("computes a full-width cell in portrait (240x320, 3x4 grid)", () => {
+		expect(getCellPixelSize({ colSpan: 3, rowSpan: 1 }, "0")).toEqual({
+			width: 240,
+			height: 80,
+		});
+	});
+});
+
+describe("computeDrawRect", () => {
+	it("contain letterboxes a wide image", () => {
+		// 200x100 image into 100x100 cell → scaled to 100x50, centered vertically
+		expect(computeDrawRect(200, 100, 100, 100, "contain")).toEqual({
+			dx: 0,
+			dy: 25,
+			dw: 100,
+			dh: 50,
+		});
+	});
+
+	it("contain upscales a small image to fit", () => {
+		expect(computeDrawRect(50, 50, 100, 100, "contain")).toEqual({
+			dx: 0,
+			dy: 0,
+			dw: 100,
+			dh: 100,
+		});
+	});
+
+	it("cover crops a wide image", () => {
+		// 200x100 image covering 100x100 cell → scaled to 200x100, centered horizontally
+		expect(computeDrawRect(200, 100, 100, 100, "cover")).toEqual({
+			dx: -50,
+			dy: 0,
+			dw: 200,
+			dh: 100,
+		});
+	});
+});
+
+describe("getTotalImageDataLength", () => {
+	it("sums string imageData lengths across cells", () => {
+		expect(
+			getTotalImageDataLength([
+				{ config: { imageData: "abc" } },
+				{ config: { imageData: "de" } },
+				{ config: {} },
+				{ config: { imageData: 123 } },
+			]),
+		).toBe(5);
+	});
+
+	it("returns 0 for an empty array", () => {
+		expect(getTotalImageDataLength([])).toBe(0);
+	});
+});
diff --git a/app/src/lib/imageField.ts b/app/src/lib/imageField.ts
new file mode 100644
index 0000000..760e815
--- /dev/null
+++ b/app/src/lib/imageField.ts
@@ -0,0 +1,117 @@
+import { getLayoutGridForOrientation, isLandscapeOrientation } from "./config";
+import type { Orientation } from "./config";
+
+export type ImageFit = "contain" | "cover";
+
+export interface CellPixelSize {
+	width: number;
+	height: number;
+}
+
+export interface DrawRect {
+	dx: number;
+	dy: number;
+	dw: number;
+	dh: number;
+}
+
+export const maxImageDataBase64Length = 49152;
+
+export const maxTotalImageDataBase64Length = 98304;
+
+export function getTotalImageDataLength(
+	cells: readonly { config: Record<string, unknown> }[],
+): number {
+	return cells.reduce((total, cell) => {
+		const imageData = cell.config["imageData"];
+		return total + (typeof imageData === "string" ? imageData.length : 0);
+	}, 0);
+}
+
+const jpegQualitySteps = [0.85, 0.7, 0.55, 0.4];
+
+export function getCellPixelSize(
+	span: { colSpan: number; rowSpan: number },
+	orientation: Orientation,
+): CellPixelSize {
+	const landscape = isLandscapeOrientation(orientation);
+	const screenWidth = landscape ? 320 : 240;
+	const screenHeight = landscape ? 240 : 320;
+	const grid = getLayoutGridForOrientation(orientation);
+
+	return {
+		width: Math.floor((screenWidth * span.colSpan) / grid.cols),
+		height: Math.floor((screenHeight * span.rowSpan) / grid.rows),
+	};
+}
+
+export function computeDrawRect(
+	imgW: number,
+	imgH: number,
+	cellW: number,
+	cellH: number,
+	fit: ImageFit,
+): DrawRect {
+	if (imgW <= 0 || imgH <= 0 || cellW <= 0 || cellH <= 0) {
+		return { dx: 0, dy: 0, dw: 0, dh: 0 };
+	}
+
+	const scale =
+		fit === "cover"
+			? Math.max(cellW / imgW, cellH / imgH)
+			: Math.min(cellW / imgW, cellH / imgH);
+	const dw = Math.round(imgW * scale);
+	const dh = Math.round(imgH * scale);
+
+	return {
+		dx: Math.floor((cellW - dw) / 2),
+		dy: Math.floor((cellH - dh) / 2),
+		dw,
+		dh,
+	};
+}
+
+export async function encodeImageForCell(
+	file: Blob,
+	size: CellPixelSize,
+	fit: ImageFit,
+	backgroundColor: string,
+): Promise<string> {
+	const bitmap = await createImageBitmap(file);
+
+	try {
+		const canvas = document.createElement("canvas");
+		canvas.width = size.width;
+		canvas.height = size.height;
+
+		const context = canvas.getContext("2d");
+		if (!context) {
+			throw new Error("Canvas is not supported in this browser");
+		}
+
+		context.fillStyle = backgroundColor;
+		context.fillRect(0, 0, size.width, size.height);
+
+		const rect = computeDrawRect(
+			bitmap.width,
+			bitmap.height,
+			size.width,
+			size.height,
+			fit,
+		);
+		context.imageSmoothingQuality = "high";
+		context.drawImage(bitmap, rect.dx, rect.dy, rect.dw, rect.dh);
+
+		for (const quality of jpegQualitySteps) {
+			const dataUrl = canvas.toDataURL("image/jpeg", quality);
+			const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
+			if (base64.length <= maxImageDataBase64Length) {
+				return base64;
+			}
+		}
+
+		throw new Error("Image is too large for this cell");
+	} finally {
+		bitmap.close();
+	}
+}
diff --git a/app/tsconfig.tsbuildinfo b/app/tsconfig.tsbuildinfo
index 816dfed..ede3bed 100644
--- a/app/tsconfig.tsbuildinfo
+++ b/app/tsconfig.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/app.tsx","./src/main.tsx","./src/components/espsidebar.tsx","./src/components/flash.tsx","./src/components/globalvarsdialog.tsx","./src/components/layout.tsx","./src/components/setup.tsx","./src/components/layout/layoutcustomizationpanel.tsx","./src/components/layout/layoutpluginpalette.tsx","./src/components/layout/layoutpreview.tsx","./src/components/layout/layoutcells.test.ts","./src/components/layout/layoutcells.ts","./src/components/layout/layoutdrag.ts","./src/components/layout/layoutmessages.ts","./src/lib/config.test.ts","./src/lib/config.ts","./src/lib/devicesetupstorage.test.ts","./src/lib/devicesetupstorage.ts","./src/lib/globalvarsstorage.ts","./src/lib/layoutstorage.test.ts","./src/lib/layoutstorage.ts","./src/lib/serial.test.ts","./src/lib/serial.ts","./src/models/budpyconfiginput.ts","./src/models/devicesetupinput.ts","./src/models/layoutcell.ts","./src/models/layoutdraft.ts","./vite.config.ts"],"version":"5.9.3"}
\ No newline at end of file
+{"root":["./src/app.tsx","./src/main.tsx","./src/components/espsidebar.tsx","./src/components/flash.tsx","./src/components/globalvarsdialog.tsx","./src/components/layout.tsx","./src/components/setup.tsx","./src/components/layout/layoutcustomizationpanel.tsx","./src/components/layout/layoutpluginpalette.tsx","./src/components/layout/layoutpreview.tsx","./src/components/layout/layoutcells.test.ts","./src/components/layout/layoutcells.ts","./src/components/layout/layoutdrag.ts","./src/components/layout/layoutmessages.ts","./src/lib/config.test.ts","./src/lib/config.ts","./src/lib/devicesetupstorage.test.ts","./src/lib/devicesetupstorage.ts","./src/lib/globalvarsstorage.ts","./src/lib/imagefield.test.ts","./src/lib/imagefield.ts","./src/lib/layoutstorage.test.ts","./src/lib/layoutstorage.ts","./src/lib/serial.test.ts","./src/lib/serial.ts","./src/models/budpyconfiginput.ts","./src/models/devicesetupinput.ts","./src/models/layoutcell.ts","./src/models/layoutdraft.ts","./vite.config.ts"],"version":"5.9.3"}
\ No newline at end of file
diff --git a/docs/plugins.md b/docs/plugins.md
index 227ab1e..a82ec0b 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -114,7 +114,7 @@ firmware receives as JSON:
 
 - `key`: config key, also the JSON key the firmware reads.
 - `label`: input label in the web app.
-- `type`: one of `text`, `number`, `boolean`, `select`, `color`.
+- `type`: one of `text`, `number`, `boolean`, `select`, `color`, `image`.
 - `defaultValue` (optional): string, number, or boolean applied when the
   widget is added to the layout.
 - `options` (for `select`): array of `{ "label": ..., "value": ... }` string
@@ -132,6 +132,13 @@ firmware side typically parses them with `doc["key"].as<const char*>()`.
 managed in the web app's Variables dialog. References are resolved by the web
 app before the config is sent, so the firmware always receives literal values.
 
+`image` fields render a file picker in the web app. The selected picture is
+resized to the cell's pixel size, re-encoded as JPEG, and stored as a raw
+base64 string (no `data:` prefix) in the cell config under the field's `key`.
+The payload is capped at 48 KB of base64; the app lowers the JPEG quality to
+fit and rejects the file if it still exceeds the cap. The firmware is expected
+to base64-decode the value and render the JPEG (see `plugins/image`).
+
 ### Setting Groups
 
 For plugins with many fields, `settingGroups` organises the form into
diff --git a/firmware/generated/plugins.ini b/firmware/generated/plugins.ini
index 866c64c..9ac3940 100644
--- a/firmware/generated/plugins.ini
+++ b/firmware/generated/plugins.ini
@@ -6,5 +6,6 @@ lib_deps =
   symlink://../plugins/get-data
   symlink://../plugins/ha-cover
   symlink://../plugins/ha-sensor
+  symlink://../plugins/image
   symlink://../plugins/next
   symlink://../plugins/weather
diff --git a/firmware/include/Renderer.h b/firmware/include/Renderer.h
index fe775e6..1e53334 100644
--- a/firmware/include/Renderer.h
+++ b/firmware/include/Renderer.h
@@ -29,6 +29,8 @@ class Renderer {
   void fillRect(int16_t left, int16_t top, int16_t width, int16_t height);
   void fillRect(int16_t left, int16_t top, int16_t width, int16_t height,
                 uint16_t color);
+  void pushImage(int16_t x, int16_t y, int16_t width, int16_t height,
+                 const uint16_t* pixels);
   int16_t textWidth(const String& value, uint8_t font);
   void textAt(int16_t x, int16_t y, const String& value, uint8_t font,
               uint16_t color);
diff --git a/firmware/src/Renderer.cpp b/firmware/src/Renderer.cpp
index dbeb778..32274a1 100644
--- a/firmware/src/Renderer.cpp
+++ b/firmware/src/Renderer.cpp
@@ -90,6 +90,15 @@ void Renderer::fillRect(int16_t left, int16_t top, int16_t width,
   tft.fillRect(left, top, width, height, color);
 }
 
+void Renderer::pushImage(int16_t x, int16_t y, int16_t width, int16_t height,
+                         const uint16_t* pixels) {
+  if (width <= 0 || height <= 0 || pixels == nullptr) return;
+  const bool previousSwap = tft.getSwapBytes();
+  tft.setSwapBytes(true);
+  tft.pushImage(x, y, width, height, pixels);
+  tft.setSwapBytes(previousSwap);
+}
+
 int16_t Renderer::textWidth(const String& value, uint8_t font) {
   return static_cast<int16_t>(tft.textWidth(value, font));
 }
diff --git a/firmware/src/generated/PluginRegistrations.cpp b/firmware/src/generated/PluginRegistrations.cpp
index f63746d..a14200c 100644
--- a/firmware/src/generated/PluginRegistrations.cpp
+++ b/firmware/src/generated/PluginRegistrations.cpp
@@ -6,6 +6,7 @@
 #include "GetDataPlugin.h"
 #include "HaCoverPlugin.h"
 #include "HaSensorPlugin.h"
+#include "ImagePlugin.h"
 #include "NextPlugin.h"
 #include "WeatherPlugin.h"
 
@@ -34,6 +35,12 @@ const PluginRegistration pluginRegistrations[] = {
         nullptr,
         nullptr,
     },
+    {
+        "image",
+        renderImagePlugin,
+        nullptr,
+        nullptr,
+    },
     {
         "next",
         renderNextPlugin,
@@ -48,4 +55,4 @@ const PluginRegistration pluginRegistrations[] = {
     },
 };
 
-const size_t pluginRegistrationCount = 6;
+const size_t pluginRegistrationCount = 7;
diff --git a/packages/plugin-sdk/src/manifest.test.ts b/packages/plugin-sdk/src/manifest.test.ts
new file mode 100644
index 0000000..7380523
--- /dev/null
+++ b/packages/plugin-sdk/src/manifest.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { PluginConfigFieldSchema } from "./manifest";
+
+describe("PluginConfigFieldSchema", () => {
+	it("accepts the image field type", () => {
+		const result = PluginConfigFieldSchema.safeParse({
+			key: "imageData",
+			label: "Image",
+			type: "image",
+		});
+
+		expect(result.success).toBe(true);
+	});
+
+	it("rejects unknown field types", () => {
+		const result = PluginConfigFieldSchema.safeParse({
+			key: "imageData",
+			label: "Image",
+			type: "file",
+		});
+
+		expect(result.success).toBe(false);
+	});
+});
diff --git a/packages/plugin-sdk/src/manifest.ts b/packages/plugin-sdk/src/manifest.ts
index b28d448..a12dded 100644
--- a/packages/plugin-sdk/src/manifest.ts
+++ b/packages/plugin-sdk/src/manifest.ts
@@ -10,7 +10,7 @@ export const PluginCapabilitySchema = z.enum([
 export const PluginConfigFieldSchema = z.object({
 	key: z.string().min(1),
 	label: z.string().min(1),
-	type: z.enum(["text", "number", "boolean", "select", "color"]),
+	type: z.enum(["text", "number", "boolean", "select", "color", "image"]),
 	required: z.boolean().optional(),
 	placeholder: z.string().optional(),
 	description: z.string().optional(),
diff --git a/plugins/generated/manifests.ts b/plugins/generated/manifests.ts
index 5521311..69369d0 100644
--- a/plugins/generated/manifests.ts
+++ b/plugins/generated/manifests.ts
@@ -3139,6 +3139,100 @@ export const pluginManifests = [
       }
     ]
   },
+  {
+    "id": "image",
+    "version": "0.1.0",
+    "displayName": "Image",
+    "description": "Displays an uploaded picture or a remote JPEG.",
+    "defaultSize": {
+      "colSpan": 2,
+      "rowSpan": 2
+    },
+    "capabilities": [
+      "network"
+    ],
+    "firmware": {
+      "type": "platformio-library",
+      "path": ".",
+      "include": "ImagePlugin.h",
+      "renderFunction": "renderImagePlugin"
+    },
+    "configFields": [
+      {
+        "key": "source",
+        "label": "Source",
+        "type": "select",
+        "defaultValue": "upload",
+        "options": [
+          {
+            "label": "Upload",
+            "value": "upload"
+          },
+          {
+            "label": "URL",
+            "value": "url"
+          }
+        ]
+      },
+      {
+        "key": "imageData",
+        "label": "Image",
+        "type": "image",
+        "description": "Resized to the cell and embedded in the config.",
+        "disabledWhen": {
+          "field": "source",
+          "equals": "url"
+        }
+      },
+      {
+        "key": "url",
+        "label": "Image URL (JPEG)",
+        "type": "text",
+        "maxLength": 512,
+        "placeholder": "https://example.com/image.jpg",
+        "disabledWhen": {
+          "field": "source",
+          "equals": "upload"
+        }
+      },
+      {
+        "key": "fit",
+        "label": "Fit",
+        "type": "select",
+        "defaultValue": "contain",
+        "options": [
+          {
+            "label": "Contain",
+            "value": "contain"
+          },
+          {
+            "label": "Cover",
+            "value": "cover"
+          }
+        ]
+      },
+      {
+        "key": "backgroundColor",
+        "label": "Background color",
+        "type": "color",
+        "defaultValue": "#000000"
+      },
+      {
+        "key": "refreshMinutes",
+        "label": "Refresh (minutes)",
+        "type": "number",
+        "defaultValue": 0,
+        "min": 0,
+        "max": 1440,
+        "step": 1,
+        "description": "URL mode only. 0 fetches once.",
+        "disabledWhen": {
+          "field": "source",
+          "equals": "upload"
+        }
+      }
+    ]
+  },
   {
     "id": "next",
     "version": "0.1.0",
diff --git a/plugins/image/firmware/ImagePlugin.cpp b/plugins/image/firmware/ImagePlugin.cpp
new file mode 100644
index 0000000..09f49e5
--- /dev/null
+++ b/plugins/image/firmware/ImagePlugin.cpp
@@ -0,0 +1,402 @@
+#include "ImagePlugin.h"
+
+#include <ArduinoJson.h>
+#include <HTTPClient.h>
+#include <TJpg_Decoder.h>
+#include <WiFiClient.h>
+#include <WiFiClientSecure.h>
+#include <mbedtls/base64.h>
+
+namespace {
+
+constexpr size_t MAX_UPLOAD_DECODED_BYTES = 40960;
+constexpr size_t MAX_URL_IMAGE_BYTES = 81920;
+constexpr uint32_t FETCH_READ_TIMEOUT_MS = 10000;
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+struct ImageCellConfig {
+  bool fromUrl;
+  const char* imageData; // points into the JsonDocument
+  String url;
+  bool cover;
+  uint16_t backgroundColor;
+  uint32_t refreshMinutes;
+};
+
+uint16_t parseHexColor(const char* value, uint16_t fallback) {
+  if (value == nullptr || value[0] != '#' || strlen(value) != 7) {
+    return fallback;
+  }
+
+  char* end = nullptr;
+  const uint32_t rgb = strtoul(value + 1, &end, 16);
+  if (end == nullptr || *end != '\0') {
+    return fallback;
+  }
+
+  return static_cast<uint16_t>(((rgb >> 8) & 0xF800) | ((rgb >> 5) & 0x07E0) |
+                               ((rgb >> 3) & 0x001F));
+}
+
+bool parseCellConfig(JsonDocument& doc, const String& configJson,
+                     ImageCellConfig& out) {
+  if (deserializeJson(doc, configJson) != DeserializationError::Ok) {
+    return false;
+  }
+
+  const char* source = doc["source"] | "upload";
+  out.fromUrl = strcmp(source, "url") == 0;
+  out.imageData = doc["imageData"] | "";
+  out.url = String(doc["url"] | "");
+  const char* fit = doc["fit"] | "contain";
+  out.cover = strcmp(fit, "cover") == 0;
+  out.backgroundColor = parseHexColor(doc["backgroundColor"] | "#000000", 0x0000);
+  const long refresh = doc["refreshMinutes"] | 0L;
+  out.refreshMinutes =
+      refresh > 0 ? min(static_cast<uint32_t>(refresh), static_cast<uint32_t>(1440))
+                  : 0;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Cell geometry
+// ---------------------------------------------------------------------------
+
+int16_t gridCoordinate(int16_t size, uint8_t position, uint8_t divisions) {
+  if (divisions == 0) return 0;
+  return static_cast<int16_t>((static_cast<int32_t>(size) * position) /
+                              divisions);
+}
+
+// ---------------------------------------------------------------------------
+// Per-cell render cache
+// ---------------------------------------------------------------------------
+
+struct ImageRenderCache {
+  bool drawn;          // an image is currently on screen for this cell
+  bool errorShown;     // the error label is currently on screen
+  uint32_t configHash; // djb2 of configJson
+  uint32_t lastFetchMs;
+  bool fetchedOnce;
+  bool fromUrl;
+  uint32_t refreshMinutes;
+};
+
+static ImageRenderCache renderCache[MAX_LAYOUT_CELLS];
+
+uint32_t hashConfig(const String& configJson) {
+  uint32_t hash = 5381;
+  for (size_t i = 0; i < static_cast<size_t>(configJson.length()); i++) {
+    hash = ((hash << 5) + hash) + static_cast<uint8_t>(configJson[i]);
+  }
+  return hash;
+}
+
+// ---------------------------------------------------------------------------
+// TJpg output callback: clip to the cell rectangle
+// ---------------------------------------------------------------------------
+
+static Renderer* activeRenderer = nullptr;
+static int16_t clipLeft = 0;
+static int16_t clipTop = 0;
+static int16_t clipRight = 0;
+static int16_t clipBottom = 0;
+
+bool tjpgOutput(int16_t x, int16_t y, uint16_t w, uint16_t h,
+                uint16_t* bitmap) {
+  if (activeRenderer == nullptr) return false;
+
+  const int16_t blockLeft = x;
+  const int16_t blockTop = y;
+  const int16_t blockRight = static_cast<int16_t>(x + w);
+  const int16_t blockBottom = static_cast<int16_t>(y + h);
+
+  const int16_t left = max(blockLeft, clipLeft);
+  const int16_t top = max(blockTop, clipTop);
+  const int16_t right = min(blockRight, clipRight);
+  const int16_t bottom = min(blockBottom, clipBottom);
+  if (left >= right || top >= bottom) return true;
+
+  for (int16_t row = top; row < bottom; row++) {
+    const uint16_t* src =
+        bitmap + static_cast<size_t>(row - blockTop) * w + (left - blockLeft);
+    activeRenderer->pushImage(left, row, static_cast<int16_t>(right - left), 1,
+                              src);
+  }
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// JPEG drawing
+// ---------------------------------------------------------------------------
+
+uint8_t chooseScale(uint16_t imgW, uint16_t imgH, int16_t cellW, int16_t cellH,
+                    bool cover) {
+  if (cover) {
+    // Largest downscale that still covers the cell.
+    for (uint8_t scale = 8; scale > 1; scale /= 2) {
+      if (imgW / scale >= static_cast<uint16_t>(cellW) &&
+          imgH / scale >= static_cast<uint16_t>(cellH)) {
+        return scale;
+      }
+    }
+    return 1;
+  }
+
+  // Smallest downscale that fits inside the cell.
+  for (uint8_t scale = 1; scale <= 8; scale *= 2) {
+    if (imgW / scale <= static_cast<uint16_t>(cellW) &&
+        imgH / scale <= static_cast<uint16_t>(cellH)) {
+      return scale;
+    }
+  }
+  return 8;
+}
+
+bool drawJpegInCell(Renderer& renderer, const uint8_t* jpeg, size_t jpegLen,
+                    int16_t cellLeft, int16_t cellTop, int16_t cellWidth,
+                    int16_t cellHeight, bool cover) {
+  uint16_t imgW = 0;
+  uint16_t imgH = 0;
+  if (TJpgDec.getJpgSize(&imgW, &imgH, jpeg, jpegLen) != JDR_OK || imgW == 0 ||
+      imgH == 0) {
+    return false;
+  }
+
+  const uint8_t scale = chooseScale(imgW, imgH, cellWidth, cellHeight, cover);
+  const int16_t scaledW = static_cast<int16_t>(imgW / scale);
+  const int16_t scaledH = static_cast<int16_t>(imgH / scale);
+  const int16_t drawX =
+      static_cast<int16_t>(cellLeft + (cellWidth - scaledW) / 2);
+  const int16_t drawY =
+      static_cast<int16_t>(cellTop + (cellHeight - scaledH) / 2);
+
+  activeRenderer = &renderer;
+  clipLeft = cellLeft;
+  clipTop = cellTop;
+  clipRight = static_cast<int16_t>(cellLeft + cellWidth);
+  clipBottom = static_cast<int16_t>(cellTop + cellHeight);
+
+  TJpgDec.setCallback(tjpgOutput);
+  TJpgDec.setJpgScale(scale);
+  const JRESULT result = TJpgDec.drawJpg(drawX, drawY, jpeg, jpegLen);
+
+  activeRenderer = nullptr;
+  return result == JDR_OK;
+}
+
+// ---------------------------------------------------------------------------
+// Sources
+// ---------------------------------------------------------------------------
+
+uint8_t* decodeBase64(const char* input, size_t& outLen) {
+  const size_t inputLen = strlen(input);
+  if (inputLen == 0) return nullptr;
+
+  size_t needed = 0;
+  mbedtls_base64_decode(nullptr, 0, &needed,
+                        reinterpret_cast<const unsigned char*>(input),
+                        inputLen);
+  if (needed == 0 || needed > MAX_UPLOAD_DECODED_BYTES) return nullptr;
+
+  uint8_t* buffer = static_cast<uint8_t*>(malloc(needed));
+  if (buffer == nullptr) return nullptr;
+
+  if (mbedtls_base64_decode(buffer, needed, &outLen,
+                            reinterpret_cast<const unsigned char*>(input),
+                            inputLen) != 0 ||
+      outLen == 0) {
+    free(buffer);
+    return nullptr;
+  }
+
+  return buffer;
+}
+
+uint8_t* fetchJpeg(const String& url, size_t& outLen) {
+  if (url.length() == 0) return nullptr;
+
+  const bool useTls = url.startsWith("https");
+  HTTPClient http;
+  http.setTimeout(8000);
+
+  bool began = false;
+  if (useTls) {
+    static WiFiClientSecure tlsClient;
+    tlsClient.setInsecure();
+    began = http.begin(tlsClient, url);
+  } else {
+    static WiFiClient plainClient;
+    began = http.begin(plainClient, url);
+  }
+  if (!began) return nullptr;
+
+  if (http.GET() != 200) {
+    http.end();
+    return nullptr;
+  }
+
+  const int size = http.getSize();
+  if (size <= 0 || static_cast<size_t>(size) > MAX_URL_IMAGE_BYTES) {
+    http.end();
+    return nullptr;
+  }
+
+  uint8_t* buffer = static_cast<uint8_t*>(malloc(static_cast<size_t>(size)));
+  if (buffer == nullptr) {
+    http.end();
+    return nullptr;
+  }
+
+  WiFiClient* stream = http.getStreamPtr();
+  size_t offset = 0;
+  const uint32_t start = millis();
+  while (offset < static_cast<size_t>(size) &&
+         millis() - start < FETCH_READ_TIMEOUT_MS) {
+    const size_t available = stream->available();
+    if (available > 0) {
+      const size_t toRead =
+          min(available, static_cast<size_t>(size) - offset);
+      offset += stream->readBytes(buffer + offset, toRead);
+    } else {
+      delay(10);
+    }
+  }
+  http.end();
+
+  if (offset != static_cast<size_t>(size)) {
+    free(buffer);
+    return nullptr;
+  }
+
+  outLen = static_cast<size_t>(size);
+  return buffer;
+}
+
+// ---------------------------------------------------------------------------
+// Drawing helpers
+// ---------------------------------------------------------------------------
+
+void drawError(Renderer& renderer, int16_t cellLeft, int16_t cellTop,
+               int16_t cellWidth, int16_t cellHeight,
+               uint16_t backgroundColor) {
+  renderer.fillRect(cellLeft, cellTop, cellWidth, cellHeight, backgroundColor);
+  const int16_t centerX = static_cast<int16_t>(cellLeft + cellWidth / 2);
+  const int16_t textY =
+      static_cast<int16_t>(cellTop + (cellHeight - renderer.fontHeight(2)) / 2);
+  renderer.textCenterWithin(centerX, textY, cellWidth, "Image error", 2,
+                            TFT_LIGHTGREY);
+}
+
+} // namespace
+
+void renderImagePlugin(PluginRenderContext& context) {
+  Renderer& renderer = context.renderer;
+  const LayoutCellConfig& cell = context.cell;
+
+  const int16_t cellLeft =
+      gridCoordinate(renderer.width(), cell.col, context.config.cols);
+  const int16_t cellRight = gridCoordinate(
+      renderer.width(), cell.col + cell.colSpan, context.config.cols);
+  const int16_t cellTop =
+      gridCoordinate(renderer.height(), cell.row, context.config.rows);
+  const int16_t cellBottom = gridCoordinate(
+      renderer.height(), cell.row + cell.rowSpan, context.config.rows);
+  const int16_t cellWidth = static_cast<int16_t>(cellRight - cellLeft);
+  const int16_t cellHeight = static_cast<int16_t>(cellBottom - cellTop);
+
+  if (context.cellIndex >= MAX_LAYOUT_CELLS) return;
+  ImageRenderCache& cache = renderCache[context.cellIndex];
+
+  const uint32_t configHash = hashConfig(cell.configJson);
+  const bool configChanged = cache.configHash != configHash;
+  if (configChanged) {
+    cache.configHash = configHash;
+    cache.drawn = false;
+    cache.errorShown = false;
+    cache.fetchedOnce = false;
+    cache.lastFetchMs = 0;
+  }
+
+  const uint32_t now = millis();
+
+  if (!configChanged) {
+    // Config is unchanged: decide whether a draw is needed from the cached
+    // values alone, before paying for a JSON parse.
+    const uint32_t cachedRefreshIntervalMs = cache.refreshMinutes * 60000UL;
+    const bool cachedRefreshDue = cache.fromUrl && cache.fetchedOnce &&
+                                  cachedRefreshIntervalMs > 0 &&
+                                  now - cache.lastFetchMs >= cachedRefreshIntervalMs;
+    const bool cachedNeedsDraw = context.forceClear ||
+                                 (!cache.drawn && !cache.errorShown) ||
+                                 cachedRefreshDue;
+    if (!cachedNeedsDraw) return;
+  }
+
+  JsonDocument doc;
+  ImageCellConfig config;
+  if (!parseCellConfig(doc, cell.configJson, config)) {
+    if (cache.drawn && !context.forceClear) return;
+    if (context.forceClear || !cache.errorShown) {
+      drawError(renderer, cellLeft, cellTop, cellWidth, cellHeight, 0x0000);
+      cache.errorShown = true;
+      cache.drawn = false;
+    }
+    return;
+  }
+
+  cache.fromUrl = config.fromUrl;
+  cache.refreshMinutes = config.refreshMinutes;
+
+  const uint32_t refreshIntervalMs = config.refreshMinutes * 60000UL;
+  const bool refreshDue = config.fromUrl && cache.fetchedOnce &&
+                          refreshIntervalMs > 0 &&
+                          now - cache.lastFetchMs >= refreshIntervalMs;
+  const bool needsDraw =
+      context.forceClear || (!cache.drawn && !cache.errorShown) || refreshDue;
+  if (!needsDraw) return;
+
+  // Acquire the JPEG bytes.
+  uint8_t* jpeg = nullptr;
+  size_t jpegLen = 0;
+  if (config.fromUrl) {
+    jpeg = fetchJpeg(config.url, jpegLen);
+    cache.fetchedOnce = true;
+    cache.lastFetchMs = now;
+  } else {
+    jpeg = decodeBase64(config.imageData, jpegLen);
+  }
+
+  if (jpeg == nullptr) {
+    // URL refresh failure keeps the previous frame; anything else shows the
+    // error state.
+    if (config.fromUrl && cache.drawn && !context.forceClear) return;
+    drawError(renderer, cellLeft, cellTop, cellWidth, cellHeight,
+              config.backgroundColor);
+    cache.errorShown = true;
+    cache.drawn = false;
+    return;
+  }
+
+  renderer.fillRect(cellLeft, cellTop, cellWidth, cellHeight,
+                    config.backgroundColor);
+  const bool drawnOk = drawJpegInCell(renderer, jpeg, jpegLen, cellLeft,
+                                      cellTop, cellWidth, cellHeight,
+                                      config.cover);
+  free(jpeg);
+
+  if (!drawnOk) {
+    drawError(renderer, cellLeft, cellTop, cellWidth, cellHeight,
+              config.backgroundColor);
+    cache.errorShown = true;
+    cache.drawn = false;
+    return;
+  }
+
+  cache.drawn = true;
+  cache.errorShown = false;
+}
diff --git a/plugins/image/firmware/ImagePlugin.h b/plugins/image/firmware/ImagePlugin.h
new file mode 100644
index 0000000..96c75f9
--- /dev/null
+++ b/plugins/image/firmware/ImagePlugin.h
@@ -0,0 +1,5 @@
+#pragma once
+
+#include "PluginRuntime.h"
+
+void renderImagePlugin(PluginRenderContext& context);
diff --git a/plugins/image/library.json b/plugins/image/library.json
new file mode 100644
index 0000000..1033ace
--- /dev/null
+++ b/plugins/image/library.json
@@ -0,0 +1,16 @@
+{
+	"name": "BudpyImagePlugin",
+	"version": "0.1.0",
+	"description": "Budpy image plugin firmware library",
+	"frameworks": "arduino",
+	"platforms": "espressif32",
+	"dependencies": {
+		"bblanchon/ArduinoJson": "^7.4.3",
+		"bodmer/TFT_eSPI": "^2.5.43",
+		"bodmer/TJpg_Decoder": "^1.1.0"
+	},
+	"build": {
+		"srcDir": "firmware",
+		"includeDir": "firmware"
+	}
+}
diff --git a/plugins/image/manifest.json b/plugins/image/manifest.json
new file mode 100644
index 0000000..5441429
--- /dev/null
+++ b/plugins/image/manifest.json
@@ -0,0 +1,71 @@
+{
+	"id": "image",
+	"version": "0.1.0",
+	"displayName": "Image",
+	"description": "Displays an uploaded picture or a remote JPEG.",
+	"defaultSize": {
+		"colSpan": 2,
+		"rowSpan": 2
+	},
+	"capabilities": ["network"],
+	"firmware": {
+		"type": "platformio-library",
+		"path": ".",
+		"include": "ImagePlugin.h",
+		"renderFunction": "renderImagePlugin"
+	},
+	"configFields": [
+		{
+			"key": "source",
+			"label": "Source",
+			"type": "select",
+			"defaultValue": "upload",
+			"options": [
+				{ "label": "Upload", "value": "upload" },
+				{ "label": "URL", "value": "url" }
+			]
+		},
+		{
+			"key": "imageData",
+			"label": "Image",
+			"type": "image",
+			"description": "Resized to the cell and embedded in the config.",
+			"disabledWhen": { "field": "source", "equals": "url" }
+		},
+		{
+			"key": "url",
+			"label": "Image URL (JPEG)",
+			"type": "text",
+			"maxLength": 512,
+			"placeholder": "https://example.com/image.jpg",
+			"disabledWhen": { "field": "source", "equals": "upload" }
+		},
+		{
+			"key": "fit",
+			"label": "Fit",
+			"type": "select",
+			"defaultValue": "contain",
+			"options": [
+				{ "label": "Contain", "value": "contain" },
+				{ "label": "Cover", "value": "cover" }
+			]
+		},
+		{
+			"key": "backgroundColor",
+			"label": "Background color",
+			"type": "color",
+			"defaultValue": "#000000"
+		},
+		{
+			"key": "refreshMinutes",
+			"label": "Refresh (minutes)",
+			"type": "number",
+			"defaultValue": 0,
+			"min": 0,
+			"max": 1440,
+			"step": 1,
+			"description": "URL mode only. 0 fetches once.",
+			"disabledWhen": { "field": "source", "equals": "upload" }
+		}
+	]
+}
diff --git a/scripts/generate-plugin-registry.mjs b/scripts/generate-plugin-registry.mjs
index 43eca4a..58aba20 100644
--- a/scripts/generate-plugin-registry.mjs
+++ b/scripts/generate-plugin-registry.mjs
@@ -36,6 +36,7 @@ const pluginConfigFieldTypes = new Set([
 	"boolean",
 	"select",
 	"color",
+	"image",
 ]);
 const identifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -178,7 +179,7 @@ function validatePluginManifest(manifest, manifestFile) {
 		if (!pluginConfigFieldTypes.has(field.type)) {
 			throw validationError(
 				manifestFile,
-				`${fieldPath}.type must be one of text, number, boolean, select, color`,
+				`${fieldPath}.type must be one of text, number, boolean, select, color, image`,
 			);
 		}
 

From 034e9a0619da49c2480c6ecf10909bdfc3e70fcb Mon Sep 17 00:00:00 2001
From: Kevin Py <pykevin@gmail.com>
Date: Fri, 3 Jul 2026 17:46:59 +0200
Subject: [PATCH 2/3] feat: add sleep display mode

---
 app/src/components/EspSidebar.tsx      | 92 ++++++++++++++++++++++++++
 app/src/lib/config.test.ts             | 56 ++++++++++++++++
 app/src/lib/config.ts                  | 72 ++++++++++++++++++++
 app/src/lib/deviceSetupStorage.test.ts | 43 ++++++++++++
 app/src/lib/deviceSetupStorage.ts      | 42 +++++++++++-
 app/src/models/DeviceSetupInput.ts     |  6 ++
 firmware/include/AppConfig.h           |  3 +
 firmware/include/TouchService.h        |  5 ++
 firmware/src/AppConfig.cpp             | 32 +++++++++
 firmware/src/TouchService.cpp          |  4 ++
 firmware/src/main.cpp                  | 55 ++++++++++++---
 packages/plugin-sdk/src/config.ts      |  3 +
 12 files changed, 403 insertions(+), 10 deletions(-)

diff --git a/app/src/components/EspSidebar.tsx b/app/src/components/EspSidebar.tsx
index bb9f94b..33e7748 100644
--- a/app/src/components/EspSidebar.tsx
+++ b/app/src/components/EspSidebar.tsx
@@ -20,9 +20,15 @@ declare module "react" {
 import {
   buildBudpyConfig,
   defaultBackgroundColor,
+  maxScreenIdleHours,
+  maxScreenIdleMinutes,
   normalizeBrightnessMode,
   normalizeBrightnessValue,
   normalizeColorValue,
+  normalizeScreenIdleMinutes,
+  normalizeScreenIdleUnit,
+  normalizeScreenSleepDimBrightness,
+  normalizeScreenSleepMode,
   type Orientation,
 } from "../lib/config";
 import { saveStoredDeviceSetupInput } from "../lib/deviceSetupStorage";
@@ -98,6 +104,17 @@ export function EspSidebar({
   const brightnessMode = normalizeBrightnessMode(input.brightnessMode);
   const brightnessLabel =
     brightnessMode === "auto" ? "Maximum brightness" : "Brightness";
+  const screenIdleMinutes = normalizeScreenIdleMinutes(input.screenIdleMinutes);
+  const screenIdleUnit = normalizeScreenIdleUnit(input.screenIdleUnit);
+  const screenSleepMode = normalizeScreenSleepMode(input.screenSleepMode);
+  const screenSleepDimBrightness = normalizeScreenSleepDimBrightness(
+    input.screenSleepDimBrightness,
+  );
+  const screenIdleValue =
+    screenIdleUnit === "hours" ? screenIdleMinutes / 60 : screenIdleMinutes;
+  const screenIdleMax =
+    screenIdleUnit === "hours" ? maxScreenIdleHours : maxScreenIdleMinutes;
+  const screenSleepEnabled = screenIdleMinutes > 0;
 
   function updateInput(key: keyof DeviceSetupInput, value: string | number) {
     onInputChange(key, value);
@@ -336,6 +353,81 @@ export function EspSidebar({
                     }
                   />
                 </label>
+                <label className="form-field">
+                  <span>Screen sleep after (0 = never)</span>
+                  <input
+                    name="screenIdleValue"
+                    type="number"
+                    min={0}
+                    max={screenIdleMax}
+                    step={1}
+                    value={screenIdleValue}
+                    onChange={(event) => {
+                      const next = Number(event.target.value);
+                      updateInput(
+                        "screenIdleMinutes",
+                        Math.round(
+                          screenIdleUnit === "hours" ? next * 60 : next,
+                        ),
+                      );
+                    }}
+                  />
+                </label>
+                <label className="form-field">
+                  <span>Sleep unit</span>
+                  <select
+                    name="screenIdleUnit"
+                    value={screenIdleUnit}
+                    onChange={(event) =>
+                      updateInput(
+                        "screenIdleUnit",
+                        event.target.value === "hours" ? "hours" : "minutes",
+                      )
+                    }
+                  >
+                    <option value="minutes">Minutes</option>
+                    <option value="hours">Hours</option>
+                  </select>
+                </label>
+                <label className="form-field">
+                  <span>Screen sleep mode</span>
+                  <select
+                    name="screenSleepMode"
+                    value={screenSleepMode}
+                    disabled={!screenSleepEnabled}
+                    onChange={(event) =>
+                      updateInput(
+                        "screenSleepMode",
+                        event.target.value === "dim" ? "dim" : "off",
+                      )
+                    }
+                  >
+                    <option value="off">Turn off</option>
+                    <option value="dim">Dim</option>
+                  </select>
+                </label>
+                {screenSleepMode === "dim" && (
+                  <label className="form-field">
+                    <span>
+                      Dim brightness —{" "}
+                      {Math.round((screenSleepDimBrightness / 255) * 100)}%
+                    </span>
+                    <input
+                      name="screenSleepDimBrightness"
+                      type="range"
+                      min={0}
+                      max={255}
+                      step={1}
+                      value={screenSleepDimBrightness}
+                      onChange={(event) =>
+                        updateInput(
+                          "screenSleepDimBrightness",
+                          Number(event.target.value),
+                        )
+                      }
+                    />
+                  </label>
+                )}
               </div>
               <button
                 type="submit"
diff --git a/app/src/lib/config.test.ts b/app/src/lib/config.test.ts
index ac78e1d..9adcf0a 100644
--- a/app/src/lib/config.test.ts
+++ b/app/src/lib/config.test.ts
@@ -268,6 +268,36 @@ describe("buildBudpyConfig", () => {
 		expect(config.brightness).toBe(128);
 		expect(config.brightnessMode).toBe("auto");
 	});
+
+	it("defaults screen sleep to disabled", () => {
+		const config = buildBudpyConfig({
+			ssid: "Home",
+			password: "secret-password",
+			orientation: "0",
+			cells: [],
+		});
+
+		expect(config.screenIdleMinutes).toBe(0);
+		expect(config.screenSleepMode).toBe("off");
+		expect(config.screenSleepDimBrightness).toBe(12);
+	});
+
+	it("builds a config with screen sleep settings", () => {
+		const config = buildBudpyConfig({
+			ssid: "Home",
+			password: "secret-password",
+			screenIdleMinutes: 120,
+			screenSleepMode: "dim",
+			screenSleepDimBrightness: 40,
+			orientation: "0",
+			cells: [],
+		});
+
+		expect(BudpyConfigSchema.safeParse(config).success).toBe(true);
+		expect(config.screenIdleMinutes).toBe(120);
+		expect(config.screenSleepMode).toBe("dim");
+		expect(config.screenSleepDimBrightness).toBe(40);
+	});
 });
 
 describe("createBudpyConfigInputFromConfig", () => {
@@ -309,6 +339,10 @@ describe("createBudpyConfigInputFromConfig", () => {
 			backgroundColor: "#000000",
 			brightness: 255,
 			brightnessMode: "manual",
+			screenIdleMinutes: 0,
+			screenSleepMode: "off",
+			screenIdleUnit: "minutes",
+			screenSleepDimBrightness: 12,
 			orientation: "90",
 			cells: [
 				{
@@ -398,6 +432,10 @@ describe("createBudpyConfigInputFromConfig", () => {
 				backgroundColor: "#000000",
 				brightness: 255,
 				brightnessMode: "manual",
+				screenIdleMinutes: 0,
+				screenSleepMode: "off",
+				screenIdleUnit: "minutes",
+				screenSleepDimBrightness: 12,
 				orientation: "0",
 				cells: [
 					{
@@ -414,4 +452,22 @@ describe("createBudpyConfigInputFromConfig", () => {
 			},
 		);
 	});
+
+	it("derives the screen sleep unit from the imported idle minutes", () => {
+		const config = BudpyConfigSchema.parse({
+			version: 1,
+			device: { model: "esp32-2432s028r", orientation: "0" },
+			wifi: { ssid: "Home", password: "secret-password" },
+			locale: "fr-FR",
+			timezone: "Europe/Paris",
+			screenIdleMinutes: 120,
+			screenSleepMode: "dim",
+			layout: { cols: 3, rows: 4, cells: [] },
+		});
+
+		const input = createBudpyConfigInputFromConfig(config);
+		expect(input.screenIdleMinutes).toBe(120);
+		expect(input.screenSleepMode).toBe("dim");
+		expect(input.screenIdleUnit).toBe("hours");
+	});
 });
diff --git a/app/src/lib/config.ts b/app/src/lib/config.ts
index c6c9ce9..8c604af 100644
--- a/app/src/lib/config.ts
+++ b/app/src/lib/config.ts
@@ -8,6 +8,8 @@ import type { LayoutCell } from "../models/LayoutCell";
 export type SupportedLocale = BudpyConfig["locale"];
 export type Orientation = BudpyConfig["device"]["orientation"];
 export type BrightnessMode = BudpyConfig["brightnessMode"];
+export type ScreenSleepMode = BudpyConfig["screenSleepMode"];
+export type ScreenIdleUnit = "minutes" | "hours";
 
 export const orientations = [
 	"0",
@@ -55,12 +57,29 @@ export const maxLayoutPages = 8;
 export const defaultBackgroundColor = "#000000";
 export const defaultBrightness = 255;
 export const defaultBrightnessMode = "manual" satisfies BrightnessMode;
+export const defaultScreenIdleMinutes = 0;
+export const defaultScreenSleepMode = "off" satisfies ScreenSleepMode;
+export const defaultScreenSleepDimBrightness = 12;
+export const defaultScreenIdleUnit = "minutes" satisfies ScreenIdleUnit;
 
 export const brightnessModes = [
 	"manual",
 	"auto",
 ] as const satisfies readonly BrightnessMode[];
 
+export const screenSleepModes = [
+	"off",
+	"dim",
+] as const satisfies readonly ScreenSleepMode[];
+
+export const screenIdleUnits = [
+	"minutes",
+	"hours",
+] as const satisfies readonly ScreenIdleUnit[];
+
+export const maxScreenIdleMinutes = 1440;
+export const maxScreenIdleHours = 24;
+
 const colorValuePattern = /^#[0-9a-f]{6}$/i;
 
 export function normalizeColorValue(
@@ -90,6 +109,48 @@ export function normalizeBrightnessMode(value: unknown): BrightnessMode {
 		: defaultBrightnessMode;
 }
 
+export function normalizeScreenIdleMinutes(
+	value: unknown,
+	fallback = defaultScreenIdleMinutes,
+): number {
+	return typeof value === "number" &&
+		Number.isInteger(value) &&
+		value >= 0 &&
+		value <= maxScreenIdleMinutes
+		? value
+		: fallback;
+}
+
+export function normalizeScreenSleepMode(value: unknown): ScreenSleepMode {
+	return screenSleepModes.includes(value as ScreenSleepMode)
+		? (value as ScreenSleepMode)
+		: defaultScreenSleepMode;
+}
+
+export function normalizeScreenSleepDimBrightness(
+	value: unknown,
+	fallback = defaultScreenSleepDimBrightness,
+): number {
+	return typeof value === "number" &&
+		Number.isInteger(value) &&
+		value >= 0 &&
+		value <= 255
+		? value
+		: fallback;
+}
+
+export function normalizeScreenIdleUnit(value: unknown): ScreenIdleUnit {
+	return screenIdleUnits.includes(value as ScreenIdleUnit)
+		? (value as ScreenIdleUnit)
+		: defaultScreenIdleUnit;
+}
+
+export function deriveScreenIdleUnit(
+	minutes: number,
+): ScreenIdleUnit {
+	return minutes > 0 && minutes % 60 === 0 ? "hours" : "minutes";
+}
+
 export function listPluginManifests(): readonly PluginManifest[] {
 	return builtInPluginManifests;
 }
@@ -367,6 +428,11 @@ export function buildBudpyConfig(input: BudpyConfigInput): BudpyConfig {
 		backgroundColor,
 		brightness: normalizeBrightnessValue(input.brightness),
 		brightnessMode: normalizeBrightnessMode(input.brightnessMode),
+		screenIdleMinutes: normalizeScreenIdleMinutes(input.screenIdleMinutes),
+		screenSleepMode: normalizeScreenSleepMode(input.screenSleepMode),
+		screenSleepDimBrightness: normalizeScreenSleepDimBrightness(
+			input.screenSleepDimBrightness,
+		),
 		device: {
 			model: "esp32-2432s028r",
 			orientation: input.orientation,
@@ -418,6 +484,12 @@ export function createBudpyConfigInputFromConfig(
 		backgroundColor: normalizeColorValue(config.backgroundColor),
 		brightness: normalizeBrightnessValue(config.brightness),
 		brightnessMode: normalizeBrightnessMode(config.brightnessMode),
+		screenIdleMinutes: normalizeScreenIdleMinutes(config.screenIdleMinutes),
+		screenSleepMode: normalizeScreenSleepMode(config.screenSleepMode),
+		screenSleepDimBrightness: normalizeScreenSleepDimBrightness(
+			config.screenSleepDimBrightness,
+		),
+		screenIdleUnit: deriveScreenIdleUnit(config.screenIdleMinutes),
 		cells: fitCellsToOrientation(cells, orientation),
 	};
 }
diff --git a/app/src/lib/deviceSetupStorage.test.ts b/app/src/lib/deviceSetupStorage.test.ts
index 0b11299..2461885 100644
--- a/app/src/lib/deviceSetupStorage.test.ts
+++ b/app/src/lib/deviceSetupStorage.test.ts
@@ -41,6 +41,10 @@ describe("device setup storage", () => {
 			backgroundColor: "#000000",
 			brightness: 255,
 			brightnessMode: "manual",
+			screenIdleMinutes: 0,
+			screenIdleUnit: "minutes",
+			screenSleepMode: "off",
+			screenSleepDimBrightness: 12,
 		});
 	});
 
@@ -55,6 +59,10 @@ describe("device setup storage", () => {
 			backgroundColor: "#aabbcc",
 			brightness: 255,
 			brightnessMode: "manual",
+			screenIdleMinutes: 0,
+			screenIdleUnit: "minutes",
+			screenSleepMode: "off",
+			screenSleepDimBrightness: 12,
 		});
 	});
 
@@ -69,6 +77,10 @@ describe("device setup storage", () => {
 			backgroundColor: "#000000",
 			brightness: 128,
 			brightnessMode: "auto",
+			screenIdleMinutes: 0,
+			screenIdleUnit: "minutes",
+			screenSleepMode: "off",
+			screenSleepDimBrightness: 12,
 		});
 	});
 
@@ -86,6 +98,37 @@ describe("device setup storage", () => {
 			backgroundColor: "#000000",
 			brightness: 255,
 			brightnessMode: "manual",
+			screenIdleMinutes: 0,
+			screenIdleUnit: "minutes",
+			screenSleepMode: "off",
+			screenSleepDimBrightness: 12,
+		});
+	});
+
+	it("saves and reads screen sleep settings", () => {
+		const storage = new MemoryStorage();
+
+		saveStoredDeviceSetupInput(
+			{
+				ssid: "Home",
+				password: "secret-password",
+				screenIdleMinutes: 90,
+				screenIdleUnit: "minutes",
+				screenSleepMode: "dim",
+			},
+			storage,
+		);
+
+		expect(readStoredDeviceSetupInput(storage)).toEqual({
+			ssid: "Home",
+			password: "secret-password",
+			backgroundColor: "#000000",
+			brightness: 255,
+			brightnessMode: "manual",
+			screenIdleMinutes: 90,
+			screenIdleUnit: "minutes",
+			screenSleepMode: "dim",
+			screenSleepDimBrightness: 12,
 		});
 	});
 });
diff --git a/app/src/lib/deviceSetupStorage.ts b/app/src/lib/deviceSetupStorage.ts
index bc69ec2..06b2987 100644
--- a/app/src/lib/deviceSetupStorage.ts
+++ b/app/src/lib/deviceSetupStorage.ts
@@ -3,9 +3,17 @@ import {
 	defaultBackgroundColor,
 	defaultBrightness,
 	defaultBrightnessMode,
+	defaultScreenIdleMinutes,
+	defaultScreenIdleUnit,
+	defaultScreenSleepMode,
+	defaultScreenSleepDimBrightness,
 	normalizeBrightnessMode,
 	normalizeBrightnessValue,
 	normalizeColorValue,
+	normalizeScreenIdleMinutes,
+	normalizeScreenIdleUnit,
+	normalizeScreenSleepDimBrightness,
+	normalizeScreenSleepMode,
 } from "./config";
 
 interface KeyValueStorage {
@@ -17,6 +25,10 @@ interface StoredDeviceSetupInput extends DeviceSetupInput {
 	version: 1;
 	brightness: number;
 	brightnessMode: DeviceSetupInput["brightnessMode"];
+	screenIdleMinutes: number;
+	screenIdleUnit: DeviceSetupInput["screenIdleUnit"];
+	screenSleepMode: DeviceSetupInput["screenSleepMode"];
+	screenSleepDimBrightness: number;
 }
 
 const deviceSetupStorageKey = "budpy:device-setup:v1";
@@ -27,6 +39,10 @@ export const emptyDeviceSetupInput = {
 	backgroundColor: defaultBackgroundColor,
 	brightness: defaultBrightness,
 	brightnessMode: defaultBrightnessMode,
+	screenIdleMinutes: defaultScreenIdleMinutes,
+	screenIdleUnit: defaultScreenIdleUnit,
+	screenSleepMode: defaultScreenSleepMode,
+	screenSleepDimBrightness: defaultScreenSleepDimBrightness,
 } satisfies DeviceSetupInput;
 
 function getLocalStorage(): KeyValueStorage | null {
@@ -68,12 +84,30 @@ export function parseStoredDeviceSetupInput(
 		const backgroundColor = normalizeColorValue(parsed.backgroundColor);
 		const brightness = normalizeBrightnessValue(parsed.brightness);
 		const brightnessMode = normalizeBrightnessMode(parsed.brightnessMode);
+		const screenIdleMinutes = normalizeScreenIdleMinutes(
+			parsed.screenIdleMinutes,
+		);
+		const screenIdleUnit = normalizeScreenIdleUnit(parsed.screenIdleUnit);
+		const screenSleepMode = normalizeScreenSleepMode(parsed.screenSleepMode);
+		const screenSleepDimBrightness = normalizeScreenSleepDimBrightness(
+			parsed.screenSleepDimBrightness,
+		);
 
 		if (ssid === null || password === null) {
 			return emptyDeviceSetupInput;
 		}
 
-		return { ssid, password, backgroundColor, brightness, brightnessMode };
+		return {
+			ssid,
+			password,
+			backgroundColor,
+			brightness,
+			brightnessMode,
+			screenIdleMinutes,
+			screenIdleUnit,
+			screenSleepMode,
+			screenSleepDimBrightness,
+		};
 	} catch (_error) {
 		return emptyDeviceSetupInput;
 	}
@@ -108,6 +142,12 @@ export function saveStoredDeviceSetupInput(
 		backgroundColor: normalizeColorValue(input.backgroundColor),
 		brightness: normalizeBrightnessValue(input.brightness),
 		brightnessMode: normalizeBrightnessMode(input.brightnessMode),
+		screenIdleMinutes: normalizeScreenIdleMinutes(input.screenIdleMinutes),
+		screenIdleUnit: normalizeScreenIdleUnit(input.screenIdleUnit),
+		screenSleepMode: normalizeScreenSleepMode(input.screenSleepMode),
+		screenSleepDimBrightness: normalizeScreenSleepDimBrightness(
+			input.screenSleepDimBrightness,
+		),
 	} satisfies StoredDeviceSetupInput;
 
 	try {
diff --git a/app/src/models/DeviceSetupInput.ts b/app/src/models/DeviceSetupInput.ts
index 47b800d..219b7c3 100644
--- a/app/src/models/DeviceSetupInput.ts
+++ b/app/src/models/DeviceSetupInput.ts
@@ -1,6 +1,8 @@
 import type { BudpyConfig } from "@budpy/plugin-sdk";
 
 export type BrightnessMode = BudpyConfig["brightnessMode"];
+export type ScreenSleepMode = BudpyConfig["screenSleepMode"];
+export type ScreenIdleUnit = "minutes" | "hours";
 
 export interface DeviceSetupInput {
 	ssid: string;
@@ -8,4 +10,8 @@ export interface DeviceSetupInput {
 	backgroundColor?: string;
 	brightness?: number;
 	brightnessMode?: BrightnessMode;
+	screenIdleMinutes?: number;
+	screenIdleUnit?: ScreenIdleUnit;
+	screenSleepMode?: ScreenSleepMode;
+	screenSleepDimBrightness?: number;
 }
diff --git a/firmware/include/AppConfig.h b/firmware/include/AppConfig.h
index 298fcde..f164386 100644
--- a/firmware/include/AppConfig.h
+++ b/firmware/include/AppConfig.h
@@ -57,6 +57,9 @@ struct AppConfig {
   uint16_t backgroundColor = 0x0000;
   uint8_t brightness = 255;
   bool automaticBrightness = false;
+  uint16_t screenIdleMinutes = 0;
+  bool screenSleepDim = false;
+  uint8_t screenSleepDimBrightness = 12;
   uint8_t cols = 3;
   uint8_t rows = 4;
   uint8_t pageCount = 1;
diff --git a/firmware/include/TouchService.h b/firmware/include/TouchService.h
index 9c21ab4..b148ab2 100644
--- a/firmware/include/TouchService.h
+++ b/firmware/include/TouchService.h
@@ -13,3 +13,8 @@ void touchServiceSetRotation(uint8_t rotation);
 // Retourne true si l'écran est touché, false sinon.
 bool touchServiceRead(int16_t displayWidth, int16_t displayHeight, int16_t& x,
                       int16_t& y);
+
+// Indique si l'écran est actuellement touché (lecture brute de l'IRQ, sans SPI).
+// Peu coûteux: utilisé chaque boucle pour réinitialiser le minuteur d'inactivité
+// ou réveiller l'écran.
+bool touchServiceTouched();
diff --git a/firmware/src/AppConfig.cpp b/firmware/src/AppConfig.cpp
index 227380c..5606cfe 100644
--- a/firmware/src/AppConfig.cpp
+++ b/firmware/src/AppConfig.cpp
@@ -411,6 +411,38 @@ bool parseAppConfig(const JsonDocument& doc, AppConfig& out, String& error) {
     return fail(error, "Unsupported brightnessMode");
   }
 
+  {
+    int16_t idleMinutes = 0;
+    if (!readOptionalIntInRange(root, "screenIdleMinutes", 0, 0, 1440,
+                                idleMinutes, error, "screenIdleMinutes")) {
+      return false;
+    }
+    parsed.screenIdleMinutes = static_cast<uint16_t>(idleMinutes);
+  }
+
+  String screenSleepMode = "off";
+  if (!readOptionalString(root, "screenSleepMode", "off", screenSleepMode,
+                          error, "screenSleepMode")) {
+    return false;
+  }
+  if (screenSleepMode == "off") {
+    parsed.screenSleepDim = false;
+  } else if (screenSleepMode == "dim") {
+    parsed.screenSleepDim = true;
+  } else {
+    return fail(error, "Unsupported screenSleepMode");
+  }
+
+  {
+    int16_t dimBrightness = 12;
+    if (!readOptionalIntInRange(root, "screenSleepDimBrightness", 12, 0, 255,
+                                dimBrightness, error,
+                                "screenSleepDimBrightness")) {
+      return false;
+    }
+    parsed.screenSleepDimBrightness = static_cast<uint8_t>(dimBrightness);
+  }
+
   JsonObjectConst device;
   if (!readObject(root, "device", device, error, "device")) {
     return false;
diff --git a/firmware/src/TouchService.cpp b/firmware/src/TouchService.cpp
index 05a18da..525b027 100644
--- a/firmware/src/TouchService.cpp
+++ b/firmware/src/TouchService.cpp
@@ -105,3 +105,7 @@ bool touchServiceRead(int16_t displayWidth, int16_t displayHeight, int16_t& x,
   y = static_cast<int16_t>(constrain(mappedY, 0, displayHeight - 1));
   return true;
 }
+
+bool touchServiceTouched() {
+  return digitalRead(TOUCH_IRQ_PIN) == LOW;
+}
diff --git a/firmware/src/main.cpp b/firmware/src/main.cpp
index 7ef7c5f..e0c3105 100644
--- a/firmware/src/main.cpp
+++ b/firmware/src/main.cpp
@@ -42,6 +42,10 @@ static uint8_t currentBacklightBrightness = 255;
 static bool backlightBrightnessApplied = false;
 static uint8_t targetBacklightBrightness = 255;
 static bool automaticBrightnessTargetReady = false;
+static uint32_t lastActivityMs = 0;
+static bool screenAsleep = false;
+static uint8_t screenSleepBrightness = 0;
+static bool wakeTouchActive = false;
 static uint16_t smoothedLdrReading = 0;
 static uint16_t ldrMinReading = 0;
 static uint16_t ldrMaxReading = LDR_MAX_READING;
@@ -217,6 +221,9 @@ static void loadConfigOrShowStatus() {
   hasConfig = loadAppConfig(appConfig, error);
   runtimeReady = false;
   renderDirty = true;
+  lastActivityMs = millis();
+  screenAsleep = false;
+  wakeTouchActive = false;
 
   const uint16_t backgroundColor =
       hasConfig ? appConfig.backgroundColor : TFT_BLACK;
@@ -274,17 +281,47 @@ void loop() {
     loadConfigOrShowStatus();
   }
 
-  updateAutomaticBrightness();
-
   const uint32_t now = millis();
-  if (runtimeReady && renderer != nullptr &&
-      (renderDirty || now - lastRenderMs >= RENDER_INTERVAL_MS)) {
-    lastRenderMs = now;
-    renderPlugins(*renderer, appConfig, renderDirty);
-    renderDirty = false;
+  const bool touched = touchServiceTouched();
+
+  // Le geste de réveil ne doit pas aussi activer un widget: on supprime la
+  // distribution tactile jusqu'à ce que le doigt se relève après un réveil.
+  if (wakeTouchActive && !touched) {
+    wakeTouchActive = false;
+  }
+
+  if (hasConfig && appConfig.screenIdleMinutes > 0) {
+    const uint32_t idleTimeoutMs =
+        static_cast<uint32_t>(appConfig.screenIdleMinutes) * 60000UL;
+    if (touched) {
+      lastActivityMs = now;
+      if (screenAsleep) {
+        screenAsleep = false;
+        wakeTouchActive = true;
+        applyConfiguredBrightness();
+        renderDirty = true;
+      }
+    } else if (!screenAsleep && now - lastActivityMs >= idleTimeoutMs) {
+      screenAsleep = true;
+      screenSleepBrightness = appConfig.screenSleepDim
+                                  ? appConfig.screenSleepDimBrightness
+                                  : 0;
+      applyBacklightBrightness(screenSleepBrightness);
+    }
   }
 
-  if (runtimeReady && renderer != nullptr) {
-    pollPluginTouch(*renderer, appConfig, renderDirty);
+  if (!screenAsleep) {
+    updateAutomaticBrightness();
+
+    if (runtimeReady && renderer != nullptr &&
+        (renderDirty || now - lastRenderMs >= RENDER_INTERVAL_MS)) {
+      lastRenderMs = now;
+      renderPlugins(*renderer, appConfig, renderDirty);
+      renderDirty = false;
+    }
+
+    if (runtimeReady && renderer != nullptr && !wakeTouchActive) {
+      pollPluginTouch(*renderer, appConfig, renderDirty);
+    }
   }
 }
\ No newline at end of file
diff --git a/packages/plugin-sdk/src/config.ts b/packages/plugin-sdk/src/config.ts
index ef30bfc..2496c2b 100644
--- a/packages/plugin-sdk/src/config.ts
+++ b/packages/plugin-sdk/src/config.ts
@@ -123,6 +123,9 @@ export const BudpyConfigSchema = z.object({
 	backgroundColor: HexColorSchema.default("#000000"),
 	brightness: z.number().int().min(0).max(255).default(255),
 	brightnessMode: BrightnessModeSchema.default("manual"),
+	screenIdleMinutes: z.number().int().min(0).max(1440).default(0),
+	screenSleepMode: z.enum(["off", "dim"]).default("off"),
+	screenSleepDimBrightness: z.number().int().min(0).max(255).default(12),
 	device: z.object({
 		model: z.literal("esp32-2432s028r"),
 		orientation: OrientationSchema,

From cda60f35602395b977095755112cb1aa5ed9ff77 Mon Sep 17 00:00:00 2001
From: Kevin Py <pykevin@gmail.com>
Date: Fri, 3 Jul 2026 18:07:45 +0200
Subject: [PATCH 3/3] 1.3.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index f356a76..8b4319d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "budpy",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "Budpy is an autonomous ESP32 CYD dashboard.",
 	"private": true,
 	"packageManager": "pnpm@11.5.2",