Fix: Render issues on button pages

.github/workflows/versioning.yml

@@ -2,13 +2,17 @@
 #
 # Triggered by merging a PR to the main branch, it automatically:
 # 1. Bumps the CalVer version (YYYY.M.seq)
-# 2. Updates the bug report template with current version placeholders
-# 3. Commits the changes and pushes to main
-# 4. Builds pre-built firmware binaries in parallel (nspanel-easy, wall-display)
-# 5. Commits the compiled binaries, checksums, and manifests to main
-# 6. Creates a version tag and GitHub Release
-# 7. Updates the stable and latest floating tags
-# 8. Announces the release on Discord
+# 2. Calculates the minimum upstream version (current month minus 2, YYYY.M.0)
+# 3. Resolves the "next" sentinel in min_blueprint_version, if set
+# 4. Updates min_esphome_compiler_version and blueprint homeassistant.min_version
+# 5. Updates the bug report template with current version placeholders
+# 6. Updates the blueprint version and display name
+# 7. Commits all version changes and pushes to main
+# 8. Builds pre-built firmware binaries in parallel (nspanel-easy, wall-display)
+# 9. Commits the compiled binaries, checksums, and manifests to main
+# 10. Creates a version tag and GitHub Release
+# 11. Updates the stable and latest floating tags
+# 12. Announces the release on Discord
 #
 # The workflow skips execution if the merge commit message contains
 # [skip-versioning] to prevent loops from its own version bump commits.
@@ -152,13 +156,63 @@ jobs:
           echo "version=${NEXT_VERSION}" >> "$GITHUB_OUTPUT"
           echo "Bumping version: $CURRENT_VERSION -> $NEXT_VERSION"
 
+      - name: Calculate minimum upstream versions
+        id: min_upstream
+        if: steps.skip_check.outputs.skip == 'false'
+        run: |
+          # Minimum upstream version is always 2 months behind the current month,
+          # with patch fixed at 0 (e.g. April 2026 -> 2026.2.0, Jan 2026 -> 2025.11.0).
+          # This is the contract for the minimum ESPHome compiler and Home Assistant
+          # versions required to build and run NSPanel Easy.
+          CURRENT_YEAR=$(date +%Y)
+          CURRENT_MONTH=$(date +%-m)  # No leading zero
+
+          MIN_MONTH=$((CURRENT_MONTH - 2))
+          MIN_YEAR=$CURRENT_YEAR
+          if [[ $MIN_MONTH -le 0 ]]; then
+            MIN_MONTH=$((MIN_MONTH + 12))
+            MIN_YEAR=$((MIN_YEAR - 1))
+          fi
+
+          MIN_UPSTREAM_VERSION="${MIN_YEAR}.${MIN_MONTH}.0"
+          echo "version=${MIN_UPSTREAM_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Minimum upstream version: ${MIN_UPSTREAM_VERSION}"
+
       - name: Update version.yaml file
         if: steps.skip_check.outputs.skip == 'false'
         env:
           NEW_VERSION: ${{ steps.next_version.outputs.version }}
         run: |
           yq eval '.version = strenv(NEW_VERSION)' -i ./versioning/version.yaml
 
+      - name: Resolve min_blueprint_version sentinel and update upstream versions
+        if: steps.skip_check.outputs.skip == 'false'
+        env:
+          NEW_VERSION: ${{ steps.next_version.outputs.version }}
+          MIN_UPSTREAM_VERSION: ${{ steps.min_upstream.outputs.version }}
+        run: |
+          ESPHOME_VERSION_FILE="esphome/nspanel_esphome_version.yaml"
+          MIN_BP=$(yq eval '.substitutions.min_blueprint_version' "$ESPHOME_VERSION_FILE")
+
+          # If min_blueprint_version is set to the sentinel "next", replace it
+          # with the actual version being released, tying the compatibility
+          # requirement to this exact release.
+          if [[ "$MIN_BP" == "next" || "$MIN_BP" == '${version}' ]]; then
+            yq eval \
+              '.substitutions.min_blueprint_version = strenv(NEW_VERSION)' \
+              -i "$ESPHOME_VERSION_FILE"
+            echo "Resolved min_blueprint_version sentinel to ${NEW_VERSION}"
+          else
+            echo "min_blueprint_version is already set to ${MIN_BP}, no sentinel to resolve"
+          fi
+
+          # Always update the minimum ESPHome compiler version to 2 months ago,
+          # keeping the upstream contract in sync with the release date.
+          yq eval \
+            '.substitutions.min_esphome_compiler_version = strenv(MIN_UPSTREAM_VERSION)' \
+            -i "$ESPHOME_VERSION_FILE"
+          echo "Updated min_esphome_compiler_version to ${MIN_UPSTREAM_VERSION}"
+
       - name: Extract cross-component version information
         id: versions
         if: steps.skip_check.outputs.skip == 'false'
@@ -189,11 +243,53 @@ jobs:
             "$VERSION" \
             "$MIN_BLUEPRINT_VERSION"
 
+      - name: Update blueprint version and name
+        if: steps.skip_check.outputs.skip == 'false'
+        env:
+          NEW_VERSION: ${{ steps.next_version.outputs.version }}
+          MIN_UPSTREAM_VERSION: ${{ steps.min_upstream.outputs.version }}
+        run: |
+          BLUEPRINT="nspanel_easy_blueprint.yaml"
+
+          # sed is used intentionally here instead of yq — the blueprint contains
+          # a large icon table with unicode escape sequences (\uXXXX) that yq would
+          # silently convert to their literal UTF-8 characters, corrupting the file.
+
+          # Update the blueprint display name shown in the HA Blueprints dashboard.
+          sed -i \
+            "s/^  name: NSPanel Easy Configuration.*/  name: NSPanel Easy Configuration (v${NEW_VERSION})/" \
+            "$BLUEPRINT"
+          if ! grep -q "^  name: NSPanel Easy Configuration (v${NEW_VERSION})" "$BLUEPRINT"; then
+            echo "ERROR: Failed to update blueprint display name in $BLUEPRINT"
+            exit 1
+          fi
+
+          # Update the blueprint's own version number, used by ESPHome to verify
+          # compatibility against min_blueprint_version at runtime.
+          sed -i \
+            "s/^  blueprint_version: .*/  blueprint_version: ${NEW_VERSION}/" \
+            "$BLUEPRINT"
+          if ! grep -q "^  blueprint_version: ${NEW_VERSION}$" "$BLUEPRINT"; then
+            echo "ERROR: Failed to update blueprint_version in $BLUEPRINT"
+            exit 1
+          fi
+
+          # Update the minimum Home Assistant version required to run this blueprint,
+          # kept 2 months behind the release date to match the upstream contract.
+          sed -i \
+            "s/^    min_version: .*/    min_version: ${MIN_UPSTREAM_VERSION}/" \
+            "$BLUEPRINT"
+          if ! grep -q "^    min_version: ${MIN_UPSTREAM_VERSION}$" "$BLUEPRINT"; then
+            echo "ERROR: Failed to update min_version in $BLUEPRINT"
+            exit 1
+          fi
+
       - name: Restore YAML document end markers
         if: steps.skip_check.outputs.skip == 'false'
         run: |
-          # Re-append document end marker stripped by yq on version.yaml in-place edits.
-          for file in ./versioning/version.yaml; do
+          # yq strips the YAML document end marker (...) on in-place edits.
+          # Re-append it to all files modified by yq.
+          for file in ./versioning/version.yaml esphome/nspanel_esphome_version.yaml; do
             if [ -f "$file" ] && ! tail -1 "$file" | grep -qx '\.\.\.'; then
               echo '...' >> "$file"
             fi
@@ -204,7 +300,8 @@ jobs:
         env:
           NEW_VERSION: ${{ steps.next_version.outputs.version }}
         run: |
-          git add ./versioning/version.yaml .github/ISSUE_TEMPLATE/bug.yml
+          git add ./versioning/version.yaml .github/ISSUE_TEMPLATE/bug.yml \
+                  esphome/nspanel_esphome_version.yaml nspanel_easy_blueprint.yaml
           git commit -m "Bump version to ${NEW_VERSION} [skip-versioning]"
 
       - name: Push changes to main

docs/addon_climate.md

@@ -51,7 +51,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
@@ -127,7 +127,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
@@ -170,7 +170,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
@@ -216,7 +216,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package

docs/addon_cover.md

@@ -54,7 +54,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
@@ -80,7 +80,7 @@ The following keys are available in your `substitutions` section:
 
 <!-- markdownlint-disable MD013 MD033 -->
 | Key | Required | Supported values | Default | Description |
-|:-|:-:|:-:|:-:|:-|
+| :- | :-: | :-: | :-: | :- |
 | `cover_device_class` | Optional | Any of the [device classes supported by Home Assistant](https://www.home-assistant.io/integrations/cover/#device-class) | `""` (none) | Sets the cover type at compile time. Influences how the entity is represented in Home Assistant. |
 | `interlock_wait_time` | Optional | `1` to `5000` | `250` | Relay interlock delay in ms. Imposes a time delay from one relay turning off until the other can turn on, preventing both relays from being on simultaneously.<br>***ATTENTION***: this is a software interlock — see [ESPHome Switch Interlocking](https://esphome.io/components/switch/gpio.html#interlocking). |
 <!-- markdownlint-enable MD013 MD033 -->
@@ -92,7 +92,7 @@ The remaining settings are accessible via the device's page in Home Assistant
 
 <!-- markdownlint-disable MD013 MD033 -->
 | Entity | Supported values | Default | Description |
-|:-|:-:|:-:|:-|
+| :- | :-: | :-: | :- |
 | Cover relays mode | `Relay 1 opens, relay 2 closes` or `Relay 2 opens, relay 1 closes` | `Relay 1 opens, relay 2 closes` | Defines which relay opens the cover and which closes it. |
 | Cover open duration | `1ms` to `600000ms` | `1ms` (disabled) | The amount of time it takes the cover to open from the fully closed state. |
 | Cover close duration | `1ms` to `600000ms` | `1ms` (disabled) | The amount of time it takes the cover to close from the fully open state. |

docs/addon_display_light.md

@@ -12,7 +12,7 @@ your panel is on with the same automation you use for your lights.
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package

docs/addon_upload_tft.md

@@ -60,7 +60,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package (already includes this add-on)
@@ -79,7 +79,7 @@ add the Upload TFT package explicitly:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - esphome/nspanel_esphome_core.yaml
@@ -118,7 +118,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml
@@ -141,7 +141,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml
@@ -164,7 +164,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml

docs/customization.md

@@ -102,7 +102,7 @@ logger:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package

docs/install.md

@@ -132,7 +132,7 @@ Follow these steps to add a new device in the ESPHome Dashboard:
    packages:
      remote_package:
        url: https://github.com/edwardtfn/NSPanel-Easy
-       ref: main
+       ref: latest
        refresh: 300s
        files:
          - nspanel_esphome.yaml # Basic package
@@ -537,7 +537,7 @@ api:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - esphome/nspanel_esphome_core.yaml        # Core NSPanel functionality
@@ -592,7 +592,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - esphome/nspanel_esphome_core.yaml
@@ -639,7 +639,7 @@ api:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - esphome/nspanel_esphome_core.yaml

docs/migration_from_blackymas.md

@@ -91,7 +91,7 @@ Find your `remote_package` block. It currently looks something like this:
 packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
-    ref: v4.3.30  # or whatever version you were using
+    ref: main  # or whatever version you were using
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Base package
@@ -108,7 +108,7 @@ Change it to:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Base package
@@ -126,7 +126,7 @@ packages:
 | `ota_password` | It was set on the remote package to use your WiFi password | You have to add the substitution `ota_password: ${wifi_password}` for backward compatibility |
 | `language` | Selected via Blueprint dropdown | Set as `language: xx` substitution in ESPHome YAML - see [Localization](localization.md) |
 | `url` | `https://github.com/Blackymas/NSPanel_HA_Blueprint` | `https://github.com/edwardtfn/NSPanel-Easy` |
-| `ref` | A version tag (e.g. `v4.3.30`) | `main` |
+| `ref` | `main` (or a specific version) | `latest` |
 | Add-on file paths | Root level (e.g. `nspanel_esphome_addon_climate_heat.yaml`) | Inside `esphome/` folder (e.g. `esphome/nspanel_esphome_addon_climate_heat.yaml`) |
 | Base package | `nspanel_esphome.yaml` | `nspanel_esphome.yaml` *(no change)* |
 
@@ -162,7 +162,7 @@ substitutions:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/NSPanel-Easy
-    ref: main
+    ref: latest
     refresh: 300s
     files:
       - nspanel_esphome.yaml # Base package
@@ -330,7 +330,7 @@ and you'll now receive updates from the new repository.
 Double-check that:
 
 - The `url` is exactly `https://github.com/edwardtfn/NSPanel-Easy`
-- The `ref` is `main` (not a version tag from the old repository).
+- The `ref` is `latest` (not a version tag from the old repository).
   After this first migration install, you'll be able to use version tags
   in the same format (e.g. `ref: v5.0.0`) once NSPanel Easy publishes releases.
 - Add-on files use the `esphome/` prefix (e.g. `esphome/nspanel_esphome_addon_climate_heat.yaml`)