From b653ee18dc1dfb3b011d601dabbd9b270d63947f Mon Sep 17 00:00:00 2001
From: Misiu <t.jagusz@gmail.com>
Date: Thu, 27 Aug 2026 07:52:10 +0200
Subject: [PATCH 1/2] Add display themes and responsive typography

---
 ARCHITECTURE.md                               |  6 ++
 CHANGELOG.md                                  |  7 ++
 WIDGET_CONTRACT.md                            |  6 ++
 .../opendisplay_studio/composer.py            | 22 +++++-
 custom_components/opendisplay_studio/const.py |  2 +-
 .../frontend/opendisplay-studio.js            | 49 ++++++++++++-
 .../opendisplay_studio/manifest.json          |  2 +-
 .../opendisplay_studio/projects.py            | 15 ++++
 .../widgets/weather/widget.liquid             | 73 ++++++++++++++++++-
 .../widgets/weather/widget.yml                |  2 +-
 frontend-src/package-lock.json                |  4 +-
 frontend-src/package.json                     |  2 +-
 frontend-src/src/dev.ts                       |  3 +
 frontend-src/src/odx-app.ts                   | 43 ++++++++++-
 frontend-src/src/services/storage.test.ts     | 10 ++-
 frontend-src/src/services/storage.ts          |  3 +
 frontend-src/src/types.ts                     |  6 ++
 .../src/weather-liquid-contract.test.ts       |  9 +++
 pyproject.toml                                |  2 +-
 tests/test_brand.py                           | 18 +++++
 tests/test_composer.py                        | 20 +++++
 tests/test_projects.py                        | 24 ++++++
 tests/test_release_version.py                 |  2 +-
 23 files changed, 315 insertions(+), 15 deletions(-)
 create mode 100644 tests/test_brand.py

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 827c1be..4bd90c8 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -65,6 +65,12 @@ whole screen, invokes Home Assistant-aware providers, renders Liquid fragments,
 and composes a single TRMNL document. The Renderer App contract remains
 `HTML + width + height -> PNG` and contains no project or HA concepts.
 
+Theme, font family, and text scale are project-level display preferences. The
+composer maps them to TRMNL Framework screen classes before sending the same
+HTML to preview and Media Source. Widgets do not own or duplicate these
+settings; they react to the framework variables and their physical region
+container.
+
 Backend panel registration follows the current Core Dynalite pattern: local
 static files, WebSocket commands, and an admin-only custom panel. Studio is not
 a standalone frontend, so its component model follows the Matter and ZHA
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95280cf..babb764 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.5.1
+
+- Add project-level light and dark TRMNL themes.
+- Add project-level default, classic, and TRMNL font families plus four text scales.
+- Add a short-wide Weather composition for dense grids such as 800×480 at 3×3.
+- Verify bundled Home Assistant brand icon dimensions in CI.
+
 ## 0.5.0
 
 - Introduce self-contained widget packages under `opendisplay_studio/widgets`.
diff --git a/WIDGET_CONTRACT.md b/WIDGET_CONTRACT.md
index ba9275c..2b3050c 100644
--- a/WIDGET_CONTRACT.md
+++ b/WIDGET_CONTRACT.md
@@ -125,6 +125,12 @@ The panel displays the PNG returned by the same renderer used for Media Source.
 Its local widget component is only a temporary loading fallback; it is not a
 second authoritative renderer.
 
+Display-wide presentation is part of the project contract. `theme` maps to
+the TRMNL light or dark screen mode, `fontFamily` selects the default, classic,
+or TRMNL family, and `textScale` selects small, regular, large, or extra-large
+framework typography. These settings must remain outside widget configuration
+so every package shares one predictable display environment.
+
 `--screen-w` and `--screen-h` describe the physical device. Responsive widget
 decisions use the actual CSS region container dimensions, never names such as
 full or half. A package must work for arbitrary device and region sizes.
diff --git a/custom_components/opendisplay_studio/composer.py b/custom_components/opendisplay_studio/composer.py
index 29ec07b..b70a541 100644
--- a/custom_components/opendisplay_studio/composer.py
+++ b/custom_components/opendisplay_studio/composer.py
@@ -32,10 +32,10 @@ class ProjectComposeError(Exception):
 
 STUDIO_STYLES = """
 <style>
-  .studio-screen{width:var(--studio-width)!important;height:var(--studio-height)!important;margin:0!important;padding:0!important;overflow:hidden!important;background:#fff;box-sizing:border-box}
+  .studio-screen{width:var(--studio-width)!important;height:var(--studio-height)!important;margin:0!important;padding:0!important;overflow:hidden!important;background:var(--framework-semantic-canvas-bg-color,#fff)!important;color:var(--framework-semantic-text-primary-text-color,#000);box-sizing:border-box}
   .studio-screen .view--full{width:100%!important;height:100%!important;margin:0!important;padding:0!important;overflow:hidden!important}
   .studio-grid{display:grid;width:100%;height:100%;padding:var(--studio-gap);gap:var(--studio-gap);box-sizing:border-box}
-  .studio-region{position:relative;min-width:0;min-height:0;overflow:hidden;background:#fff;box-sizing:border-box;container-type:size;container-name:od-region}
+  .studio-region{position:relative;min-width:0;min-height:0;overflow:hidden;background:var(--framework-semantic-surface-bg-color,transparent);color:inherit;box-sizing:border-box;container-type:size;container-name:od-region}
   .studio-region>.item{width:100%!important;height:100%!important;margin:0!important;padding:0!important}
   .studio-entity,.studio-entity__content{width:100%;height:100%;box-sizing:border-box}
   .studio-entity__content{display:flex!important;align-items:center;justify-content:center;gap:clamp(4px,4cqh,14px);padding:clamp(7px,7cqh,22px)!important;overflow:hidden}
@@ -74,6 +74,20 @@ def _screen_size(width: int, height: int) -> str:
     return "screen--md"
 
 
+def _screen_preferences(project: Project) -> str:
+    """Map persisted display preferences to TRMNL screen classes."""
+    classes: list[str] = []
+    if project.get("theme", "light") == "dark":
+        classes.append("screen--dark-mode")
+    font_family = project.get("fontFamily", "default")
+    if font_family in {"classic", "trmnl"}:
+        classes.append(f"screen--fonts-{font_family}")
+    text_scale = project.get("textScale", "regular")
+    if text_scale in {"small", "large", "xlarge"}:
+        classes.append(f"screen--text-scale-{text_scale}")
+    return " ".join(classes)
+
+
 def _region_size(
     project: Project, region: dict[str, Any], *, gap: int
 ) -> tuple[float, float]:
@@ -241,8 +255,10 @@ async def async_compose_project(
     body = "".join(fragments)
     size = _screen_size(width, height)
     portrait = " screen--portrait" if height > width else ""
+    preferences = _screen_preferences(project)
+    preference_classes = f" {preferences}" if preferences else ""
     html = (
-        f'<main class="screen {mode} {size}{portrait} studio-screen" '
+        f'<main class="screen {mode} {size}{portrait}{preference_classes} studio-screen" '
         f'style="--studio-width:{width}px;--studio-height:{height}px;'
         f"--screen-w:{width}px;--screen-h:{height}px;"
         f'--studio-gap:{layout_gap}px">{STUDIO_STYLES}<div class="view view--full">'
diff --git a/custom_components/opendisplay_studio/const.py b/custom_components/opendisplay_studio/const.py
index 454fce6..e0ec335 100644
--- a/custom_components/opendisplay_studio/const.py
+++ b/custom_components/opendisplay_studio/const.py
@@ -6,7 +6,7 @@
 
 DOMAIN = "opendisplay_studio"
 NAME = "OpenDisplay Studio"
-INTEGRATION_VERSION = "0.5.0"
+INTEGRATION_VERSION = "0.5.1"
 
 API_VERSION = 1
 MIN_RENDERER_VERSION = "0.5.0"
diff --git a/custom_components/opendisplay_studio/frontend/opendisplay-studio.js b/custom_components/opendisplay_studio/frontend/opendisplay-studio.js
index 49a33f7..0b3b291 100644
--- a/custom_components/opendisplay_studio/frontend/opendisplay-studio.js
+++ b/custom_components/opendisplay_studio/frontend/opendisplay-studio.js
@@ -2703,6 +2703,9 @@ var tt = (e) => e <= 1.6 ? {
 		name: e,
 		status: "draft",
 		language: t,
+		theme: "light",
+		fontFamily: "default",
+		textScale: "regular",
 		displayId: n.id,
 		orientation: r,
 		palette: n.defaultPalette,
@@ -3469,6 +3472,26 @@ var Z = (e, t) => {
 			palette: t
 		}));
 	}
+	changeTheme(e) {
+		this.updateLayoutDraft((t) => ({
+			...t,
+			theme: e
+		}));
+	}
+	changeFontFamily(e) {
+		let t = e.currentTarget.value;
+		this.updateLayoutDraft((e) => ({
+			...e,
+			fontFamily: t
+		}));
+	}
+	changeTextScale(e) {
+		let t = e.currentTarget.value;
+		this.updateLayoutDraft((e) => ({
+			...e,
+			textScale: t
+		}));
+	}
 	changeOrientation(e) {
 		if (e === this.canvasProject.orientation) return;
 		let t = this.canvasProject.displayId === "custom" ? {
@@ -3656,6 +3679,30 @@ var Z = (e, t) => {
             ${(e.displayId === "custom" ? Object.keys(R) : t.palettes).map((e) => C`<option value=${e}>${R[e]}</option>`)}
           </select>
         </div>
+        <div class="control">
+          <span class="field-label">Theme</span>
+          <div class="segment" role="group" aria-label="Display theme">
+            <button class=${e.theme === "light" ? "active" : ""} @click=${() => this.changeTheme("light")}>Light</button>
+            <button class=${e.theme === "dark" ? "active" : ""} @click=${() => this.changeTheme("dark")}>Dark</button>
+          </div>
+        </div>
+        <div class="control">
+          <label for="font-family">Font family</label>
+          <select id="font-family" .value=${e.fontFamily} @change=${this.changeFontFamily}>
+            <option value="default">Default</option>
+            <option value="classic">Classic</option>
+            <option value="trmnl">TRMNL</option>
+          </select>
+        </div>
+        <div class="control">
+          <label for="text-scale">Text scale</label>
+          <select id="text-scale" .value=${e.textScale} @change=${this.changeTextScale}>
+            <option value="small">Small</option>
+            <option value="regular">Regular</option>
+            <option value="large">Large</option>
+            <option value="xlarge">Extra large</option>
+          </select>
+        </div>
         <div class="control">
           <span class="field-label">Orientation</span>
           <div class="segment" role="group" aria-label="Display orientation">
@@ -3678,7 +3725,7 @@ var Z = (e, t) => {
         <div class="device-summary">
           <span class="step-kicker">Step 2 · Widgets</span>
           <strong>${this.displayName(this.project)}</strong>
-          <span>${e.width}×${e.height} · ${R[this.project.palette]} · ${this.project.grid.columns}×${this.project.grid.rows} grid</span>
+          <span>${e.width}×${e.height} · ${R[this.project.palette]} · ${this.project.theme} · ${this.project.fontFamily}/${this.project.textScale} · ${this.project.grid.columns}×${this.project.grid.rows} grid</span>
         </div>
         <ha-button size="s" appearance="outlined" @click=${this.openLayoutEditor}>${J(Qe)} Edit device & layout</ha-button>
       </div>
diff --git a/custom_components/opendisplay_studio/manifest.json b/custom_components/opendisplay_studio/manifest.json
index 764a88f..24765e6 100644
--- a/custom_components/opendisplay_studio/manifest.json
+++ b/custom_components/opendisplay_studio/manifest.json
@@ -11,5 +11,5 @@
   "issue_tracker": "https://github.com/Misiu/OpenDisplay-Studio-Integration/issues",
   "requirements": ["python-liquid==2.3.1"],
   "single_config_entry": true,
-  "version": "0.5.0"
+  "version": "0.5.1"
 }
diff --git a/custom_components/opendisplay_studio/projects.py b/custom_components/opendisplay_studio/projects.py
index af210d1..70c389d 100644
--- a/custom_components/opendisplay_studio/projects.py
+++ b/custom_components/opendisplay_studio/projects.py
@@ -23,6 +23,9 @@
 MAX_NAME_LENGTH = 100
 MAX_TEXT_LENGTH = 4_096
 PALETTES = {"bw", "gray4", "gray16", "bwr", "bwy", "bwry", "spectra6"}
+DISPLAY_THEMES = {"light", "dark"}
+FONT_FAMILIES = {"default", "classic", "trmnl"}
+TEXT_SCALES = {"small", "regular", "large", "xlarge"}
 LANGUAGE_PATTERN = re.compile(r"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$")
 WIDGET_VERSION_PATTERN = re.compile(
     r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$"
@@ -172,6 +175,15 @@ def validate_project(value: object, registry: WidgetRegistry | None = None) -> P
         language != "system" and LANGUAGE_PATTERN.fullmatch(language) is None
     ):
         raise ProjectValidationError("language is invalid")
+    theme = value.get("theme", "light")
+    if theme not in DISPLAY_THEMES:
+        raise ProjectValidationError("theme is invalid")
+    font_family = value.get("fontFamily", "default")
+    if font_family not in FONT_FAMILIES:
+        raise ProjectValidationError("fontFamily is invalid")
+    text_scale = value.get("textScale", "regular")
+    if text_scale not in TEXT_SCALES:
+        raise ProjectValidationError("textScale is invalid")
     grid = value.get("grid")
     if not isinstance(grid, dict):
         raise ProjectValidationError("grid must be an object")
@@ -284,6 +296,9 @@ def validate_project(value: object, registry: WidgetRegistry | None = None) -> P
         "name": name,
         "status": status,
         "language": language,
+        "theme": theme,
+        "fontFamily": font_family,
+        "textScale": text_scale,
         "displayId": display_id or "custom",
         "width": width,
         "height": height,
diff --git a/custom_components/opendisplay_studio/widgets/weather/widget.liquid b/custom_components/opendisplay_studio/widgets/weather/widget.liquid
index a93b441..330ff8f 100644
--- a/custom_components/opendisplay_studio/widgets/weather/widget.liquid
+++ b/custom_components/opendisplay_studio/widgets/weather/widget.liquid
@@ -320,6 +320,24 @@
     </div>
   </section>
 
+  <section class="od-weather__composition od-weather__composition--strip" data-weather-composition="strip">
+    <div class="layout">
+      <div class="od-weather__strip-content">
+        <img class="image--adaptive" alt="{{ current.condition_label }}" src="{{ current.icon }}">
+        <span class="value value--tnums" data-fit-value="true">{{ current.temperature }}°</span>
+        <div class="od-weather__strip-summary">
+          <span class="value">{{ current.condition_label }}</span>
+          <span class="label">{{ current.labels.right_now }}</span>
+        </div>
+      </div>
+    </div>
+    <div class="title_bar">
+      <img class="image image--adaptive" alt="" src="https://trmnl.com/images/plugins/weather--render.svg">
+      <h1 class="title">{{ current.updated_at }}</h1>
+      <span class="instance">{{ current.name }}</span>
+    </div>
+  </section>
+
   <section class="od-weather__composition od-weather__composition--minimal" data-weather-composition="minimal">
     <div class="layout">
       <div class="od-weather__minimal-content">
@@ -389,6 +407,50 @@
     gap: 4px;
   }
 
+  .od-weather__strip-content {
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: clamp(8px, 3cqw, 28px);
+    overflow: hidden;
+  }
+
+  .od-weather__strip-content > img {
+    width: min(21cqw, 88px);
+    height: min(62cqh, 88px);
+    flex: 0 1 auto;
+    object-fit: contain;
+  }
+
+  .od-weather__strip-content > .value {
+    flex: 0 1 auto;
+    font-size: clamp(
+      calc(28px * var(--text-ui-scale, 1)),
+      calc(12cqw * var(--text-ui-scale, 1)),
+      calc(64px * var(--text-ui-scale, 1))
+    );
+    line-height: 0.9;
+    white-space: nowrap;
+  }
+
+  .od-weather__strip-summary {
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    overflow: hidden;
+  }
+
+  .od-weather__strip-summary > span {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
   .od-weather__minimal-content img {
     width: min(78cqw, 145px);
     height: min(60cqh, 120px);
@@ -396,7 +458,11 @@
   }
 
   .od-weather__minimal-content .value {
-    font-size: clamp(38px, 25cqw, 56px);
+    font-size: clamp(
+      calc(38px * var(--text-ui-scale, 1)),
+      calc(25cqw * var(--text-ui-scale, 1)),
+      calc(56px * var(--text-ui-scale, 1))
+    );
     line-height: 1;
     white-space: nowrap;
   }
@@ -406,6 +472,11 @@
     .od-weather__composition--wide { display: grid; }
   }
 
+  @container weather (min-width: 361px) and (max-height: 199px) {
+    .od-weather__composition { display: none; }
+    .od-weather__composition--strip { display: grid; }
+  }
+
   @container weather (min-width: 300px) and (max-width: 619px) and (min-height: 340px) {
     .od-weather__composition { display: none; }
     .od-weather__composition--tall { display: grid; }
diff --git a/custom_components/opendisplay_studio/widgets/weather/widget.yml b/custom_components/opendisplay_studio/widgets/weather/widget.yml
index 52adc5b..90cddd2 100644
--- a/custom_components/opendisplay_studio/widgets/weather/widget.yml
+++ b/custom_components/opendisplay_studio/widgets/weather/widget.yml
@@ -1,6 +1,6 @@
 id: weather
 name: Weather
-version: "0.5.0"
+version: "0.5.1"
 description: Current conditions and a daily Home Assistant forecast.
 icon: mdi:weather-partly-cloudy
 framework: 3.2.0
diff --git a/frontend-src/package-lock.json b/frontend-src/package-lock.json
index 3313e66..59fa2f0 100644
--- a/frontend-src/package-lock.json
+++ b/frontend-src/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "opendisplay-studio-ha-panel",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "opendisplay-studio-ha-panel",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "dependencies": {
         "@mdi/js": "^7.4.47",
         "lit": "^3.3.3"
diff --git a/frontend-src/package.json b/frontend-src/package.json
index 886731b..e91eabd 100644
--- a/frontend-src/package.json
+++ b/frontend-src/package.json
@@ -1,7 +1,7 @@
 {
   "name": "opendisplay-studio-ha-panel",
   "private": true,
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "scripts": {
     "dev": "vite build --watch",
diff --git a/frontend-src/src/dev.ts b/frontend-src/src/dev.ts
index 0686545..7eddcfd 100644
--- a/frontend-src/src/dev.ts
+++ b/frontend-src/src/dev.ts
@@ -37,6 +37,9 @@ let projects: ScreenProject[] = [
     name: 'Kitchen dashboard',
     status: 'ready',
     language: 'en',
+    theme: 'light',
+    fontFamily: 'default',
+    textScale: 'regular',
     displayId: 'opendisplay-e1001',
     width: 800,
     height: 480,
diff --git a/frontend-src/src/odx-app.ts b/frontend-src/src/odx-app.ts
index df40bd2..9de5cf4 100644
--- a/frontend-src/src/odx-app.ts
+++ b/frontend-src/src/odx-app.ts
@@ -30,12 +30,15 @@ import type {
   BootstrapResponse,
   CellCoordinate,
   ComposePreviewResponse,
+  DisplayTheme,
+  FontFamily,
   GridRegion,
   HomeAssistant,
   Orientation,
   PaletteId,
   PersistedState,
   ScreenProject,
+  TextScale,
   WidgetDefinition,
   WidgetConfigValue,
   WidgetOption,
@@ -462,6 +465,20 @@ export class OdxApp extends LitElement {
     this.updateLayoutDraft((project) => ({ ...project, palette }))
   }
 
+  private changeTheme(theme: DisplayTheme): void {
+    this.updateLayoutDraft((project) => ({ ...project, theme }))
+  }
+
+  private changeFontFamily(event: Event): void {
+    const fontFamily = (event.currentTarget as HTMLSelectElement).value as FontFamily
+    this.updateLayoutDraft((project) => ({ ...project, fontFamily }))
+  }
+
+  private changeTextScale(event: Event): void {
+    const textScale = (event.currentTarget as HTMLSelectElement).value as TextScale
+    this.updateLayoutDraft((project) => ({ ...project, textScale }))
+  }
+
   private changeOrientation(orientation: Orientation): void {
     if (orientation === this.canvasProject.orientation) return
     const grid = this.canvasProject.displayId === 'custom'
@@ -661,6 +678,30 @@ export class OdxApp extends LitElement {
             ${(project.displayId === 'custom' ? Object.keys(PALETTE_LABELS) as PaletteId[] : display.palettes).map((palette) => html`<option value=${palette}>${PALETTE_LABELS[palette]}</option>`)}
           </select>
         </div>
+        <div class="control">
+          <span class="field-label">Theme</span>
+          <div class="segment" role="group" aria-label="Display theme">
+            <button class=${project.theme === 'light' ? 'active' : ''} @click=${() => this.changeTheme('light')}>Light</button>
+            <button class=${project.theme === 'dark' ? 'active' : ''} @click=${() => this.changeTheme('dark')}>Dark</button>
+          </div>
+        </div>
+        <div class="control">
+          <label for="font-family">Font family</label>
+          <select id="font-family" .value=${project.fontFamily} @change=${this.changeFontFamily}>
+            <option value="default">Default</option>
+            <option value="classic">Classic</option>
+            <option value="trmnl">TRMNL</option>
+          </select>
+        </div>
+        <div class="control">
+          <label for="text-scale">Text scale</label>
+          <select id="text-scale" .value=${project.textScale} @change=${this.changeTextScale}>
+            <option value="small">Small</option>
+            <option value="regular">Regular</option>
+            <option value="large">Large</option>
+            <option value="xlarge">Extra large</option>
+          </select>
+        </div>
         <div class="control">
           <span class="field-label">Orientation</span>
           <div class="segment" role="group" aria-label="Display orientation">
@@ -681,7 +722,7 @@ export class OdxApp extends LitElement {
         <div class="device-summary">
           <span class="step-kicker">Step 2 · Widgets</span>
           <strong>${this.displayName(this.project)}</strong>
-          <span>${pixels.width}×${pixels.height} · ${PALETTE_LABELS[this.project.palette]} · ${this.project.grid.columns}×${this.project.grid.rows} grid</span>
+          <span>${pixels.width}×${pixels.height} · ${PALETTE_LABELS[this.project.palette]} · ${this.project.theme} · ${this.project.fontFamily}/${this.project.textScale} · ${this.project.grid.columns}×${this.project.grid.rows} grid</span>
         </div>
         <ha-button size="s" appearance="outlined" @click=${this.openLayoutEditor}>${renderButtonIcon(mdiTuneVariant)} Edit device & layout</ha-button>
       </div>
diff --git a/frontend-src/src/services/storage.test.ts b/frontend-src/src/services/storage.test.ts
index 3e58a20..bc2111e 100644
--- a/frontend-src/src/services/storage.test.ts
+++ b/frontend-src/src/services/storage.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { createProject } from './storage'
 
-describe('project language', () => {
+describe('new project defaults', () => {
   it('pins a new display to the current Home Assistant language', () => {
     expect(createProject('Kuchnia', 'pl').language).toBe('pl')
   })
@@ -9,4 +9,12 @@ describe('project language', () => {
   it('keeps English as the standalone development fallback', () => {
     expect(createProject().language).toBe('en')
   })
+
+  it('uses the same baseline display preferences as the renderer contract', () => {
+    const project = createProject()
+
+    expect(project.theme).toBe('light')
+    expect(project.fontFamily).toBe('default')
+    expect(project.textScale).toBe('regular')
+  })
 })
diff --git a/frontend-src/src/services/storage.ts b/frontend-src/src/services/storage.ts
index 661e568..2139d61 100644
--- a/frontend-src/src/services/storage.ts
+++ b/frontend-src/src/services/storage.ts
@@ -15,6 +15,9 @@ export const createProject = (name = 'Kitchen display', language = 'en'): Screen
     name,
     status: 'draft',
     language,
+    theme: 'light',
+    fontFamily: 'default',
+    textScale: 'regular',
     displayId: display.id,
     orientation,
     palette: display.defaultPalette,
diff --git a/frontend-src/src/types.ts b/frontend-src/src/types.ts
index 1c554cd..aa371db 100644
--- a/frontend-src/src/types.ts
+++ b/frontend-src/src/types.ts
@@ -1,6 +1,9 @@
 import type { CSSResult, TemplateResult } from 'lit'
 
 export type Orientation = 'landscape' | 'portrait'
+export type DisplayTheme = 'light' | 'dark'
+export type FontFamily = 'default' | 'classic' | 'trmnl'
+export type TextScale = 'small' | 'regular' | 'large' | 'xlarge'
 
 export type PaletteId =
   | 'bw'
@@ -63,6 +66,9 @@ export interface ScreenProject {
   name: string
   status: 'draft' | 'ready'
   language: string
+  theme: DisplayTheme
+  fontFamily: FontFamily
+  textScale: TextScale
   displayId: string
   driverId?: string
   orientation: Orientation
diff --git a/frontend-src/src/weather-liquid-contract.test.ts b/frontend-src/src/weather-liquid-contract.test.ts
index 1ae3973..aa48b2a 100644
--- a/frontend-src/src/weather-liquid-contract.test.ts
+++ b/frontend-src/src/weather-liquid-contract.test.ts
@@ -79,6 +79,15 @@ describe('Weather LiquidJS contract', () => {
     await expect(render(current, false)).resolves.toContain('12°')
   })
 
+  it('includes a dedicated composition for short wide regions', async () => {
+    const html = await render(current)
+
+    expect(html).toContain('data-weather-composition="strip"')
+    expect(html).toContain(
+      '@container weather (min-width: 361px) and (max-height: 199px)',
+    )
+  })
+
   it('renders localized vocabulary supplied by Home Assistant', async () => {
     const html = await render({
       ...current,
diff --git a/pyproject.toml b/pyproject.toml
index 5a45673..1a2f9e8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "opendisplay-studio-integration"
-version = "0.5.0"
+version = "0.5.1"
 requires-python = ">=3.14.2"
 
 [tool.pytest.ini_options]
diff --git a/tests/test_brand.py b/tests/test_brand.py
new file mode 100644
index 0000000..a6cd2a5
--- /dev/null
+++ b/tests/test_brand.py
@@ -0,0 +1,18 @@
+"""Tests for locally bundled Home Assistant brand images."""
+
+from pathlib import Path
+from struct import unpack
+
+BRAND = Path(__file__).parents[1] / "custom_components" / "opendisplay_studio" / "brand"
+
+
+def _png_size(path: Path) -> tuple[int, int]:
+    payload = path.read_bytes()
+    assert payload.startswith(b"\x89PNG\r\n\x1a\n")
+    assert payload[12:16] == b"IHDR"
+    return unpack(">II", payload[16:24])
+
+
+def test_local_brand_icons_match_home_assistant_dimensions() -> None:
+    assert _png_size(BRAND / "icon.png") == (256, 256)
+    assert _png_size(BRAND / "icon@2x.png") == (512, 512)
diff --git a/tests/test_composer.py b/tests/test_composer.py
index a47ff1e..7ba8d9b 100644
--- a/tests/test_composer.py
+++ b/tests/test_composer.py
@@ -117,6 +117,26 @@ async def test_entity_requirements_are_deduplicated(hass) -> None:
     assert 'data-region-width="388.000"' in result.html
 
 
+async def test_display_preferences_become_trmnl_screen_classes(hass) -> None:
+    project = {
+        "theme": "dark",
+        "fontFamily": "classic",
+        "textScale": "small",
+        "palette": "bw",
+        "width": 400,
+        "height": 300,
+        "grid": {"columns": 1, "rows": 1},
+        "regions": [],
+    }
+
+    result = await async_compose_project(hass, project)
+
+    assert "screen--dark-mode" in result.html
+    assert "screen--fonts-classic" in result.html
+    assert "screen--text-scale-small" in result.html
+    assert "var(--framework-semantic-canvas-bg-color,#fff)" in result.html
+
+
 async def test_provider_error_is_exposed_as_compose_error(hass) -> None:
     project = {
         "palette": "bw",
diff --git a/tests/test_projects.py b/tests/test_projects.py
index d75b182..6c9cdb0 100644
--- a/tests/test_projects.py
+++ b/tests/test_projects.py
@@ -96,6 +96,30 @@ def test_project_language_defaults_to_system_and_accepts_bcp47() -> None:
     assert validate_project(payload)["language"] == "pt-BR"
 
 
+def test_display_preferences_have_safe_defaults() -> None:
+    result = validate_project(project_payload())
+
+    assert result["theme"] == "light"
+    assert result["fontFamily"] == "default"
+    assert result["textScale"] == "regular"
+
+
+@pytest.mark.parametrize(
+    ("key", "value"),
+    [
+        ("theme", "system"),
+        ("fontFamily", "comic-sans"),
+        ("textScale", "tiny"),
+    ],
+)
+def test_display_preferences_reject_unknown_values(key: str, value: str) -> None:
+    payload = project_payload()
+    payload[key] = value
+
+    with pytest.raises(ProjectValidationError, match=key):
+        validate_project(payload)
+
+
 @pytest.mark.parametrize("language", ["", "polish", "../pl", "pl_PL"])
 def test_project_language_rejects_invalid_values(language: str) -> None:
     payload = project_payload()
diff --git a/tests/test_release_version.py b/tests/test_release_version.py
index f035f1b..826f44d 100644
--- a/tests/test_release_version.py
+++ b/tests/test_release_version.py
@@ -23,7 +23,7 @@ def test_release_rejects_mismatch(tmp_path) -> None:
 
 
 def test_panel_build_version_matches_release() -> None:
-    assert INTEGRATION_VERSION == "0.5.0"
+    assert INTEGRATION_VERSION == "0.5.1"
 
 
 def test_panel_does_not_bundle_home_assistant_component_implementations() -> None:

From 0dfc977145e217b0deff0f2c5bdbbd387164ed3c Mon Sep 17 00:00:00 2001
From: Misiu <t.jagusz@gmail.com>
Date: Thu, 27 Aug 2026 18:12:14 +0200
Subject: [PATCH 2/2] Use shared TRMNL Liquid package

---
 CHANGELOG.md                                  |   4 +
 README.md                                     |  11 +-
 STAGE2_COMPATIBILITY.md                       |  55 ++++----
 .../opendisplay_studio/composer.py            |  25 ++--
 .../opendisplay_studio/liquid_renderer.py     | 122 ------------------
 .../opendisplay_studio/manifest.json          |   2 +-
 .../opendisplay_studio/media_source.py        |   3 +-
 .../opendisplay_studio/screens.py             |  33 +++--
 .../opendisplay_studio/websocket.py           |   3 +-
 pyproject.toml                                |   2 +-
 requirements_test.txt                         |   2 +-
 tests/test_composer.py                        |  31 +++++
 tests/test_liquid_renderer.py                 |  61 ---------
 tests/test_trmnl_liquid.py                    |  69 ++++++++++
 14 files changed, 168 insertions(+), 255 deletions(-)
 delete mode 100644 custom_components/opendisplay_studio/liquid_renderer.py
 delete mode 100644 tests/test_liquid_renderer.py
 create mode 100644 tests/test_trmnl_liquid.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index babb764..54f6728 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@
 
 ## 0.5.1
 
+- Replace the integration-owned Liquid subset with `trmnl-liquid-py` 0.1.0,
+  matching the supported non-I18n TRMNL Liquid 0.8.2 rendering surface.
+- Validate every bundled widget template against the shared TRMNL engine and
+  cover lax missing-data and inline-template behavior with regression tests.
 - Add project-level light and dark TRMNL themes.
 - Add project-level default, classic, and TRMNL font families plus four text scales.
 - Add a short-wide Weather composition for dense grids such as 800×480 at 3×3.
diff --git a/README.md b/README.md
index 42666e2..4eefff7 100644
--- a/README.md
+++ b/README.md
@@ -24,11 +24,12 @@ media-source://opendisplay_studio/<project-id>
 
 On every resolution the integration deduplicates widget data requirements,
 reads current entity states, calendar events, and requested weather forecasts,
-renders widget Liquid templates, composes one TRMNL Framework document, and
-sends that final HTML to the Renderer. The Renderer App still knows only HTML,
-width, and height. The designer preview calls this same Renderer path and shows
-its PNG, so the visible preview and final Media Source do not have separate CSS
-or layout implementations.
+renders widget Liquid templates through
+[`trmnl-liquid-py`](https://github.com/Misiu/trmnl-liquid-py), composes one
+TRMNL Framework document, and sends that final HTML to the Renderer. The
+Renderer App still knows only HTML, width, and height. The designer preview
+calls this same Renderer path and shows its PNG, so the visible preview and
+final Media Source do not have separate CSS or layout implementations.
 
 See [the widget contract](WIDGET_CONTRACT.md) for the schema/data/template
 boundary, native Home Assistant selectors, and the controlled provider model.
diff --git a/STAGE2_COMPATIBILITY.md b/STAGE2_COMPATIBILITY.md
index a8ce0c6..fc91202 100644
--- a/STAGE2_COMPATIBILITY.md
+++ b/STAGE2_COMPATIBILITY.md
@@ -8,41 +8,32 @@ height. The App has no Liquid dependency or template API.
 
 ## Liquid engine
 
-The integration pins `python-liquid==2.3.1`, a Python implementation tested
-against Shopify's Golden Liquid suite. It runs in strict mode, has no filesystem
-loader, auto-escapes variables, and applies limits for block depth, context
-depth, loop iterations, local variables, and output bytes.
-
-Supported in the POC:
-
-- variables and nested mapping/list access;
-- `assign`, `capture`, `if`/`elsif`/`else`, `unless`, `case`, `for`, `break`,
-  `continue`, and standard Shopify filters supplied by Python Liquid;
-- selected TRMNL filters ported from `trmnl-liquid` 0.8.2:
-  `number_with_delimiter`, `json`, `parse_json`, `map_to_i`, `group_by`, and
-  `find_by`.
-
-Not yet ported:
-
-- TRMNL's custom `{% template %}` tag;
-- `where_exp`, QR code, Markdown, locale/Rails helpers, currency, ordinal, and
-  timezone-specific filters;
-- arbitrary user templates or Home Assistant entity bindings.
-
-The official `usetrmnl/byos_node_lite` reference does not use Ruby either. It
-uses LiquidJS with strict filters and variables inside its Node server. That is
-useful compatibility evidence, but moving Liquid into this project's App would
-violate the renderer-only boundary. A fuller Python port can become a separate
-integration-side package after the POC.
+The integration pins
+[`trmnl-liquid-py==0.1.0`](https://github.com/Misiu/trmnl-liquid-py). The package
+targets byte-for-byte compatibility with the supported non-I18n surface of Ruby
+`trmnl-liquid` 0.8.2. Its differential corpus currently matches all 574 covered
+Ruby outputs and maps all 73 upstream RSpec examples.
+
+The shared package supplies the standard Liquid language, TRMNL's inline
+`{% template %}` tag, Ruby-compatible lax syntax and runtime behavior, Markdown,
+QR generation, and the supported TRMNL filters. Rendering intentionally follows
+TRMNL's unescaped, lax semantics; missing provider fields become empty Liquid
+values instead of failing an otherwise renderable display. Each widget fragment
+uses a fresh in-memory environment, so inline template definitions cannot leak
+between installed widgets and Liquid has no filesystem fallback.
+
+Rails/ActionView behavior and full I18n implementations of `l_word` and `l_date`
+remain outside the package's 0.1.0 compatibility target. Widget-owned translation
+files and Home Assistant localization handle OpenDisplay Studio presentation
+language independently of those Rails helpers.
 
 ## TRMNL Liquid Components
 
 The stat/item, table, and progress structures were adapted from the MIT-licensed
 `usetrmnl/trmnl-liquid-components` repository at commit
-`77445360fb10b0d9edd2b28ffe574574ae563417`. Its custom `{% template %}` wrapper
-was deliberately removed because that tag is outside the current subset. The
-resulting HTML uses the same public Framework classes and renders as one DOM and
-one screenshot.
+`77445360fb10b0d9edd2b28ffe574574ae563417`. Installed widgets may now use the
+same `{% template %}` and `{% render %}` primitives as TRMNL. The resulting HTML
+uses the public Framework classes and renders as one DOM and one screenshot.
 
 ## Display profiles and palettes
 
@@ -61,5 +52,5 @@ not final e-paper quantization or dithering by OpenDisplay.
 
 The App bundles TRMNL Framework 3.2.0 CSS/JS and fonts with upstream MIT, OFL,
 and CC BY notices. It contains no Highcharts distribution or plugin image
-bundle. The integration's Python Liquid dependency and the adapted Liquid
-Components source are MIT licensed. No render path requires Internet access.
+bundle. The integration's `trmnl-liquid-py` dependency and the adapted Liquid
+Components source are MIT licensed.
diff --git a/custom_components/opendisplay_studio/composer.py b/custom_components/opendisplay_studio/composer.py
index b70a541..4ad9d20 100644
--- a/custom_components/opendisplay_studio/composer.py
+++ b/custom_components/opendisplay_studio/composer.py
@@ -9,9 +9,10 @@
 
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import HomeAssistantError
+from liquid.exceptions import LiquidError
+from trmnl_liquid import render as render_liquid
 
 from .const import DOMAIN
-from .liquid_renderer import LIQUID
 from .projects import Project
 from .widgets import DEFAULT_REGISTRY, WidgetRegistry, definition, with_defaults
 
@@ -218,16 +219,18 @@ async def async_compose_project(
                 resolved,
                 registry,
             )
-            result = LIQUID.render(
-                registry.template(widget_type),
-                {
-                    "config": config,
-                    "data": data,
-                    "region": {"shape": _region_shape(project, region, gap=layout_gap)},
-                },
-            )
-            fragment = result.html
-            liquid_ms += result.milliseconds
+            liquid_started = perf_counter()
+            try:
+                fragment = render_liquid(
+                    registry.template(widget_type),
+                    config=config,
+                    data=data,
+                    region={"shape": _region_shape(project, region, gap=layout_gap)},
+                )
+            except LiquidError as err:
+                message = f"Could not render {widget_type} widget: {err}"
+                raise ProjectComposeError(message) from err
+            liquid_ms += (perf_counter() - liquid_started) * 1_000
         region_width, region_height = _region_size(project, region, gap=layout_gap)
         ratio = region_width / max(1, region_height)
         style = (
diff --git a/custom_components/opendisplay_studio/liquid_renderer.py b/custom_components/opendisplay_studio/liquid_renderer.py
deleted file mode 100644
index 7caabc1..0000000
--- a/custom_components/opendisplay_studio/liquid_renderer.py
+++ /dev/null
@@ -1,122 +0,0 @@
-"""Bounded Liquid rendering for OpenDisplay Studio documents."""
-
-from __future__ import annotations
-
-import json
-import re
-from collections.abc import Iterable, Mapping
-from dataclasses import dataclass
-from time import perf_counter
-from typing import Any
-
-from liquid import Environment
-from liquid.exceptions import LiquidError
-from liquid.undefined import StrictDefaultUndefined
-
-MAX_LIQUID_OUTPUT_BYTES = 1_000_000
-
-
-class TemplateRenderError(Exception):
-    """A Liquid document could not be parsed or rendered safely."""
-
-
-@dataclass(frozen=True, slots=True)
-class LiquidResult:
-    """Rendered HTML and measured template processing time."""
-
-    html: str
-    milliseconds: float
-
-
-def _number_with_delimiter(
-    value: object, delimiter: str = ",", separator: str = "."
-) -> str:
-    try:
-        raw = str(value)
-        whole, dot, fraction = raw.partition(".")
-        parsed = int(whole)
-    except TypeError, ValueError:
-        return str(value)
-    grouped = f"{parsed:,}".replace(",", delimiter)
-    return f"{grouped}{separator}{fraction}" if dot else grouped
-
-
-def _json(value: object) -> str:
-    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
-
-
-def _parse_json(value: object) -> object:
-    return json.loads(str(value))
-
-
-def _map_to_i(values: Iterable[object]) -> list[int]:
-    converted: list[int] = []
-    for value in values:
-        match = re.match(r"\s*([+-]?\d+)", str(value))
-        converted.append(int(match.group(1)) if match else 0)
-    return converted
-
-
-def _group_by(values: Iterable[object], key: str) -> dict[Any, list[object]]:
-    groups: dict[Any, list[object]] = {}
-    for value in values:
-        group = value.get(key) if isinstance(value, Mapping) else None
-        groups.setdefault(group, []).append(value)
-    return groups
-
-
-def _find_by(
-    values: Iterable[object], key: str, expected: object, fallback: object = None
-) -> object:
-    return next(
-        (
-            value
-            for value in values
-            if isinstance(value, Mapping) and value.get(key) == expected
-        ),
-        fallback,
-    )
-
-
-class _BoundedEnvironment(Environment):
-    context_depth_limit = 20
-    loop_iteration_limit = 5_000
-    local_namespace_limit = 10_000
-    output_stream_limit = MAX_LIQUID_OUTPUT_BYTES
-
-
-class TrmnlLiquidRenderer:
-    """Render a compatibility-focused subset of TRMNL Liquid in memory."""
-
-    def __init__(self) -> None:
-        """Initialize a strict in-memory environment with resource limits."""
-        environment = _BoundedEnvironment(
-            undefined=StrictDefaultUndefined,
-            strict_filters=True,
-            autoescape=True,
-        )
-        environment.add_filter("number_with_delimiter", _number_with_delimiter)
-        environment.add_filter("json", _json)
-        environment.add_filter("parse_json", _parse_json)
-        environment.add_filter("map_to_i", _map_to_i)
-        environment.add_filter("group_by", _group_by)
-        environment.add_filter("find_by", _find_by)
-        self._environment = environment
-
-    def render(self, source: str, data: Mapping[str, Any]) -> LiquidResult:
-        """Parse and render one template without filesystem or network access."""
-        started = perf_counter()
-        try:
-            template = self._environment.from_string(source)
-            html = template.render(dict(data))
-        except (LiquidError, TypeError, ValueError, json.JSONDecodeError) as err:
-            raise TemplateRenderError(str(err)) from err
-        if len(html.encode()) > MAX_LIQUID_OUTPUT_BYTES:
-            raise TemplateRenderError("Liquid output exceeds the configured limit")
-        return LiquidResult(
-            html=html,
-            milliseconds=(perf_counter() - started) * 1_000,
-        )
-
-
-LIQUID = TrmnlLiquidRenderer()
diff --git a/custom_components/opendisplay_studio/manifest.json b/custom_components/opendisplay_studio/manifest.json
index 24765e6..9b4b595 100644
--- a/custom_components/opendisplay_studio/manifest.json
+++ b/custom_components/opendisplay_studio/manifest.json
@@ -9,7 +9,7 @@
   "integration_type": "service",
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/Misiu/OpenDisplay-Studio-Integration/issues",
-  "requirements": ["python-liquid==2.3.1"],
+  "requirements": ["trmnl-liquid-py==0.1.0"],
   "single_config_entry": true,
   "version": "0.5.1"
 }
diff --git a/custom_components/opendisplay_studio/media_source.py b/custom_components/opendisplay_studio/media_source.py
index 79e2d00..1bfec0b 100644
--- a/custom_components/opendisplay_studio/media_source.py
+++ b/custom_components/opendisplay_studio/media_source.py
@@ -20,7 +20,6 @@
 
 from .composer import ProjectComposeError, async_compose_project
 from .const import DOMAIN, LOGGER
-from .liquid_renderer import TemplateRenderError
 from .renderer import RendererClient, RendererError
 
 
@@ -53,7 +52,7 @@ async def async_resolve_media(self, item: MediaSourceItem) -> PlayMedia:
                 width=project["width"],
                 height=project["height"],
             )
-        except (ProjectComposeError, RendererError, TemplateRenderError) as err:
+        except (ProjectComposeError, RendererError) as err:
             LOGGER.error("Could not render %s: %s", item.identifier, err)
             raise Unresolvable(
                 translation_domain=DOMAIN,
diff --git a/custom_components/opendisplay_studio/screens.py b/custom_components/opendisplay_studio/screens.py
index b2d6d7f..21e4e68 100644
--- a/custom_components/opendisplay_studio/screens.py
+++ b/custom_components/opendisplay_studio/screens.py
@@ -4,11 +4,11 @@
 
 from collections.abc import Callable
 from dataclasses import dataclass
+from time import perf_counter
 from typing import Final
 
 from homeassistant.util import dt as dt_util
-
-from .liquid_renderer import LIQUID
+from trmnl_liquid import render as render_liquid
 
 
 @dataclass(frozen=True, slots=True)
@@ -168,23 +168,22 @@ def _palette(mode: str, label: str) -> str:
 def build_liquid_screen() -> BuiltScreen:
     """Render dynamic HTML before Chromium and expose the Liquid time."""
     now = dt_util.now()
-    result = LIQUID.render(
+    started = perf_counter()
+    html = render_liquid(
         LIQUID_TEMPLATE,
-        {
-            "title": "Liquid · Łódź",
-            "generated_at": now.strftime("%H:%M:%S"),
-            "metrics": [
-                {"label": "Temperatura", "value": 21.4, "unit": "°C"},
-                {"label": "Wilgotność", "value": 47, "unit": "%"},
-                {"label": "Ciśnienie", "value": 1017, "unit": " hPa"},
-            ],
-            "events": [
-                {"time": "10:00", "title": "Spotkanie produkcyjne"},
-                {"time": "16:00", "title": "Przegląd projektu"},
-            ],
-        },
+        title="Liquid · Łódź",
+        generated_at=now.strftime("%H:%M:%S"),
+        metrics=[
+            {"label": "Temperatura", "value": 21.4, "unit": "°C"},
+            {"label": "Wilgotność", "value": 47, "unit": "%"},
+            {"label": "Ciśnienie", "value": 1017, "unit": " hPa"},
+        ],
+        events=[
+            {"time": "10:00", "title": "Spotkanie produkcyjne"},
+            {"time": "16:00", "title": "Przegląd projektu"},
+        ],
     )
-    return BuiltScreen(result.html, result.milliseconds)
+    return BuiltScreen(html, (perf_counter() - started) * 1_000)
 
 
 SCREENS: Final = {
diff --git a/custom_components/opendisplay_studio/websocket.py b/custom_components/opendisplay_studio/websocket.py
index f7d5869..1610ff5 100644
--- a/custom_components/opendisplay_studio/websocket.py
+++ b/custom_components/opendisplay_studio/websocket.py
@@ -10,7 +10,6 @@
 
 from .composer import ProjectComposeError, async_compose_project
 from .const import DOMAIN, LOGGER, MIN_RENDERER_VERSION, RENDER_HTTP_PATH
-from .liquid_renderer import TemplateRenderError
 from .projects import (
     ProjectStore,
     ProjectValidationError,
@@ -159,7 +158,7 @@ async def websocket_compose_preview(
     except ProjectValidationError as err:
         _error(connection, msg, err)
         return
-    except (ProjectComposeError, RendererError, TemplateRenderError) as err:
+    except (ProjectComposeError, RendererError) as err:
         LOGGER.warning("Live preview render failed: %s", err)
         connection.send_error(msg["id"], "preview_failed", str(err))
         return
diff --git a/pyproject.toml b/pyproject.toml
index 1a2f9e8..bec416e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -37,7 +37,7 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["ANN", "D", "PLR2004", "S101", "SLF001"]
-"tests/test_liquid_renderer.py" = ["E501"]
+"tests/test_trmnl_liquid.py" = ["E501"]
 "custom_components/opendisplay_studio/screens.py" = ["E501", "RUF001"]
 "custom_components/opendisplay_studio/widgets/entity_state/provider.py" = ["E501"]
 "custom_components/opendisplay_studio/composer.py" = ["E501"]
diff --git a/requirements_test.txt b/requirements_test.txt
index 9324fc4..d41e20d 100644
--- a/requirements_test.txt
+++ b/requirements_test.txt
@@ -5,5 +5,5 @@ pytest
 pytest-aiohttp
 pytest-cov
 pytest-homeassistant-custom-component
-python-liquid==2.3.1
+trmnl-liquid-py==0.1.0
 ruff
diff --git a/tests/test_composer.py b/tests/test_composer.py
index 7ba8d9b..c670b8d 100644
--- a/tests/test_composer.py
+++ b/tests/test_composer.py
@@ -5,6 +5,7 @@
 
 import pytest
 from homeassistant.exceptions import HomeAssistantError
+from liquid.exceptions import LiquidSyntaxError
 
 from custom_components.opendisplay_studio.composer import (
     ProjectComposeError,
@@ -167,6 +168,36 @@ async def test_provider_error_is_exposed_as_compose_error(hass) -> None:
         await async_compose_project(hass, project)
 
 
+async def test_liquid_syntax_error_is_exposed_as_compose_error(hass) -> None:
+    project = {
+        "palette": "bw",
+        "grid": {"columns": 1, "rows": 1},
+        "regions": [
+            {
+                "id": "text",
+                "row": 1,
+                "column": 1,
+                "rowSpan": 1,
+                "columnSpan": 1,
+                "widget": {
+                    "type": "text",
+                    "version": "0.5.0",
+                    "config": {"text": "Broken"},
+                },
+            }
+        ],
+    }
+
+    with (
+        patch(
+            "custom_components.opendisplay_studio.composer.render_liquid",
+            side_effect=LiquidSyntaxError("broken template", token=None),
+        ),
+        pytest.raises(ProjectComposeError, match="Could not render text widget"),
+    ):
+        await async_compose_project(hass, project)
+
+
 async def test_weather_widget_renders_normalized_home_assistant_data(hass) -> None:
     project = {
         "palette": "bw",
diff --git a/tests/test_liquid_renderer.py b/tests/test_liquid_renderer.py
deleted file mode 100644
index 485fe44..0000000
--- a/tests/test_liquid_renderer.py
+++ /dev/null
@@ -1,61 +0,0 @@
-"""Tests for safe and compatible Liquid processing."""
-
-import pytest
-
-from custom_components.opendisplay_studio.liquid_renderer import (
-    TemplateRenderError,
-    TrmnlLiquidRenderer,
-)
-
-
-def test_standard_liquid_constructs_and_trmnl_filters() -> None:
-    result = TrmnlLiquidRenderer().render(
-        "{% for item in items %}{% if item.show %}{{ item.value | number_with_delimiter: ' ' }}{% endif %}{% else %}empty{% endfor %}",
-        {"items": [{"show": True, "value": 12345}, {"show": False, "value": 9}]},
-    )
-    assert result.html == "12 345"
-    assert result.milliseconds >= 0
-
-
-def test_selected_trmnl_filters_match_ruby_contracts() -> None:
-    renderer = TrmnlLiquidRenderer()
-    assert (
-        renderer.render(
-            "{{ values | map_to_i | join: ',' }}", {"values": ["12px", "-4.5", "x"]}
-        ).html
-        == "12,-4,0"
-    )
-    grouped = renderer.render(
-        "{{ values | group_by: 'room' | json }}",
-        {"values": [{"room": "kitchen", "value": 1}, {"room": "kitchen", "value": 2}]},
-    )
-    assert (
-        grouped.html
-        == "{&#34;kitchen&#34;:[{&#34;room&#34;:&#34;kitchen&#34;,&#34;value&#34;:1},{&#34;room&#34;:&#34;kitchen&#34;,&#34;value&#34;:2}]}"
-    )
-
-
-def test_missing_values_require_explicit_default() -> None:
-    renderer = TrmnlLiquidRenderer()
-    assert renderer.render("{{ missing | default: '—' }}", {}).html == "—"
-    with pytest.raises(TemplateRenderError):
-        renderer.render("{{ missing }}", {})
-
-
-def test_empty_data_and_html_escaping() -> None:
-    result = TrmnlLiquidRenderer().render(
-        "{% for item in items %}{{ item }}{% else %}empty{% endfor %} {{ value }}",
-        {"items": [], "value": "<script>bad</script>"},
-    )
-    assert result.html == "empty &lt;script&gt;bad&lt;/script&gt;"
-
-
-def test_malformed_and_unbounded_templates_fail_cleanly() -> None:
-    renderer = TrmnlLiquidRenderer()
-    with pytest.raises(TemplateRenderError):
-        renderer.render("{% if broken %}", {"broken": True})
-    with pytest.raises(TemplateRenderError):
-        renderer.render(
-            "{% for i in (1..100) %}{% for j in (1..100) %}{{ i }}{{ j }}{% endfor %}{% endfor %}",
-            {},
-        )
diff --git a/tests/test_trmnl_liquid.py b/tests/test_trmnl_liquid.py
new file mode 100644
index 0000000..6bc9430
--- /dev/null
+++ b/tests/test_trmnl_liquid.py
@@ -0,0 +1,69 @@
+"""Integration contracts for the shared TRMNL-compatible Liquid package."""
+
+import json
+from pathlib import Path
+
+import pytest
+from trmnl_liquid import Environment, __version__, render
+
+from custom_components.opendisplay_studio.widgets import DEFAULT_REGISTRY
+
+
+def test_manifest_pins_the_tested_trmnl_liquid_version() -> None:
+    manifest_path = (
+        Path(__file__).parents[1]
+        / "custom_components"
+        / "opendisplay_studio"
+        / "manifest.json"
+    )
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+    assert manifest["requirements"] == [f"trmnl-liquid-py=={__version__}"]
+
+
+def test_standard_liquid_constructs_and_trmnl_filters() -> None:
+    html = render(
+        "{% for item in items %}{% if item.show %}{{ item.value | number_with_delimiter: ' ' }}{% endif %}{% else %}empty{% endfor %}",
+        items=[{"show": True, "value": 12345}, {"show": False, "value": 9}],
+    )
+    assert html == "12 345"
+
+
+def test_trmnl_inline_templates_and_filters_are_available() -> None:
+    html = render(
+        "{% template card %}<p>{{ title }}</p>{% endtemplate %}{% render 'card', title: label %}|{{ values | map_to_i | join: ',' }}",
+        label="Weather",
+        values=["12px", "-4.5", "x"],
+    )
+    assert html == "<p>Weather</p>|12,-4,0"
+
+
+def test_rendering_uses_trmnl_lax_and_unescaped_semantics() -> None:
+    assert render("{{ missing }}|{{ value }}", value="<b>ready</b>") == "|<b>ready</b>"
+
+
+def test_lax_parser_matches_trmnl_for_incomplete_template() -> None:
+    assert render("{% if broken %}", broken=True) == ""
+
+
+@pytest.mark.parametrize("widget_type", sorted(DEFAULT_REGISTRY.widget_types))
+def test_every_bundled_widget_template_compiles(widget_type: str) -> None:
+    Environment().from_string(DEFAULT_REGISTRY.template(widget_type))
+
+
+@pytest.mark.parametrize("widget_type", sorted(DEFAULT_REGISTRY.widget_types))
+def test_every_bundled_widget_renders_with_missing_provider_data(
+    widget_type: str,
+) -> None:
+    definition = DEFAULT_REGISTRY.definition(widget_type)
+    data = {requirement["key"]: None for requirement in definition["dataRequirements"]}
+
+    html = render(
+        DEFAULT_REGISTRY.template(widget_type),
+        config=definition["defaults"],
+        data=data,
+        region={"shape": "square"},
+    )
+
+    assert isinstance(html, str)
+    assert html.strip()