Added ImageMagick 7 Q16-HDRI for consistent dithering

Debian apt only provides ImageMagick 6 which produces different dithering
output than local dev environments running IM7. This caused visual
inconsistencies between development and production.

Changes:
- Multi-stage build copies IM7 from dpokidov/imagemagick
- Wrapper script filters deprecation warnings from gm package
- Documentation recommends docker-dev.sh for version parity

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ikraamg

CLAUDE.md

@@ -8,7 +8,7 @@ Home Assistant add-on for TRMNL e-ink displays. Captures HA dashboard screenshot
 
 **Runtime:** Bun 1.3.5+ (not Node.js)
 **Language:** TypeScript with strict type checking
-**Image Processing:** ImageMagick via `gm` package
+**Image Processing:** ImageMagick 7 Q16-HDRI via `gm` package
 
 ## Development Commands
 
@@ -121,11 +121,37 @@ Error hierarchy:
 
 ## Local Development Setup
 
+### Recommended: Docker Dev (ensures ImageMagick version parity)
+
+```bash
+cd trmnl-ha/ha-trmnl
+cp options-dev.json.example options-dev.json
+# Edit options-dev.json with your HA URL and token
+./scripts/docker-dev.sh
+```
+
+This runs the app inside Docker with hot-reload, using the **exact same ImageMagick 7 Q16-HDRI** version as production. This ensures dithering output is identical between dev and prod.
+
+### Alternative: Native Bun (requires local ImageMagick 7)
+
+If you prefer running outside Docker, you need ImageMagick 7 installed locally:
+
+```bash
+# macOS
+brew install imagemagick
+
+# Verify version (must be 7.x with Q16-HDRI)
+convert -version | head -1
+# Should show: Version: ImageMagick 7.x.x Q16-HDRI
+```
+
+Then:
 1. Copy `options-dev.json.example` to `options-dev.json`
 2. Add your HA URL and access token
 3. Run `bun run dev`
 
-For development without real Home Assistant:
+### Mock HA Server (for development without real HA)
+
 ```bash
 # Terminal 1: Mock HA server
 bun run mock:server
@@ -180,5 +206,5 @@ log.error`Failed: ${error.message}`
 
 - Base: `debian:bookworm-slim` (multi-stage build)
 - Chromium for headless browser
-- ImageMagick for image processing
+- ImageMagick 7 Q16-HDRI (copied from `dpokidov/imagemagick` for consistent dithering)
 - Health check: `GET /health` on port 10000

trmnl-ha/Dockerfile

@@ -4,7 +4,16 @@
 # Uses Debian Bookworm for updated packages and better security
 
 # =============================================================================
-# STAGE 1: DEPENDENCY BUILDER
+# STAGE 1: IMAGEMAGICK 7 SOURCE
+# =============================================================================
+# NOTE: Using dpokidov's IM7 image to ensure consistent dithering between
+# local dev (IM7) and Docker. Debian apt only provides IM6 which has different
+# algorithm implementations, colorspace handling, and HDRI support.
+# See: https://github.com/dooman87/imagemagick-docker
+FROM dpokidov/imagemagick:7.1.1-47-bookworm AS imagemagick
+
+# =============================================================================
+# STAGE 2: DEPENDENCY BUILDER
 # =============================================================================
 # NOTE: Using official Bun image which ships with baseline x64 builds for maximum
 # CPU compatibility (supports Synology DS918+, older Proxmox VMs, CPUs without AVX2)
@@ -25,14 +34,14 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
     bun install --frozen-lockfile --production
 
 # =============================================================================
-# STAGE 2: RUNTIME
+# STAGE 3: RUNTIME
 # =============================================================================
 FROM debian:bookworm-slim
 
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=Etc/UTC
 
-# Install only runtime dependencies
+# Install only runtime dependencies (ImageMagick copied from stage 1)
 # NOTE: Grouped by purpose for clarity and maintainability
 # NOTE: Using BuildKit cache mounts for apt to speed up rebuilds
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
@@ -46,8 +55,41 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     ca-certificates \
     # CJK font support for international dashboards
     fonts-noto-cjk \
-    # Image processing for dithering algorithms
-    imagemagick
+    # ImageMagick 7 runtime dependencies (binaries copied from stage 1)
+    libgomp1 \
+    libomp5 \
+    libjpeg62-turbo \
+    libpng16-16 \
+    libtiff6 \
+    libwebp7 \
+    libwebpmux3 \
+    libwebpdemux2 \
+    libheif1 \
+    libraw20 \
+    liblcms2-2 \
+    libfreetype6 \
+    libfontconfig1 \
+    libfftw3-double3 \
+    liblqr-1-0 \
+    libltdl7 \
+    libopenjp2-7 \
+    libxml2 \
+    libzip4
+
+# Copy ImageMagick 7 binaries and libraries from stage 1
+# NOTE: This gives us IM7 with Q16-HDRI for consistent dithering with local dev
+COPY --from=imagemagick /usr/local/bin/magick /usr/local/bin/
+COPY --from=imagemagick /usr/local/lib/ /usr/local/lib/
+COPY --from=imagemagick /usr/local/etc/ImageMagick-7/ /usr/local/etc/ImageMagick-7/
+
+# Set up ImageMagick 7 CLI compatibility
+# The gm package calls 'convert', but IM7 uses 'magick' and shows deprecation warnings
+# We use a wrapper script that filters out the warning while preserving functionality
+COPY ha-trmnl/scripts/imagemagick-wrapper.sh /usr/local/bin/convert
+RUN chmod +x /usr/local/bin/convert && \
+    ln -s /usr/local/bin/magick /usr/local/bin/identify && \
+    ln -s /usr/local/bin/magick /usr/local/bin/mogrify && \
+    ldconfig
 
 # Copy Bun runtime from builder stage
 # NOTE: /usr/local/bin is already in PATH, no additional ENV needed

trmnl-ha/ha-trmnl/scripts/imagemagick-wrapper.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# ImageMagick 7 wrapper script
+# Suppresses the "convert command is deprecated" warning from IM7
+# The gm npm package calls 'convert', but IM7 wants 'magick'
+#
+# This wrapper:
+# 1. Calls 'magick' with all arguments passed through
+# 2. Filters out only the deprecation warning from stderr
+# 3. Preserves stdout (for binary image data) and exit codes
+
+# Create a temp file for filtered stderr
+tmpfile=$(mktemp)
+trap 'rm -f "$tmpfile"' EXIT
+
+# Run magick, capture stderr to temp, let stdout pass through
+/usr/local/bin/magick "$@" 2>"$tmpfile"
+exit_code=$?
+
+# Output filtered stderr (remove deprecation warning)
+grep -v "The convert command is deprecated" "$tmpfile" >&2
+
+exit $exit_code