espresso_frame/server/app/html_render.py

"""Experimental "modern" weather widget render style: Jinja2 + a
persistent headless Chromium browser (Playwright) instead of the hand-
drawn PIL primitives in weather_render.py -- see docs/widgets.md and the
`html-widget-render` branch's PR description for the design rationale
(gradients/shadows/soft shading that PIL can't easily do, at the cost of
a real browser-process dependency).

Two things this module owns that nothing else in the codebase needed
before:

1. A **persistent** background browser process. Widget rendering already
   happens concurrently across a fresh `ThreadPoolExecutor` per frame
   request (routers/device.py's _render_widgets) -- Playwright's sync
   API is thread-affine (an object must be used from the thread that
   created it), so a single browser object can't be handed across those
   ad-hoc worker threads, and relaunching a full Chromium process on
   every widget render would be real, avoidable latency. Fix: one
   background thread runs its own persistent asyncio event loop hosting
   one long-lived `Browser`, lazily started on first use (see start()) --
   not eagerly at server startup, so a deployment that never enables the
   weather widget's "modern" style never launches Chromium at all and
   never needs Playwright's browser binaries installed. main.py's
   lifespan only wires up the *shutdown* half (stop()), so a clean
   server restart doesn't leave an orphaned Chromium process behind if
   this was ever actually used. render_html_to_image() is a plain sync
   function any worker thread can call, bridging in via
   `asyncio.run_coroutine_threadsafe` (the standard safe cross-thread
   entry point into a *running* loop on another thread).

2. **Per-region ordered (Bayer) dithering against the palette**, done
   here rather than in the shared image_pipeline.py pipeline.
   render_panel's whole-canvas single Floyd-Steinberg pass exists
   because Floyd-Steinberg's error diffusion can't be split across
   independently-quantized regions without a visible seam at the
   boundary -- but that reasoning doesn't apply to ordered dithering,
   which has no cross-pixel error term (each pixel's dither decision
   only depends on its own position + color). So this module dithers its
   own rendered widget to *already-exact* palette colors before
   returning it; the later shared Floyd-Steinberg pass sees zero
   quantization error there and leaves it untouched -- the same
   "pre-commit to exact palette colors" trick image_pipeline.draw_text
   and the hand-drawn weather icons already rely on, just reached a
   different way. Floyd-Steinberg keeps working exactly as before for
   photos and every other (classic-rendered) widget region.
"""

from __future__ import annotations

import asyncio
import io
import threading
from datetime import date
from pathlib import Path

import numpy as np
from jinja2 import Environment, FileSystemLoader, select_autoescape
from PIL import Image

from . import panel_style
from .image_pipeline import DEFAULT_PALETTE_RGB

_TEMPLATE_DIR = Path(__file__).resolve().parent / "templates" / "widget_html"
_FONT_DIR = Path(__file__).resolve().parent / "fonts"

_jinja_env = Environment(
    loader=FileSystemLoader(str(_TEMPLATE_DIR)),
    autoescape=select_autoescape(["html", "jinja"]),
)

CATEGORY_EMOJI = {
    "clear": "☀️",
    "partly_cloudy": "⛅",
    "cloudy": "☁️",
    "fog": "\U0001f32b️",
    "rain": "\U0001f327️",
    "snow": "❄️",
    "thunderstorm": "⛈️",
}

# ACCENT_START/END: a fixed blue gradient pair for the "modern" style's
# card header -- deliberately not routed through panel_style.theme_color
# (unlike every classic-rendered widget's chrome), since the whole point
# of this style is the gradient look ordered_dither below then commits
# to exact palette colors anyway; which literal hex this starts from
# doesn't matter to the end result the way it would for a flat PIL fill.
ACCENT_START = "#1c4fd6"
ACCENT_END = "#6fa8ff"


# --- Persistent background browser -------------------------------------

_loop: asyncio.AbstractEventLoop | None = None
_loop_thread: threading.Thread | None = None
_browser = None
_playwright_cm = None
_start_lock = threading.Lock()


async def _launch_browser() -> None:
    global _browser, _playwright_cm
    from playwright.async_api import async_playwright

    _playwright_cm = async_playwright()
    playwright = await _playwright_cm.__aenter__()
    _browser = await playwright.chromium.launch()


async def _close_browser() -> None:
    global _browser, _playwright_cm
    if _browser is not None:
        await _browser.close()
        _browser = None
    if _playwright_cm is not None:
        await _playwright_cm.__aexit__(None, None, None)
        _playwright_cm = None


def start() -> None:
    """Launches the background event loop + persistent Chromium browser,
    if not already running. Called lazily by render_html_to_image on
    first use (not from main.py's lifespan -- see module docstring for
    why this must stay opt-in) -- exposed directly too, for tests that
    want to control startup explicitly. Idempotent -- a second call
    while already started is a no-op."""
    global _loop, _loop_thread
    if _loop is not None:
        return
    ready = threading.Event()

    def _run() -> None:
        global _loop
        loop = asyncio.new_event_loop()
        asyncio.set_event_loop(loop)
        _loop = loop
        ready.set()
        loop.run_forever()

    _loop_thread = threading.Thread(target=_run, daemon=True, name="html-render-loop")
    _loop_thread.start()
    ready.wait()
    asyncio.run_coroutine_threadsafe(_launch_browser(), _loop).result()


def stop() -> None:
    """Closes the browser and stops the background loop -- called from
    main.py's lifespan shutdown so a server restart never leaves an
    orphaned Chromium process behind. No-op if start() was never called
    (the common case: most deployments never enable "modern" style)."""
    global _loop, _loop_thread
    if _loop is None:
        return
    asyncio.run_coroutine_threadsafe(_close_browser(), _loop).result()
    _loop.call_soon_threadsafe(_loop.stop)
    _loop_thread.join(timeout=5)
    _loop = None
    _loop_thread = None


async def _screenshot(html: str, target_w: int, target_h: int) -> bytes:
    page = await _browser.new_page(viewport={"width": target_w, "height": target_h}, device_scale_factor=1)
    try:
        await page.set_content(html, wait_until="networkidle")
        return await page.screenshot()
    finally:
        await page.close()


def render_html_to_image(html: str, target_w: int, target_h: int) -> Image.Image:
    """Renders `html` (already sized to target_w x target_h via its own
    <style>) through the persistent headless Chromium browser and
    returns an RGB image of exactly that size. Safe to call from any
    thread -- bridges into the dedicated background asyncio loop via
    run_coroutine_threadsafe. Lazily calls start() on first use (see its
    docstring) -- the first "modern" style render on a freshly-started
    server pays Chromium's launch latency; every render after that reuses
    the same persistent browser."""
    if _loop is None:
        with _start_lock:
            if _loop is None:
                start()
    future = asyncio.run_coroutine_threadsafe(_screenshot(html, target_w, target_h), _loop)
    png_bytes = future.result()
    return Image.open(io.BytesIO(png_bytes)).convert("RGB")


# --- Ordered (Bayer 8x8) dithering against an arbitrary palette ---------

_BAYER8 = (
    np.array(
        [
            [0, 32, 8, 40, 2, 34, 10, 42],
            [48, 16, 56, 24, 50, 18, 58, 26],
            [12, 44, 4, 36, 14, 46, 6, 38],
            [60, 28, 52, 20, 62, 30, 54, 22],
            [3, 35, 11, 43, 1, 33, 9, 41],
            [51, 19, 59, 27, 49, 17, 57, 25],
            [15, 47, 7, 39, 13, 45, 5, 37],
            [63, 31, 55, 23, 61, 29, 53, 21],
        ],
        dtype=np.float32,
    )
    / 64.0
    - 0.5
)


def ordered_dither(img: Image.Image, palette_rgb: list | None, amplitude: float = 48.0) -> Image.Image:
    """Bayer-ordered dither of `img` against `palette_rgb` (falls back to
    DEFAULT_PALETTE_RGB) -- every output pixel is one of the palette's
    exact colors, spatially patterned rather than error-diffused, so it's
    safe to run per-region before compositing (see module docstring for
    why that's not true of Floyd-Steinberg). `amplitude` is the Bayer
    bias's full swing in 0-255 RGB units before nearest-palette-color
    matching -- 48 was the value this render style was tuned against in
    the exploratory spike behind this feature; not exposed as a per-frame
    setting (unlike dither_strength) since there's only one consumer of
    it today."""
    palette = np.array(palette_rgb or DEFAULT_PALETTE_RGB, dtype=np.float32)
    arr = np.asarray(img.convert("RGB"), dtype=np.float32)
    h, w, _ = arr.shape
    tile = np.tile(_BAYER8, (h // 8 + 1, w // 8 + 1))[:h, :w]
    biased = np.clip(arr + tile[:, :, None] * amplitude, 0, 255)
    diffs = biased[:, :, None, :] - palette[None, None, :, :]
    dists = np.einsum("hwkc,hwkc->hwk", diffs, diffs)
    idx = np.argmin(dists, axis=2)
    return Image.fromarray(palette[idx].astype(np.uint8), "RGB")


# --- Weather "modern" style ----------------------------------------------

def _day_label(day_date: date) -> str:
    delta = (day_date - date.today()).days
    if delta == 0:
        return "Today"
    if delta == 1:
        return "Tomorrow"
    return day_date.strftime("%a")


def build_current(entry: dict | None, target_w: int, target_h: int, palette_rgb: list | None = None,
                  units: str = "fahrenheit", city_label: str = "") -> Image.Image:
    """HTML/CSS-rendered analogue of weather_render.build_current --
    same call signature, so app/widgets/weather.py can dispatch to
    either interchangeably. Returns an already-palette-exact RGB image
    (see ordered_dither)."""
    img = Image.new("RGB", (target_w, target_h), (255, 255, 255))
    if not entry:
        return img

    unit_suffix = "F" if units == "fahrenheit" else "C"
    icon_size = max(28, min(target_w, target_h) // 3)
    template = _jinja_env.get_template("weather_current.html.jinja")
    html = template.render(
        w=target_w, h=target_h, gutter=panel_style.GUTTER, radius=panel_style.CARD_RADIUS,
        font_dir=str(_FONT_DIR), emoji=CATEGORY_EMOJI.get(entry["category"], ""),
        temp=round(entry["temp"]), unit_suffix=unit_suffix, city_label=city_label,
        icon_size=icon_size, temp_size=max(24, min(target_w, target_h) // 3),
        label_size=max(12, icon_size // 3),
    )
    rendered = render_html_to_image(html, target_w, target_h)
    return ordered_dither(rendered, palette_rgb)


def build_daily(daily: dict[str, dict], target_w: int, target_h: int, palette_rgb: list | None = None,
               units: str = "fahrenheit", city_label: str = "") -> Image.Image:
    """HTML/CSS-rendered analogue of weather_render.build_daily -- same
    call signature. Returns an already-palette-exact RGB image (see
    ordered_dither)."""
    img = Image.new("RGB", (target_w, target_h), (255, 255, 255))
    days = list(daily.items())
    if not days:
        return img

    unit_suffix = "F" if units == "fahrenheit" else "C"
    header_h = max(28, min(target_w, target_h) // 8) if city_label else 0
    col_w = max(1, target_w // len(days))
    icon_size = max(16, min(col_w // 2, 36))
    day_entries = [
        {
            "label": _day_label(date.fromisoformat(day_str)),
            "emoji": CATEGORY_EMOJI.get(d["category"], ""),
            "high": round(d["high"]),
            "low": round(d["low"]),
        }
        for day_str, d in days
    ]
    template = _jinja_env.get_template("weather_daily.html.jinja")
    html = template.render(
        w=target_w, h=target_h, gutter=panel_style.GUTTER, radius=panel_style.CARD_RADIUS,
        font_dir=str(_FONT_DIR), city_label=city_label, header_h=header_h,
        title_size=max(14, header_h - 12), accent_start=ACCENT_START, accent_end=ACCENT_END,
        days=day_entries, icon_size=icon_size, label_size=max(12, icon_size // 2),
        unit_suffix=unit_suffix,
    )
    rendered = render_html_to_image(html, target_w, target_h)
    return ordered_dither(rendered, palette_rgb)


SUPPORTED_MODES = ("current", "daily")


def build(mode: str, data, target_w: int, target_h: int, palette_rgb: list | None = None,
         units: str = "fahrenheit", city_label: str = "") -> Image.Image:
    """Dispatches to build_current/build_daily -- mirrors weather_render.
    build()'s signature (minus interval_hours, which no modern-style mode
    uses) so app/widgets/weather.py and the weather preview endpoint can
    call either module identically. Only call this for mode in
    SUPPORTED_MODES -- callers are expected to have already fallen back to
    weather_render.build() for hourly/multi_city (see weather.py)."""
    if mode == "current":
        return build_current(data, target_w, target_h, palette_rgb, units, city_label)
    return build_daily(data, target_w, target_h, palette_rgb, units, city_label)


def render_weather_preview_png(mode: str, data, orientation: str, palette_rgb: list | None,
                               units: str = "fahrenheit", city_label: str = "") -> bytes:
    """Modern-style analogue of weather_render.render_weather_preview_png
    -- same browser-viewable-PNG convention every other widget's preview
    endpoint uses. build()'s output is already palette-exact (see
    ordered_dither), so the final _quantize pass here is a no-op on it,
    same reasoning as the module docstring's compositing story."""
    from .image_pipeline import _quantize, _png_bytes, logical_render_size

    target_w, target_h = logical_render_size(orientation)
    img = build(mode, data, target_w, target_h, palette_rgb, units, city_label)
    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
    return _png_bytes(quantized)