server.py

from collections import Counter, defaultdict, deque
from concurrent.futures import ThreadPoolExecutor
from copy import deepcopy
from datetime import datetime, timedelta, timezone
from threading import RLock
from time import monotonic
from uuid import uuid4
import os
import unicodedata
from urllib.parse import urlsplit

import pycountry
from flask import Flask, g, jsonify, render_template, request, send_from_directory, url_for
from waitress import create_server

from browser_launcher import start_browser_launcher
from infrastructure import create_redis_cache, initialize_sentry
from planner import (
    ACTIVITY_PROFILES,
    DEFAULT_PLANNER_PREFERENCES,
    activity_guidance,
    best_outdoor_window,
    heat_stress_view,
    validate_activity,
    validate_planner_preferences,
)
from push_service import (
    DEFAULT_ALERT_RULES,
    get_alert_rules,
    push_configuration,
    save_alert_rules,
    save_subscription,
    validate_alert_rules,
)

from weather import (
    DEFAULT_CITY,
    WeatherConfigurationError,
    WeatherNotFoundError,
    WeatherServiceError,
    get_air_pollution,
    get_current_weather,
    get_environmental_forecast,
    get_one_call_weather,
    get_recent_history,
    get_singapore_psi,
    get_singapore_two_hour_forecast,
    get_singapore_uv,
    get_weather_forecast,
    search_locations,
)

app = Flask(__name__)
app.config["MAX_CONTENT_LENGTH"] = 64 * 1024
SENTRY_ACTIVE = initialize_sentry()

SINGAPORE_UTC_OFFSET = 8 * 60 * 60
CURRENT_WEATHER_TTL = 5 * 60
FORECAST_TTL = 10 * 60
AIR_QUALITY_TTL = 10 * 60
GEOCODING_TTL = 6 * 60 * 60
HISTORY_TTL = 6 * 60 * 60
ONE_CALL_TTL = 10 * 60
ENVIRONMENT_TTL = 30 * 60
SINGAPORE_OFFICIAL_TTL = 15 * 60


def _environment_flag(name, default=False):
    value = os.getenv(name)
    if value is None:
        return default
    return value.strip().casefold() in {"1", "true", "yes", "on"}


ONE_CALL_ENABLED = _environment_flag("OPENWEATHER_ONE_CALL_ENABLED")


class TTLCache:
    """Small thread-safe in-memory cache for upstream weather responses."""

    def __init__(self, maximum_entries=512):
        self.maximum_entries = maximum_entries
        self._entries = {}
        self._lock = RLock()

    def clear(self):
        with self._lock:
            self._entries.clear()

    def get(self, key):
        now = monotonic()
        with self._lock:
            entry = self._entries.get(key)
            if not entry:
                return None
            expires_at, value = entry
            if expires_at <= now:
                self._entries.pop(key, None)
                return None
            return deepcopy(value)

    def set(self, key, value, ttl_seconds):
        now = monotonic()
        with self._lock:
            if len(self._entries) >= self.maximum_entries:
                expired = [
                    cache_key
                    for cache_key, (expires_at, _) in self._entries.items()
                    if expires_at <= now
                ]
                for cache_key in expired:
                    self._entries.pop(cache_key, None)
                while len(self._entries) >= self.maximum_entries:
                    self._entries.pop(next(iter(self._entries)))
            self._entries[key] = (now + ttl_seconds, deepcopy(value))


API_CACHE = create_redis_cache() or TTLCache()
CACHE_BACKEND = getattr(API_CACHE, "backend_name", "memory")
RATE_BUCKETS = defaultdict(deque)
RATE_LOCK = RLock()
REQUEST_METRICS = Counter()
REQUEST_METRICS_LOCK = RLock()
APP_STARTED_AT = monotonic()
REQUEST_LOGGING_ENABLED = _environment_flag("REQUEST_LOGGING_ENABLED")
RATE_LIMITS = {
    "get_location_suggestions": (90, 60),
    "get_location_time": (20, 60),
    "get_weather_summary": (60, 60),
    "get_weather": (40, 60),
    "get_push_configuration": (60, 60),
    "subscribe_to_push": (10, 60),
    "manage_push_alert_rules": (20, 60),
    "get_planner_configuration": (60, 60),
    "calculate_personal_planner": (30, 60),
    "download_weather_calendar": (20, 60),
}


def _cached_value(key, ttl_seconds, loader):
    if app.testing:
        return loader()
    cached = API_CACHE.get(key)
    if cached is not None:
        return cached
    value = loader()
    API_CACHE.set(key, value, ttl_seconds)
    return deepcopy(value)


def _coordinate_key(latitude, longitude):
    return round(float(latitude), 5), round(float(longitude), 5)


def _cached_current_weather(
    city=DEFAULT_CITY,
    *,
    latitude=None,
    longitude=None,
    units="metric",
):
    if latitude is not None and longitude is not None:
        coordinates = _coordinate_key(latitude, longitude)
        key = ("current", *coordinates, units)
        return _cached_value(
            key,
            CURRENT_WEATHER_TTL,
            lambda: get_current_weather(
                latitude=latitude,
                longitude=longitude,
                units=units,
            ),
        )
    normalized_city = (city or DEFAULT_CITY).strip().casefold()
    return _cached_value(
        ("current-city", normalized_city, units),
        CURRENT_WEATHER_TTL,
        lambda: get_current_weather(city, units=units),
    )


def _cached_forecast(latitude, longitude, units):
    coordinates = _coordinate_key(latitude, longitude)
    return _cached_value(
        ("forecast", *coordinates, units),
        FORECAST_TTL,
        lambda: get_weather_forecast(
            latitude,
            longitude,
            units=units,
        ),
    )


def _cached_air_quality(latitude, longitude):
    coordinates = _coordinate_key(latitude, longitude)
    return _cached_value(
        ("air-quality", *coordinates),
        AIR_QUALITY_TTL,
        lambda: get_air_pollution(latitude, longitude),
    )


def _cached_history(latitude, longitude, units):
    end_date = (datetime.now(timezone.utc) - timedelta(days=1)).date()
    start_date = end_date - timedelta(days=6)
    coordinates = _coordinate_key(latitude, longitude)
    return _cached_value(
        ("history", *coordinates, units, str(start_date), str(end_date)),
        HISTORY_TTL,
        lambda: get_recent_history(
            latitude,
            longitude,
            start_date,
            end_date,
            units=units,
        ),
    )


def _cached_one_call(latitude, longitude, units):
    coordinates = _coordinate_key(latitude, longitude)
    return _cached_value(
        ("one-call", *coordinates, units),
        ONE_CALL_TTL,
        lambda: get_one_call_weather(latitude, longitude, units=units),
    )


def _cached_environment(latitude, longitude):
    coordinates = _coordinate_key(latitude, longitude)
    return _cached_value(
        ("environment", *coordinates),
        ENVIRONMENT_TTL,
        lambda: get_environmental_forecast(latitude, longitude),
    )


def _cached_singapore_two_hour():
    return _cached_value(
        ("singapore", "two-hour"),
        SINGAPORE_OFFICIAL_TTL,
        get_singapore_two_hour_forecast,
    )


def _cached_singapore_psi():
    return _cached_value(
        ("singapore", "psi"),
        SINGAPORE_OFFICIAL_TTL,
        get_singapore_psi,
    )


def _cached_singapore_uv():
    return _cached_value(
        ("singapore", "uv"),
        SINGAPORE_OFFICIAL_TTL,
        get_singapore_uv,
    )


def _cached_location_search(
    query,
    *,
    country_code="",
    state_code="",
    limit=5,
):
    key = (
        "geocode",
        (query or "").strip().casefold(),
        country_code.upper(),
        state_code.upper(),
        int(limit),
    )
    return _cached_value(
        key,
        GEOCODING_TTL,
        lambda: search_locations(
            query,
            country_code=country_code,
            state_code=state_code,
            limit=limit,
        ),
    )


@app.before_request
def begin_request_monitoring():
    g.request_started_at = monotonic()
    incoming_request_id = request.headers.get("X-Request-ID", "").strip()
    g.request_id = (
        incoming_request_id[:80]
        if incoming_request_id and all(character.isalnum() or character in "-_." for character in incoming_request_id)
        else uuid4().hex
    )


@app.after_request
def finish_request_monitoring(response):
    duration_ms = max(
        0.0,
        (monotonic() - getattr(g, "request_started_at", monotonic())) * 1000,
    )
    status_group = f"{response.status_code // 100}xx"
    with REQUEST_METRICS_LOCK:
        REQUEST_METRICS["requests"] += 1
        REQUEST_METRICS[status_group] += 1
    response.headers["X-Request-ID"] = getattr(g, "request_id", uuid4().hex)
    response.headers["Server-Timing"] = f"app;dur={duration_ms:.1f}"
    response.headers["Content-Security-Policy"] = "; ".join(
        (
            "default-src 'self'",
            "base-uri 'self'",
            "object-src 'none'",
            "frame-ancestors 'none'",
            "form-action 'self'",
            "script-src 'self' https://unpkg.com",
            "script-src-attr 'none'",
            "style-src-elem 'self' https://unpkg.com",
            "style-src-attr 'unsafe-inline'",
            "img-src 'self' data: blob: https://unpkg.com https://*.openstreetmap.org https://*.rainviewer.com https://tilecache.rainviewer.com",
            "connect-src 'self' https://api.rainviewer.com https://*.ingest.sentry.io",
            "font-src 'self'",
            "manifest-src 'self'",
            "worker-src 'self'",
            "upgrade-insecure-requests",
        )
    )
    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
    response.headers["X-Content-Type-Options"] = "nosniff"
    response.headers["X-Frame-Options"] = "DENY"
    response.headers["Permissions-Policy"] = (
        "camera=(), microphone=(), payment=(), usb=(), "
        "geolocation=(self), fullscreen=(self)"
    )
    if REQUEST_LOGGING_ENABLED and not app.testing:
        app.logger.info(
            "%s %s %s %.1fms request_id=%s",
            request.method,
            request.path,
            response.status_code,
            duration_ms,
            response.headers["X-Request-ID"],
        )
    return response


@app.before_request
def enforce_rate_limit():
    if app.testing or request.method == "OPTIONS":
        return None
    rule = RATE_LIMITS.get(request.endpoint)
    if not rule:
        return None

    maximum_requests, window_seconds = rule
    client = request.remote_addr or "unknown"
    shared_limiter = getattr(API_CACHE, "check_rate_limit", None)
    if shared_limiter:
        shared_result = shared_limiter(
            request.endpoint,
            client,
            maximum_requests,
            window_seconds,
        )
        if shared_result is not None:
            allowed, retry_after = shared_result
            if allowed:
                return None
            response = jsonify(
                {
                    "error": "Too many requests. Please wait a moment and try again."
                }
            )
            response.status_code = 429
            response.headers["Retry-After"] = str(retry_after)
            response.headers["Cache-Control"] = "no-store"
            return response

    key = (request.endpoint, client)
    now = monotonic()
    with RATE_LOCK:
        bucket = RATE_BUCKETS[key]
        while bucket and bucket[0] <= now - window_seconds:
            bucket.popleft()
        if len(bucket) >= maximum_requests:
            retry_after = max(1, int(window_seconds - (now - bucket[0])))
            response = jsonify(
                {
                    "error": "Too many requests. Please wait a moment and try again."
                }
            )
            response.status_code = 429
            response.headers["Retry-After"] = str(retry_after)
            response.headers["Cache-Control"] = "no-store"
            return response
        bucket.append(now)
    return None


@app.context_processor
def inject_location_catalog():
    return {
        "country_catalog": COUNTRY_CATALOG,
        "catalog_subdivisions": (),
    }


def _country_display_name(country):
    return getattr(country, "common_name", country.name)


def _alphabetical_key(value):
    normalized = unicodedata.normalize("NFKD", str(value))
    return "".join(
        character
        for character in normalized
        if not unicodedata.combining(character)
    ).casefold()


COUNTRY_CATALOG = tuple(
    sorted(
        (
            {"code": country.alpha_2, "name": _country_display_name(country)}
            for country in pycountry.countries
        ),
        key=lambda country: _alphabetical_key(country["name"]),
    )
)
COUNTRIES_BY_CODE = {country["code"]: country for country in COUNTRY_CATALOG}
SUBDIVISION_CATALOG = tuple(
    sorted(
        (
            {
                "code": subdivision.code,
                "country_code": subdivision.country_code,
                "name": subdivision.name,
                "type": getattr(subdivision, "type", "Subdivision"),
            }
            for subdivision in pycountry.subdivisions
        ),
        key=lambda subdivision: (
            subdivision["country_code"],
            _alphabetical_key(subdivision["name"]),
        ),
    )
)
SUBDIVISIONS_BY_CODE = {
    subdivision["code"]: subdivision for subdivision in SUBDIVISION_CATALOG
}
SUBDIVISIONS_BY_COUNTRY = {
    country["code"]: tuple(
        subdivision
        for subdivision in SUBDIVISION_CATALOG
        if subdivision["country_code"] == country["code"]
    )
    for country in COUNTRY_CATALOG
}

CONDITION_SYMBOLS = {
    "clear-day": "☀️",
    "clear-night": "🌙",
    "clouds-day": "⛅",
    "clouds-night": "☁️",
    "rain": "🌧️",
    "storm": "⛈️",
    "snow": "🌨️",
    "atmosphere": "🌫️",
}


def _number(value, default=0.0):
    try:
        return float(value)
    except (TypeError, ValueError):
        return default


def _local_datetime(timestamp, utc_offset):
    try:
        location_timezone = timezone(timedelta(seconds=int(utc_offset)))
        return datetime.fromtimestamp(int(timestamp), timezone.utc).astimezone(
            location_timezone
        )
    except (OverflowError, TypeError, ValueError):
        return None


def _normalise_utc_offset(value):
    try:
        offset = int(value)
    except (TypeError, ValueError):
        return 0

    # Current civil time zones range from UTC-12:00 through UTC+14:00.
    return offset if -12 * 60 * 60 <= offset <= 14 * 60 * 60 else 0


def _format_utc_offset(utc_offset):
    sign = "+" if utc_offset >= 0 else "−"
    hours, remainder = divmod(abs(utc_offset), 60 * 60)
    minutes = remainder // 60
    return f"UTC{sign}{hours:02d}:{minutes:02d}"


def _clock_snapshot(utc_offset, now_utc=None):
    utc_offset = _normalise_utc_offset(utc_offset)
    now_utc = now_utc or datetime.now(timezone.utc)
    local_time = now_utc.astimezone(timezone(timedelta(seconds=utc_offset)))
    day = local_time.strftime("%d").lstrip("0")

    return {
        "time": local_time.strftime("%H:%M:%S"),
        "date": f"{local_time.strftime('%A')}, {day} {local_time.strftime('%B %Y')}",
        "iso": local_time.isoformat(timespec="seconds"),
        "utc_offset": utc_offset,
        "utc_label": _format_utc_offset(utc_offset),
    }


def _describe_singapore_difference(location_utc_offset):
    difference_minutes = (
        _normalise_utc_offset(location_utc_offset) - SINGAPORE_UTC_OFFSET
    ) // 60
    if difference_minutes == 0:
        return "Same time as Singapore"

    hours, minutes = divmod(abs(difference_minutes), 60)
    parts = []
    if hours:
        parts.append(f"{hours} hr")
    if minutes:
        parts.append(f"{minutes} min")
    direction = "ahead of" if difference_minutes > 0 else "behind"
    return f"{' '.join(parts)} {direction} Singapore"


def _format_time(timestamp, utc_offset):
    local_time = _local_datetime(timestamp, utc_offset)
    return local_time.strftime("%H:%M") if local_time else "—"


def _format_observed_time(timestamp, utc_offset):
    local_time = _local_datetime(timestamp, utc_offset)
    if not local_time:
        return "Updated just now"

    day = local_time.strftime("%d").lstrip("0")
    return f"{local_time.strftime('%A')}, {day} {local_time.strftime('%B · %H:%M')}"


def _wind_direction(degrees):
    if degrees is None:
        return ""

    directions = ("N", "NE", "E", "SE", "S", "SW", "W", "NW")
    return directions[round(_number(degrees) / 45) % len(directions)]


def _condition_theme(condition, icon_code):
    condition = (condition or "").lower()
    is_night = str(icon_code).endswith("n")

    if condition == "clear":
        return "clear-night" if is_night else "clear-day"
    if condition == "clouds":
        return "clouds-night" if is_night else "clouds-day"
    if condition in {"rain", "drizzle"}:
        return "rain"
    if condition == "thunderstorm":
        return "storm"
    if condition == "snow":
        return "snow"
    return "atmosphere"


def _weather_view_model(weather_data, units):
    conditions = weather_data["weather"][0]
    main = weather_data.get("main", {})
    system = weather_data.get("sys", {})
    wind = weather_data.get("wind", {})
    coordinates = weather_data.get("coord", {})
    utc_offset = _normalise_utc_offset(weather_data.get("timezone", 0))
    theme = _condition_theme(conditions.get("main"), conditions.get("icon"))

    wind_speed = _number(wind.get("speed"))
    visibility = _number(weather_data.get("visibility"))
    if units == "metric":
        wind_speed *= 3.6
        wind_unit = "km/h"
        visibility_value = visibility / 1000
        visibility_unit = "km"
        temperature_unit = "C"
    else:
        wind_unit = "mph"
        visibility_value = visibility / 1609.344
        visibility_unit = "mi"
        temperature_unit = "F"

    city = weather_data.get("name") or "Current location"
    country = system.get("country", "")
    location = f"{city}, {country}" if country else city
    wind_cardinal = _wind_direction(wind.get("deg"))
    now_utc = datetime.now(timezone.utc)

    return {
        "city": city,
        "country": country,
        "location": location,
        "description": (conditions.get("description") or "Current conditions").capitalize(),
        "theme": theme,
        "symbol": CONDITION_SYMBOLS[theme],
        "temperature": round(_number(main.get("temp"))),
        "temperature_unit": temperature_unit,
        "feels_like": round(_number(main.get("feels_like"))),
        "minimum": round(_number(main.get("temp_min"))),
        "maximum": round(_number(main.get("temp_max"))),
        "humidity": round(_number(main.get("humidity"))),
        "pressure": round(_number(main.get("pressure"))),
        "wind_speed": round(wind_speed),
        "wind_unit": wind_unit,
        "wind_direction": wind_cardinal,
        "visibility": f"{visibility_value:.1f}",
        "visibility_unit": visibility_unit,
        "sunrise": _format_time(system.get("sunrise"), utc_offset),
        "sunset": _format_time(system.get("sunset"), utc_offset),
        "observed_at": _format_observed_time(weather_data.get("dt"), utc_offset),
        "location_clock": _clock_snapshot(utc_offset, now_utc),
        "singapore_clock": _clock_snapshot(SINGAPORE_UTC_OFFSET, now_utc),
        "singapore_difference": _describe_singapore_difference(utc_offset),
        "latitude": coordinates.get("lat"),
        "longitude": coordinates.get("lon"),
    }


def _forecast_item_view(item, utc_offset, units):
    conditions = item.get("weather") or [{}]
    condition = conditions[0] if isinstance(conditions[0], dict) else {}
    main = item.get("main", {})
    wind = item.get("wind", {})
    local_time = _local_datetime(item.get("dt"), utc_offset)
    wind_speed = _number(wind.get("speed"))
    if units == "metric":
        wind_speed *= 3.6
        wind_unit = "km/h"
    else:
        wind_unit = "mph"

    rain_volume = _number(item.get("rain", {}).get("3h"))
    snow_volume = _number(item.get("snow", {}).get("3h"))
    theme = _condition_theme(condition.get("main"), condition.get("icon"))
    return {
        "timestamp": int(_number(item.get("dt"))),
        "iso": local_time.isoformat(timespec="minutes") if local_time else "",
        "time": local_time.strftime("%H:%M") if local_time else "—",
        "date_key": local_time.strftime("%Y-%m-%d") if local_time else "",
        "weekday": local_time.strftime("%a") if local_time else "—",
        "temperature": round(_number(main.get("temp"))),
        "minimum": round(_number(main.get("temp_min"))),
        "maximum": round(_number(main.get("temp_max"))),
        "feels_like": round(_number(main.get("feels_like"))),
        "humidity": round(_number(main.get("humidity"))),
        "condition_id": int(_number(condition.get("id"))),
        "condition": condition.get("main", ""),
        "description": (condition.get("description") or "Forecast").capitalize(),
        "theme": theme,
        "precipitation_probability": round(_number(item.get("pop")) * 100),
        "precipitation_volume": round(rain_volume + snow_volume, 1),
        "rain_volume": rain_volume,
        "snow_volume": snow_volume,
        "wind_speed": round(wind_speed),
        "wind_unit": wind_unit,
        "wind_gust": _number(wind.get("gust")),
        "visibility": _number(item.get("visibility")),
    }


def _forecast_view_model(forecast_data, units):
    utc_offset = _normalise_utc_offset(
        forecast_data.get("city", {}).get("timezone", 0)
    )
    items = [
        _forecast_item_view(item, utc_offset, units)
        for item in forecast_data.get("list", [])
        if isinstance(item, dict) and item.get("dt")
    ]
    if not items:
        return None

    today = datetime.now(timezone.utc).astimezone(
        timezone(timedelta(seconds=utc_offset))
    ).date()
    grouped = {}
    for item in items:
        if not item["date_key"]:
            continue
        grouped.setdefault(item["date_key"], []).append(item)

    daily = []
    for date_key, day_items in list(grouped.items())[:5]:
        local_date = datetime.strptime(date_key, "%Y-%m-%d").date()
        day_difference = (local_date - today).days
        if day_difference == 0:
            day_label = "Today"
        elif day_difference == 1:
            day_label = "Tomorrow"
        else:
            day_label = local_date.strftime("%A")

        theme_counts = Counter(item["theme"] for item in day_items)
        representative = max(
            day_items,
            key=lambda item: (
                item["precipitation_probability"],
                theme_counts[item["theme"]],
                -abs(int(item["time"][:2]) - 12)
                if item["time"] != "—"
                else 0,
            ),
        )
        daily.append(
            {
                "date_key": date_key,
                "day": day_label,
                "date": local_date.strftime("%d %b").lstrip("0"),
                "minimum": min(item["minimum"] for item in day_items),
                "maximum": max(item["maximum"] for item in day_items),
                "precipitation_probability": max(
                    item["precipitation_probability"] for item in day_items
                ),
                "precipitation_volume": round(
                    sum(item["precipitation_volume"] for item in day_items), 1
                ),
                "humidity": round(
                    sum(item["humidity"] for item in day_items) / len(day_items)
                ),
                "theme": representative["theme"],
                "description": representative["description"],
            }
        )

    return {
        "hourly": items[:8],
        "daily": daily,
        "items": items,
        "interval_label": "3-hour intervals · free forecast",
        "is_true_hourly": False,
        "temperature_unit": "C" if units == "metric" else "F",
        "utc_offset": utc_offset,
    }


def _one_call_hourly_item(item, utc_offset, units):
    conditions = item.get("weather") or [{}]
    condition = conditions[0] if isinstance(conditions[0], dict) else {}
    local_time = _local_datetime(item.get("dt"), utc_offset)
    raw_wind_speed = _number(item.get("wind_speed"))
    display_wind_speed = (
        raw_wind_speed * 3.6 if units == "metric" else raw_wind_speed
    )
    rain_volume = _number(item.get("rain", {}).get("1h"))
    snow_volume = _number(item.get("snow", {}).get("1h"))
    temperature = round(_number(item.get("temp")))
    return {
        "timestamp": int(_number(item.get("dt"))),
        "iso": local_time.isoformat(timespec="minutes") if local_time else "",
        "time": local_time.strftime("%H:%M") if local_time else "—",
        "date_key": local_time.strftime("%Y-%m-%d") if local_time else "",
        "weekday": local_time.strftime("%a") if local_time else "—",
        "temperature": temperature,
        "minimum": temperature,
        "maximum": temperature,
        "feels_like": round(_number(item.get("feels_like"))),
        "humidity": round(_number(item.get("humidity"))),
        "condition_id": int(_number(condition.get("id"))),
        "condition": condition.get("main", ""),
        "description": (condition.get("description") or "Forecast").capitalize(),
        "theme": _condition_theme(condition.get("main"), condition.get("icon")),
        "precipitation_probability": round(_number(item.get("pop")) * 100),
        "precipitation_volume": round(rain_volume + snow_volume, 1),
        "rain_volume": rain_volume,
        "snow_volume": snow_volume,
        "wind_speed": round(display_wind_speed),
        "wind_unit": "km/h" if units == "metric" else "mph",
        "wind_gust": _number(item.get("wind_gust")),
        "visibility": _number(item.get("visibility")),
    }


def _enhance_forecast_with_one_call(forecast, one_call_data, units):
    utc_offset = _normalise_utc_offset(one_call_data.get("timezone_offset", 0))
    hourly = [
        _one_call_hourly_item(item, utc_offset, units)
        for item in one_call_data.get("hourly", [])[:24]
        if isinstance(item, dict) and item.get("dt")
    ]
    if not hourly:
        return forecast
    enhanced = forecast or {
        "daily": [],
        "temperature_unit": "C" if units == "metric" else "F",
    }
    enhanced["hourly"] = hourly
    enhanced["items"] = hourly
    enhanced["interval_label"] = "True hourly · One Call 3.0"
    enhanced["is_true_hourly"] = True
    enhanced["utc_offset"] = utc_offset
    return enhanced


def _build_five_hour_guidance(
    forecast,
    units,
    now_utc=None,
    *,
    preferences=None,
    activity="general",
    environment=None,
    observed_timestamp=None,
):
    """Turn the available next-five-hour forecast into practical advice."""
    if not forecast:
        return None

    preferences = validate_planner_preferences(preferences)
    activity = validate_activity(activity)

    source_items = (
        forecast.get("hourly", [])
        if forecast.get("is_true_hourly")
        else forecast.get("items", [])
    )
    items = sorted(
        (
            item
            for item in source_items
            if isinstance(item, dict) and item.get("timestamp")
        ),
        key=lambda item: item["timestamp"],
    )
    if not items:
        return None

    now_utc = now_utc or datetime.now(timezone.utc)
    if now_utc.tzinfo is None:
        now_utc = now_utc.replace(tzinfo=timezone.utc)
    else:
        now_utc = now_utc.astimezone(timezone.utc)
    now_timestamp = int(now_utc.timestamp())
    window_end_timestamp = now_timestamp + 5 * 60 * 60
    current_hour_tolerance = 60 * 60 if forecast.get("is_true_hourly") else 15 * 60
    window_items = [
        item
        for item in items
        if now_timestamp - current_hour_tolerance
        <= item["timestamp"]
        <= window_end_timestamp
    ]
    if not window_items:
        return None

    precipitation_probability = max(
        item.get("precipitation_probability", 0) for item in window_items
    )
    condition_ids = [item.get("condition_id", 0) for item in window_items]
    has_thunderstorm = any(200 <= condition_id < 300 for condition_id in condition_ids)
    has_snow = any(
        600 <= item.get("condition_id", 0) < 700
        or item.get("snow_volume", 0) > 0
        or item.get("theme") == "snow"
        for item in window_items
    )
    has_rain = any(
        300 <= item.get("condition_id", 0) < 600
        or item.get("rain_volume", 0) > 0
        or item.get("theme") in {"rain", "storm"}
        for item in window_items
    )
    wet_risk = has_rain or (
        precipitation_probability >= preferences["rain_threshold"] and not has_snow
    )
    freezing_rain = 511 in condition_ids

    feels_like_values = [
        _temperature_as_celsius(item.get("feels_like"), units)
        for item in window_items
    ]
    minimum_feels_c = min(feels_like_values)
    maximum_feels_c = max(feels_like_values)
    minimum_feels_display = min(
        round(_number(item.get("feels_like"))) for item in window_items
    )
    maximum_feels_display = max(
        round(_number(item.get("feels_like"))) for item in window_items
    )

    wind_speeds_display = [
        _number(item.get("wind_speed")) for item in window_items
    ]
    gusts_display = [
        (
            _number(item.get("wind_gust")) * 3.6
            if units == "metric"
            else _number(item.get("wind_gust"))
        )
        for item in window_items
    ]
    maximum_wind_display = round(max(wind_speeds_display + gusts_display))
    maximum_wind_kmh = (
        maximum_wind_display * 1.609344
        if units == "imperial"
        else maximum_wind_display
    )
    visibility_values = [
        _number(item.get("visibility"))
        for item in window_items
        if _number(item.get("visibility")) > 0
    ]
    minimum_visibility = min(visibility_values) if visibility_values else None

    precipitation_items = [
        item
        for item in window_items
        if item.get("precipitation_probability", 0) >= preferences["rain_threshold"]
        or item.get("rain_volume", 0) > 0
        or item.get("snow_volume", 0) > 0
        or item.get("theme") in {"rain", "storm", "snow"}
    ]
    precipitation_time = (
        precipitation_items[0].get("time", "soon")
        if precipitation_items
        else ""
    )

    recommendations = []
    recommendation_ids = set()

    def add(identifier, symbol, title, message, tone):
        if identifier in recommendation_ids:
            return
        recommendation_ids.add(identifier)
        recommendations.append(
            {
                "id": identifier,
                "symbol": symbol,
                "title": title,
                "message": message,
                "tone": tone,
            }
        )

    if has_thunderstorm:
        add(
            "storm-shelter",
            "⚡",
            "Plan for indoor shelter",
            "If thunder starts, go indoors promptly—an umbrella is not lightning protection.",
            "danger",
        )

    if has_snow:
        add(
            "snow-layers",
            "❄",
            "Wear thick, waterproof layers",
            f"Snow is forecast around {precipitation_time}. Wear an insulated coat, warm layers, gloves, and waterproof shoes.",
            "snow",
        )
    elif wet_risk:
        if maximum_wind_kmh >= preferences["wind_threshold_kmh"]:
            add(
                "windy-rain",
                "≋",
                "Choose a hooded raincoat",
                f"Rain is possible around {precipitation_time}, while wind may reach {maximum_wind_display} {'km/h' if units == 'metric' else 'mph'}. A raincoat will be easier to manage than a loose umbrella.",
                "rain",
            )
        else:
            umbrella_title = (
                "Bring an umbrella"
                if has_rain
                or precipitation_probability
                >= max(60, preferences["rain_threshold"])
                else "Pack a compact umbrella"
            )
            add(
                "umbrella",
                "☂",
                umbrella_title,
                f"Precipitation is possible around {precipitation_time}, with probability reaching {precipitation_probability}% in this window.",
                "rain",
            )
    else:
        add(
            "no-umbrella",
            "✓",
            "No umbrella is likely needed",
            f"Precipitation probability stays at or below {precipitation_probability}% across the available five-hour forecast.",
            "clear",
        )

    if freezing_rain:
        add(
            "ice",
            "◆",
            "Watch for slippery surfaces",
            "Freezing rain can create ice quickly. Wear shoes with good grip and allow extra travel time.",
            "danger",
        )
    elif minimum_feels_c <= 0:
        add(
            "very-cold",
            "▰",
            "Wear heavy winter layers",
            f"It may feel as cold as {minimum_feels_display}°{'C' if units == 'metric' else 'F'}. Add thermal layers, an insulated coat, a hat, and gloves.",
            "cold",
        )
    elif minimum_feels_c <= preferences["cold_threshold_c"] - 7:
        add(
            "cold",
            "▰",
            "Wear a thick coat",
            f"The feels-like temperature may fall to {minimum_feels_display}°{'C' if units == 'metric' else 'F'}. Wear a warm coat with layers underneath.",
            "cold",
        )
    elif minimum_feels_c <= preferences["cold_threshold_c"]:
        add(
            "cool",
            "▱",
            "Bring a jacket or sweater",
            f"It may feel as cool as {minimum_feels_display}°{'C' if units == 'metric' else 'F'}, especially if you stay outside for a while.",
            "cold",
        )
    elif maximum_feels_c >= preferences["heat_threshold_c"]:
        add(
            "heat",
            "☀",
            "Dress lightly and carry water",
            f"It may feel as hot as {maximum_feels_display}°{'C' if units == 'metric' else 'F'}. Choose breathable clothing and stay hydrated.",
            "heat",
        )

    if maximum_wind_kmh >= preferences["wind_threshold_kmh"] and not wet_risk:
        add(
            "wind",
            "≋",
            "Use a wind-resistant outer layer",
            f"Wind may reach {maximum_wind_display} {'km/h' if units == 'metric' else 'mph'}. Secure loose items and take care in exposed places.",
            "wind",
        )
    if minimum_visibility is not None and minimum_visibility < 1000:
        add(
            "visibility",
            "◌",
            "Allow extra travel time",
            "Visibility may become very low. Slow down and leave more stopping distance when travelling.",
            "caution",
        )

    uv_index = _number(environment.get("uv_index")) if environment else 0
    us_aqi = _number(environment.get("us_aqi")) if environment else 0
    if uv_index >= preferences["uv_threshold"]:
        add(
            "uv",
            "☀",
            "Use sun protection",
            f"UV is around {uv_index:.1f}. Use sunscreen, shade, and protective clothing.",
            "heat",
        )
    if us_aqi >= preferences["aqi_threshold"]:
        add(
            "air-quality",
            "◌",
            "Reduce prolonged exertion",
            f"Modelled U.S. AQI is around {round(us_aqi)}. Sensitive people should reduce strenuous outdoor activity.",
            "caution",
        )

    if has_thunderstorm:
        tone = "danger"
        symbol = "⚡"
        decision = "Storm shelter matters more than an umbrella"
        summary = (
            "Thunderstorms are possible during the next five hours. Carry rain protection, "
            "but move indoors when thunder is heard."
        )
    elif has_snow:
        tone = "snow"
        symbol = "❄"
        decision = "Dress warmly for snow"
        summary = (
            "Snow is possible in this five-hour window. Wear warm, waterproof layers "
            "and watch for slippery ground."
        )
    elif wet_risk and maximum_wind_kmh >= preferences["wind_threshold_kmh"]:
        tone = "rain"
        symbol = "≋"
        decision = "Take rain protection"
        summary = (
            "Rain is possible, but stronger wind may make an umbrella awkward. "
            "A hooded waterproof jacket is the safer choice."
        )
    elif wet_risk:
        tone = "rain"
        symbol = "☂"
        decision = (
            "Yes—bring an umbrella"
            if has_rain
            or precipitation_probability >= max(60, preferences["rain_threshold"])
            else "A compact umbrella is sensible"
        )
        summary = (
            f"Precipitation probability reaches {precipitation_probability}% "
            "during the next five hours."
        )
    elif maximum_feels_c >= preferences["heat_threshold_c"]:
        tone = "heat"
        symbol = "☀"
        decision = "No umbrella—prepare for heat"
        summary = "Dry conditions are expected, but heat may be uncomfortable outdoors."
    elif minimum_feels_c <= preferences["cold_threshold_c"]:
        tone = "cold"
        symbol = "▰"
        decision = "No umbrella—bring a warm layer"
        summary = "Rain is unlikely, but the feels-like temperature may be cool or cold."
    else:
        tone = "clear"
        symbol = "✓"
        decision = "No umbrella is likely needed"
        summary = "No meaningful rain or snow signal appears in the available five-hour forecast."

    utc_offset = _normalise_utc_offset(forecast.get("utc_offset", 0))
    location_timezone = timezone(timedelta(seconds=utc_offset))
    window_end_local = (now_utc + timedelta(hours=5)).astimezone(
        location_timezone
    )
    point_label = (
        "hourly forecast"
        if forecast.get("is_true_hourly")
        else "3-hour forecast checkpoint"
    )
    if len(window_items) != 1:
        point_label += "s"
    observed_period = (
        window_items[0].get("time", "—")
        if len(window_items) == 1
        else f"{window_items[0].get('time', '—')}–{window_items[-1].get('time', '—')}"
    )

    confidence_score = 92 if forecast.get("is_true_hourly") else 72
    if len(window_items) == 1:
        confidence_score -= 12
    confidence_score = max(40, confidence_score)
    why = [
        {
            "id": "precipitation",
            "label": "Precipitation rule",
            "value": f"{precipitation_probability}%",
            "threshold": f"{preferences['rain_threshold']}%",
            "triggered": wet_risk or has_snow,
        },
        {
            "id": "temperature",
            "label": "Comfort rule",
            "value": f"{minimum_feels_display}°–{maximum_feels_display}°{'C' if units == 'metric' else 'F'}",
            "threshold": (
                f"{preferences['cold_threshold_c']}°C / "
                f"{preferences['heat_threshold_c']}°C"
            ),
            "triggered": (
                minimum_feels_c <= preferences["cold_threshold_c"]
                or maximum_feels_c >= preferences["heat_threshold_c"]
            ),
        },
        {
            "id": "wind",
            "label": "Wind rule",
            "value": f"{maximum_wind_display} {'km/h' if units == 'metric' else 'mph'}",
            "threshold": f"{preferences['wind_threshold_kmh']} km/h",
            "triggered": maximum_wind_kmh >= preferences["wind_threshold_kmh"],
        },
    ]
    if environment:
        why.extend(
            [
                {
                    "id": "uv",
                    "label": "UV rule",
                    "value": f"{uv_index:.1f}",
                    "threshold": str(preferences["uv_threshold"]),
                    "triggered": uv_index >= preferences["uv_threshold"],
                },
                {
                    "id": "aqi",
                    "label": "Air-quality rule",
                    "value": str(round(us_aqi)),
                    "threshold": str(preferences["aqi_threshold"]),
                    "triggered": us_aqi >= preferences["aqi_threshold"],
                },
            ]
        )

    return {
        "tone": tone,
        "symbol": symbol,
        "decision": decision,
        "summary": summary,
        "period": f"Now–{window_end_local.strftime('%H:%M')}",
        "coverage": f"Based on {len(window_items)} {point_label} ({observed_period})",
        "recommendations": recommendations[:4],
        "precipitation_probability": precipitation_probability,
        "minimum_feels_like": minimum_feels_display,
        "maximum_wind_speed": maximum_wind_display,
        "temperature_unit": "C" if units == "metric" else "F",
        "wind_unit": "km/h" if units == "metric" else "mph",
        "is_true_hourly": bool(forecast.get("is_true_hourly")),
        "activity": activity,
        "preferences": preferences,
        "confidence": {
            "score": confidence_score,
            "label": "High" if confidence_score >= 85 else "Moderate",
            "reason": (
                "True hourly forecast points"
                if forecast.get("is_true_hourly")
                else "Available 3-hour forecast checkpoints"
            ),
        },
        "freshness": (
            _freshness_view(
                datetime.fromtimestamp(
                    int(_number(observed_timestamp)), timezone.utc
                ).isoformat()
            )
            if observed_timestamp
            else {"timestamp": "", "minutes": None, "label": "Latest cached forecast"}
        ),
        "why": why,
        "source": (
            "OpenWeather One Call 3.0"
            if forecast.get("is_true_hourly")
            else "OpenWeather 5-day / 3-hour forecast"
        ),
    }


def _official_alerts_view_model(one_call_data):
    utc_offset = _normalise_utc_offset(one_call_data.get("timezone_offset", 0))
    alerts = []
    for index, alert in enumerate(one_call_data.get("alerts", [])):
        if not isinstance(alert, dict):
            continue
        event = str(alert.get("event") or "Official weather alert").strip()
        description = " ".join(str(alert.get("description") or "").split())
        sender = str(alert.get("sender_name") or "Local weather authority").strip()
        end_time = _local_datetime(alert.get("end"), utc_offset)
        alerts.append(
            {
                "id": f"official-{int(_number(alert.get('start')))}-{index}",
                "severity": "danger",
                "title": event[:120],
                "message": description[:700]
                or "Follow the issuing authority for local safety instructions.",
                "official": True,
                "source": sender[:120],
                "ends_at": (
                    end_time.strftime("%d %b · %H:%M") if end_time else ""
                ),
            }
        )
    return alerts[:6]


AQI_LEVELS = {
    1: (
        "Good",
        "good",
        "Air quality is suitable for normal outdoor activities.",
    ),
    2: (
        "Fair",
        "fair",
        "Air quality is generally acceptable; unusually sensitive people may take care.",
    ),
    3: (
        "Moderate",
        "moderate",
        "Sensitive people may consider reducing prolonged outdoor exertion.",
    ),
    4: (
        "Poor",
        "poor",
        "Reduce prolonged outdoor exertion, especially if you are sensitive to pollution.",
    ),
    5: (
        "Very poor",
        "very-poor",
        "Avoid strenuous outdoor activity and follow local health guidance.",
    ),
}


def _air_quality_view_model(pollution_data):
    entries = pollution_data.get("list") or []
    if not entries or not isinstance(entries[0], dict):
        return None
    entry = entries[0]
    aqi = max(1, min(5, int(_number(entry.get("main", {}).get("aqi"), 1))))
    label, css_class, guidance = AQI_LEVELS[aqi]
    components = entry.get("components", {})
    return {
        "index": aqi,
        "label": label,
        "css_class": css_class,
        "guidance": guidance,
        "pm2_5": round(_number(components.get("pm2_5")), 1),
        "pm10": round(_number(components.get("pm10")), 1),
        "no2": round(_number(components.get("no2")), 1),
        "o3": round(_number(components.get("o3")), 1),
        "unit": "μg/m³",
        "observed_at": entry.get("dt"),
    }


def _history_view_model(history_data, forecast, units):
    daily = history_data.get("daily", {})
    daily_units = history_data.get("daily_units", {})
    dates = daily.get("time", [])
    maxima = daily.get("temperature_2m_max", [])
    minima = daily.get("temperature_2m_min", [])
    precipitation = daily.get("precipitation_sum", [])
    winds = daily.get("wind_speed_10m_max", [])
    count = min(len(dates), len(maxima), len(minima), len(precipitation), len(winds))
    entries = []
    for index in range(count):
        if maxima[index] is None or minima[index] is None:
            continue
        try:
            date_value = datetime.strptime(dates[index], "%Y-%m-%d").date()
        except (TypeError, ValueError):
            continue
        entries.append(
            {
                "date": dates[index],
                "day": date_value.strftime("%a"),
                "maximum": round(_number(maxima[index])),
                "minimum": round(_number(minima[index])),
                "precipitation": round(_number(precipitation[index]), 1),
                "wind": round(_number(winds[index])),
            }
        )
    if not entries:
        return None

    yesterday = entries[-1]
    today_maximum = (
        forecast.get("daily", [{}])[0].get("maximum")
        if forecast and forecast.get("daily")
        else None
    )
    maximum_change = (
        round(_number(today_maximum) - yesterday["maximum"])
        if today_maximum is not None
        else None
    )
    return {
        "entries": entries,
        "yesterday": yesterday,
        "today_maximum": today_maximum,
        "maximum_change": maximum_change,
        "average_maximum": round(
            sum(entry["maximum"] for entry in entries) / len(entries), 1
        ),
        "average_minimum": round(
            sum(entry["minimum"] for entry in entries) / len(entries), 1
        ),
        "precipitation_total": round(
            sum(entry["precipitation"] for entry in entries), 1
        ),
        "temperature_unit": "C" if units == "metric" else "F",
        "wind_unit": "km/h" if units == "metric" else "mph",
        "precipitation_unit": (
            "in"
            if daily_units.get("precipitation_sum") == "inch"
            else daily_units.get("precipitation_sum", "mm")
        ),
        "source": "Open-Meteo reanalysis",
    }


def _iso_datetime(value):
    if not value:
        return None
    try:
        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
    except ValueError:
        return None


def _freshness_view(timestamp, now_utc=None):
    parsed = _iso_datetime(timestamp)
    if not parsed:
        return {"timestamp": str(timestamp or ""), "minutes": None, "label": "Time unavailable"}
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=timezone.utc)
    now_utc = now_utc or datetime.now(timezone.utc)
    age_minutes = max(
        0,
        round((now_utc - parsed.astimezone(timezone.utc)).total_seconds() / 60),
    )
    if age_minutes < 2:
        label = "Updated just now"
    elif age_minutes < 60:
        label = f"Updated {age_minutes} min ago"
    else:
        label = f"Updated {age_minutes // 60} hr ago"
    return {
        "timestamp": parsed.isoformat(timespec="minutes"),
        "minutes": age_minutes,
        "label": label,
    }


def _environmental_view_model(environment_data):
    if not isinstance(environment_data, dict):
        return None
    current = environment_data.get("current", {})
    hourly = environment_data.get("hourly", {})
    if not isinstance(hourly, dict):
        return None

    def numeric_values(key):
        values = hourly.get(key, [])
        return [
            _number(value)
            for value in values
            if value is not None
        ] if isinstance(values, list) else []

    uv_values = numeric_values("uv_index")
    aqi_values = numeric_values("us_aqi")
    pollen_keys = (
        "grass_pollen",
        "birch_pollen",
        "alder_pollen",
        "mugwort_pollen",
        "olive_pollen",
        "ragweed_pollen",
    )
    pollen_series = {
        key: numeric_values(key)
        for key in pollen_keys
        if numeric_values(key)
    }
    pollen_peak = max(
        (max(values) for values in pollen_series.values()),
        default=None,
    )
    if pollen_peak is None:
        pollen_label = "Unavailable in this model region"
    elif pollen_peak < 10:
        pollen_label = "Low"
    elif pollen_peak < 50:
        pollen_label = "Moderate"
    elif pollen_peak < 200:
        pollen_label = "High"
    else:
        pollen_label = "Very high"

    uv_index = _number(current.get("uv_index"), max(uv_values, default=0))
    if uv_index < 3:
        uv_label, uv_tone = "Low", "clear"
    elif uv_index < 6:
        uv_label, uv_tone = "Moderate", "caution"
    elif uv_index < 8:
        uv_label, uv_tone = "High", "warning"
    elif uv_index < 11:
        uv_label, uv_tone = "Very high", "danger"
    else:
        uv_label, uv_tone = "Extreme", "danger"

    return {
        "uv_index": round(uv_index, 1),
        "uv_max_24h": round(max(uv_values, default=uv_index), 1),
        "uv_label": uv_label,
        "uv_tone": uv_tone,
        "us_aqi": round(_number(current.get("us_aqi"), max(aqi_values, default=0))),
        "us_aqi_max_24h": round(max(aqi_values, default=_number(current.get("us_aqi")))),
        "pm2_5": round(_number(current.get("pm2_5")), 1),
        "pm10": round(_number(current.get("pm10")), 1),
        "pollen_available": pollen_peak is not None,
        "pollen_peak": round(pollen_peak, 1) if pollen_peak is not None else None,
        "pollen_label": pollen_label,
        "pollen_species": [key.replace("_", " ") for key in pollen_series],
        "hourly": {
            "time": hourly.get("time", []),
            "uv_index": hourly.get("uv_index", []),
            "us_aqi": hourly.get("us_aqi", []),
        },
        "freshness": _freshness_view(current.get("time")),
        "source": "Open-Meteo · CAMS global",
        "pollen_note": (
            "CAMS pollen forecasts are currently available only in Europe."
            if pollen_peak is None
            else "Modelled pollen concentration; local conditions may vary."
        ),
    }


def _nearest_metadata(records, latitude, longitude, location_key):
    candidates = []
    for record in records or []:
        if not isinstance(record, dict):
            continue
        location = record.get(location_key, {})
        record_latitude = location.get("latitude")
        record_longitude = location.get("longitude")
        if record_latitude is None or record_longitude is None:
            continue
        distance = (
            (_number(record_latitude) - _number(latitude)) ** 2
            + (_number(record_longitude) - _number(longitude)) ** 2
        )
        candidates.append((distance, record))
    return min(candidates, default=(None, None), key=lambda item: item[0])[1]


def _psi_category(value):
    value = round(_number(value))
    if value <= 50:
        return "Good", "clear"
    if value <= 100:
        return "Moderate", "caution"
    if value <= 200:
        return "Unhealthy", "warning"
    if value <= 300:
        return "Very unhealthy", "danger"
    return "Hazardous", "danger"


def _singapore_official_view_model(
    two_hour_data,
    psi_data,
    uv_data,
    latitude,
    longitude,
):
    result = {
        "source": "Singapore Government · data.gov.sg",
        "two_hour": None,
        "psi": None,
        "uv": None,
        "lightning": {
            "available": False,
            "note": "The public lightning endpoint currently requires additional access.",
        },
    }
    if isinstance(two_hour_data, dict):
        data = two_hour_data.get("data", {})
        nearest_area = _nearest_metadata(
            data.get("area_metadata", []),
            latitude,
            longitude,
            "label_location",
        )
        items = data.get("items", [])
        item = items[0] if items and isinstance(items[0], dict) else None
        if nearest_area and item:
            area_name = nearest_area.get("name", "Nearest area")
            forecasts = {
                forecast.get("area"): forecast.get("forecast")
                for forecast in item.get("forecasts", [])
                if isinstance(forecast, dict)
            }
            result["two_hour"] = {
                "area": area_name,
                "forecast": forecasts.get(area_name, "Unavailable"),
                "period": item.get("valid_period", {}).get("text", ""),
                "freshness": _freshness_view(item.get("update_timestamp")),
            }

    if isinstance(psi_data, dict):
        data = psi_data.get("data", {})
        nearest_region = _nearest_metadata(
            data.get("regionMetadata", []),
            latitude,
            longitude,
            "labelLocation",
        )
        items = data.get("items", [])
        item = items[0] if items and isinstance(items[0], dict) else None
        if nearest_region and item:
            region = nearest_region.get("name", "national")
            readings = item.get("readings", {})
            psi_value = readings.get("psi_twenty_four_hourly", {}).get(region)
            if psi_value is not None:
                label, tone = _psi_category(psi_value)
                result["psi"] = {
                    "region": region.title(),
                    "value": round(_number(psi_value)),
                    "label": label,
                    "tone": tone,
                    "pm2_5": readings.get("pm25_twenty_four_hourly", {}).get(region),
                    "freshness": _freshness_view(
                        item.get("updatedTimestamp") or item.get("timestamp")
                    ),
                }

    if isinstance(uv_data, dict):
        records = uv_data.get("data", {}).get("records", [])
        record = records[0] if records and isinstance(records[0], dict) else None
        indices = record.get("index", []) if record else []
        valid_indices = [
            index
            for index in indices
            if isinstance(index, dict)
            and index.get("hour")
            and index.get("value") is not None
        ]
        if valid_indices:
            latest = max(valid_indices, key=lambda index: index["hour"])
            value = _number(latest.get("value"))
            if value < 3:
                label, tone = "Low", "clear"
            elif value < 6:
                label, tone = "Moderate", "caution"
            elif value < 8:
                label, tone = "High", "warning"
            elif value < 11:
                label, tone = "Very high", "danger"
            else:
                label, tone = "Extreme", "danger"
            result["uv"] = {
                "value": round(value, 1),
                "label": label,
                "tone": tone,
                "freshness": _freshness_view(latest.get("hour")),
            }
    return result if any((result["two_hour"], result["psi"], result["uv"])) else None


def _temperature_as_celsius(value, units):
    value = _number(value)
    return (value - 32) * 5 / 9 if units == "imperial" else value


def _wind_as_kmh(value, units):
    value = _number(value)
    return value * 1.609344 if units == "imperial" else value * 3.6


def _build_advisories(weather_data, forecast, air_quality, units):
    advisories = []
    seen = set()

    def add(identifier, severity, title, message):
        if identifier in seen:
            return
        seen.add(identifier)
        advisories.append(
            {
                "id": identifier,
                "severity": severity,
                "title": title,
                "message": message,
                "official": False,
                "source": "SkyCast forecast rules",
                "ends_at": "",
            }
        )

    current_condition = (weather_data.get("weather") or [{}])[0]
    current_id = int(_number(current_condition.get("id")))
    current_visibility = _number(weather_data.get("visibility"), 10000)
    current_temp_c = _temperature_as_celsius(
        weather_data.get("main", {}).get("temp"), units
    )
    current_wind_kmh = _wind_as_kmh(
        weather_data.get("wind", {}).get("speed"), units
    )

    forecast_items = forecast.get("items", []) if forecast else []
    condition_ids = [current_id] + [item["condition_id"] for item in forecast_items]
    if any(200 <= condition_id < 300 for condition_id in condition_ids):
        add(
            "thunderstorm",
            "danger",
            "Thunderstorm possible",
            "Lightning and sudden heavy rain may occur. Seek shelter when thunder is heard.",
        )

    if any(
        item["rain_volume"] >= 10 or 502 <= item["condition_id"] <= 504
        for item in forecast_items
    ):
        add(
            "heavy-rain",
            "warning",
            "Heavy rain possible",
            "Allow extra travel time and avoid flooded roads or low-lying areas.",
        )

    if any(
        item["snow_volume"] >= 5 or item["condition_id"] in {602, 622}
        for item in forecast_items
    ):
        add(
            "heavy-snow",
            "warning",
            "Heavy snow possible",
            "Travel may be difficult. Check local road and transport updates.",
        )

    maximum_temp_c = max(
        [current_temp_c]
        + [
            _temperature_as_celsius(item["maximum"], units)
            for item in forecast_items
        ]
    )
    minimum_temp_c = min(
        [current_temp_c]
        + [
            _temperature_as_celsius(item["minimum"], units)
            for item in forecast_items
        ]
    )
    if maximum_temp_c >= 35:
        add(
            "heat",
            "warning",
            "High heat expected",
            "Stay hydrated, limit strenuous activity, and check on vulnerable people.",
        )
    if minimum_temp_c <= -10:
        add(
            "cold",
            "warning",
            "Very cold conditions",
            "Limit exposure and protect people, pets, and pipes from freezing temperatures.",
        )

    maximum_wind_kmh = max(
        [current_wind_kmh]
        + [_wind_as_kmh(item["wind_gust"], units) for item in forecast_items]
    )
    if maximum_wind_kmh >= 65:
        add(
            "wind",
            "warning",
            "Strong wind possible",
            "Secure loose outdoor items and take care near trees and exposed areas.",
        )

    if current_visibility < 1000:
        add(
            "visibility",
            "caution",
            "Very low visibility",
            "Use extra caution when travelling and allow greater stopping distance.",
        )
    if air_quality and air_quality["index"] >= 4:
        add(
            "air-quality",
            "caution",
            f"{air_quality['label']} air quality",
            air_quality["guidance"],
        )

    severity_order = {"danger": 0, "warning": 1, "caution": 2}
    return sorted(
        advisories,
        key=lambda advisory: severity_order[advisory["severity"]],
    )[:4]


def _load_supplemental_weather(
    latitude,
    longitude,
    units,
    *,
    include_singapore=False,
):
    if app.testing and not app.config.get("TEST_SUPPLEMENTAL_WEATHER"):
        return (None,) * 8

    def optional(loader):
        try:
            return loader()
        except (WeatherConfigurationError, WeatherNotFoundError, WeatherServiceError):
            return None

    load_environment = (
        not app.testing or app.config.get("TEST_ENVIRONMENTAL_WEATHER")
    )
    with ThreadPoolExecutor(max_workers=8) as executor:
        forecast_future = executor.submit(
            optional,
            lambda: _cached_forecast(latitude, longitude, units),
        )
        air_future = executor.submit(
            optional,
            lambda: _cached_air_quality(latitude, longitude),
        )
        history_future = executor.submit(
            optional,
            lambda: _cached_history(latitude, longitude, units),
        )
        one_call_future = (
            executor.submit(
                optional,
                lambda: _cached_one_call(latitude, longitude, units),
            )
            if ONE_CALL_ENABLED
            else None
        )
        environment_future = (
            executor.submit(
                optional,
                lambda: _cached_environment(latitude, longitude),
            )
            if load_environment
            else None
        )
        singapore_two_hour_future = (
            executor.submit(optional, _cached_singapore_two_hour)
            if include_singapore and load_environment
            else None
        )
        singapore_psi_future = (
            executor.submit(optional, _cached_singapore_psi)
            if include_singapore and load_environment
            else None
        )
        singapore_uv_future = (
            executor.submit(optional, _cached_singapore_uv)
            if include_singapore and load_environment
            else None
        )
        return (
            forecast_future.result(),
            air_future.result(),
            history_future.result(),
            one_call_future.result() if one_call_future else None,
            environment_future.result() if environment_future else None,
            (
                singapore_two_hour_future.result()
                if singapore_two_hour_future
                else None
            ),
            singapore_psi_future.result() if singapore_psi_future else None,
            singapore_uv_future.result() if singapore_uv_future else None,
        )


def _validated_coordinates(latitude, longitude):
    if latitude is None and longitude is None:
        return None
    if latitude is None or longitude is None:
        raise ValueError("Both latitude and longitude are required.")

    try:
        latitude = float(latitude)
        longitude = float(longitude)
    except ValueError as exc:
        raise ValueError("The location coordinates are invalid.") from exc

    if not -90 <= latitude <= 90 or not -180 <= longitude <= 180:
        raise ValueError("The location coordinates are outside the valid range.")
    return latitude, longitude


def _requested_coordinates():
    latitude = request.args.get("lat")
    longitude = request.args.get("lon")
    if isinstance(latitude, str) and not latitude.strip():
        latitude = None
    if isinstance(longitude, str) and not longitude.strip():
        longitude = None
    return _validated_coordinates(
        latitude,
        longitude,
    )


def _json_response(payload, status_code=200):
    response = jsonify(payload)
    response.headers["Cache-Control"] = "no-store"
    return response, status_code


def _personal_planner_bundle(
    latitude,
    longitude,
    units,
    preferences,
    activity,
):
    preferences = validate_planner_preferences(preferences)
    activity = validate_activity(activity)
    weather_data = _cached_current_weather(
        latitude=latitude,
        longitude=longitude,
        units=units,
    )
    forecast = _forecast_view_model(
        _cached_forecast(latitude, longitude, units),
        units,
    )
    if ONE_CALL_ENABLED:
        try:
            forecast = _enhance_forecast_with_one_call(
                forecast,
                _cached_one_call(latitude, longitude, units),
                units,
            )
        except (WeatherConfigurationError, WeatherServiceError):
            pass
    environment = None
    try:
        environment = _environmental_view_model(
            _cached_environment(latitude, longitude)
        )
    except WeatherServiceError:
        pass
    guidance = _build_five_hour_guidance(
        forecast,
        units,
        preferences=preferences,
        activity=activity,
        environment=environment,
        observed_timestamp=weather_data.get("dt"),
    )
    outdoor = best_outdoor_window(
        forecast,
        environment,
        units,
        preferences=preferences,
        activity=activity,
    )
    activity_result = activity_guidance(
        activity,
        forecast,
        environment,
        units,
        preferences=preferences,
    )
    heat = heat_stress_view(
        weather_data.get("main", {}).get("temp"),
        weather_data.get("main", {}).get("humidity"),
        units,
    )
    return {
        "preferences": preferences,
        "activity": activity,
        "guidance": guidance,
        "outdoor_window": outdoor,
        "activity_guidance": activity_result,
        "environment": environment,
        "heat_stress": heat,
    }


def _ical_escape(value):
    return (
        str(value or "")
        .replace("\\", "\\\\")
        .replace(";", "\\;")
        .replace(",", "\\,")
        .replace("\r\n", "\\n")
        .replace("\n", "\\n")
    )


def _ical_fold(line, limit=73):
    if len(line) <= limit:
        return [line]
    pieces = [line[:limit]]
    line = line[limit:]
    while line:
        pieces.append(f" {line[:limit - 1]}")
        line = line[limit - 1:]
    return pieces


def _weather_calendar(location, bundle, activity):
    window = bundle.get("outdoor_window")
    if not window:
        raise ValueError("No suitable forecast window is available for export.")
    start = _iso_datetime(window["start_iso"])
    end = _iso_datetime(window["end_iso"])
    if not start or not end:
        raise ValueError("The forecast window time is unavailable.")
    start_utc = start.astimezone(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    end_utc = end.astimezone(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    created = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    uid_seed = (
        f"{location}|{activity}|{window['start_iso']}|{window['end_iso']}"
    )
    import hashlib

    uid = f"{hashlib.sha256(uid_seed.encode('utf-8')).hexdigest()[:24]}@skycast.local"
    summary = f"Best time for {window['activity_label'].lower()} · {location}"
    description = (
        f"SkyCast score {window['score']}/100 ({window['label']}). "
        f"{window['summary']}. Confidence: {window['confidence_label']} "
        f"({window['confidence']}%). Recheck live conditions before leaving."
    )
    raw_lines = [
        "BEGIN:VCALENDAR",
        "VERSION:2.0",
        "PRODID:-//SkyCast//Weather Planner//EN",
        "CALSCALE:GREGORIAN",
        "METHOD:PUBLISH",
        "BEGIN:VEVENT",
        f"UID:{uid}",
        f"DTSTAMP:{created}",
        f"DTSTART:{start_utc}",
        f"DTEND:{end_utc}",
        f"SUMMARY:{_ical_escape(summary)}",
        f"LOCATION:{_ical_escape(location)}",
        f"DESCRIPTION:{_ical_escape(description)}",
        "TRANSP:TRANSPARENT",
        "END:VEVENT",
        "END:VCALENDAR",
    ]
    return "\r\n".join(
        folded
        for line in raw_lines
        for folded in _ical_fold(line)
    ) + "\r\n"


def _validated_catalog_filters(country_code="", state_code=""):
    country_code = (country_code or "").strip().upper()
    state_code = (state_code or "").strip().upper()

    subdivision = None
    if state_code:
        subdivision = SUBDIVISIONS_BY_CODE.get(state_code)
        if not subdivision:
            raise ValueError("The selected state or province is invalid.")
        if country_code and subdivision["country_code"] != country_code:
            raise ValueError(
                "The selected state or province does not belong to that country."
            )
        country_code = subdivision["country_code"]

    if country_code and country_code not in COUNTRIES_BY_CODE:
        raise ValueError("The selected country is invalid.")

    return country_code, state_code


def _catalog_matches(query, country_code="", state_code=""):
    search_term = _alphabetical_key(query)

    def match_rank(item):
        name = _alphabetical_key(item["name"])
        return (0 if name.startswith(search_term) else 1, name)

    countries = [
        country
        for country in COUNTRY_CATALOG
        if search_term in _alphabetical_key(country["name"])
        and (not country_code or country["code"] == country_code)
    ]
    countries.sort(key=match_rank)

    subdivision_scope = (
        SUBDIVISIONS_BY_COUNTRY.get(country_code, ())
        if country_code
        else SUBDIVISION_CATALOG
    )
    subdivisions = [
        subdivision
        for subdivision in subdivision_scope
        if search_term in _alphabetical_key(subdivision["name"])
        and (not state_code or subdivision["code"] == state_code)
    ]
    subdivisions.sort(key=match_rank)

    suggestions = [
        {
            "kind": "country",
            "label": country["name"],
            "detail": "Country or territory",
            "country_code": country["code"],
        }
        for country in countries
    ]
    suggestions.extend(
        {
            "kind": "state",
            "label": subdivision["name"],
            "detail": (
                f"{subdivision['type']} · "
                f"{COUNTRIES_BY_CODE[subdivision['country_code']]['name']}"
            ),
            "country_code": subdivision["country_code"],
            "state_code": subdivision["code"],
        }
        for subdivision in subdivisions
    )
    return suggestions


def _place_suggestion(location):
    name = str(location.get("name", "")).strip()
    state = str(location.get("state", "")).strip()
    country_code = str(location.get("country", "")).strip().upper()
    country_name = COUNTRIES_BY_CODE.get(
        country_code,
        {"name": country_code or "Unknown country"},
    )["name"]

    label_parts = [name]
    if state and state.casefold() != name.casefold():
        label_parts.append(state)
    if country_name and country_name.casefold() != name.casefold():
        label_parts.append(country_name)

    return {
        "kind": "place",
        "label": ", ".join(label_parts),
        "detail": f"Place · {country_name}",
        "name": name,
        "state": state,
        "country_code": country_code,
        "latitude": float(location["lat"]),
        "longitude": float(location["lon"]),
    }


def _render_error(title, message, status_code, city="", unit="metric"):
    return (
        render_template(
            "city-not-found.html",
            page_title=title,
            error_title=title,
            error_message=message,
            city=city,
            unit=unit,
            theme="home",
            selected_country="",
            selected_state="",
            catalog_subdivisions=(),
        ),
        status_code,
    )


@app.get("/")
@app.get("/index")
def index():
    return render_template(
        "index.html",
        page_title="Weather at a glance",
        city="",
        unit="metric",
        theme="home",
    )


@app.get("/healthz")
def health_check():
    with REQUEST_METRICS_LOCK:
        request_count = int(REQUEST_METRICS.get("requests", 0))
        server_errors = int(REQUEST_METRICS.get("5xx", 0))
    response = jsonify(
        {
            "status": "ok",
            "uptime_seconds": round(monotonic() - APP_STARTED_AT),
            "requests": request_count,
            "server_errors": server_errors,
            "cache_backend": CACHE_BACKEND,
            "features": {
                "one_call": ONE_CALL_ENABLED,
                "push": push_configuration()["enabled"],
                "sentry": SENTRY_ACTIVE,
            },
        }
    )
    response.headers["Cache-Control"] = "no-store"
    return response


@app.get("/service-worker.js")
def service_worker():
    response = send_from_directory(
        app.static_folder,
        "service-worker.js",
        mimetype="application/javascript",
        max_age=0,
    )
    response.headers["Service-Worker-Allowed"] = "/"
    response.headers["Cache-Control"] = "no-cache"
    return response


@app.get("/api/push/config")
def get_push_configuration():
    configuration = push_configuration()
    return _json_response(
        {
            "enabled": configuration["enabled"],
            "public_key": configuration["public_key"],
            "default_rules": DEFAULT_ALERT_RULES,
        }
    )


@app.get("/api/planner/config")
def get_planner_configuration():
    return _json_response(
        {
            "preferences": DEFAULT_PLANNER_PREFERENCES,
            "activities": [
                {
                    "id": identifier,
                    "label": profile["label"],
                    "symbol": profile["symbol"],
                }
                for identifier, profile in ACTIVITY_PROFILES.items()
            ],
        }
    )


@app.post("/api/planner")
def calculate_personal_planner():
    payload = request.get_json(silent=True)
    if not isinstance(payload, dict):
        return _json_response({"error": "A JSON planner request is required."}, 400)
    try:
        coordinates = _validated_coordinates(
            payload.get("latitude"),
            payload.get("longitude"),
        )
        if not coordinates:
            raise ValueError("Planner coordinates are required.")
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)
    units = str(payload.get("unit") or "metric").lower()
    if units not in {"metric", "imperial"}:
        units = "metric"
    try:
        bundle = _personal_planner_bundle(
            coordinates[0],
            coordinates[1],
            units,
            payload.get("preferences"),
            payload.get("activity"),
        )
    except WeatherNotFoundError:
        return _json_response({"error": "Weather data was not found."}, 404)
    except (WeatherConfigurationError, WeatherServiceError):
        return _json_response(
            {"error": "Personal planning data is temporarily unavailable."},
            503,
        )
    return _json_response(bundle)


@app.get("/api/calendar")
def download_weather_calendar():
    try:
        coordinates = _validated_coordinates(
            request.args.get("lat"),
            request.args.get("lon"),
        )
        if not coordinates:
            raise ValueError("Calendar coordinates are required.")
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)
    units = (request.args.get("unit") or "metric").lower()
    if units not in {"metric", "imperial"}:
        units = "metric"
    activity = validate_activity(request.args.get("activity"))
    preferences = validate_planner_preferences(
        {
            key: request.args.get(key)
            for key in DEFAULT_PLANNER_PREFERENCES
            if request.args.get(key) is not None
        }
    )
    location = (request.args.get("location") or "Selected location").strip()[:160]
    try:
        bundle = _personal_planner_bundle(
            coordinates[0],
            coordinates[1],
            units,
            preferences,
            activity,
        )
        calendar = _weather_calendar(location, bundle, activity)
    except ValueError as error:
        return _json_response({"error": str(error)}, 404)
    except (WeatherConfigurationError, WeatherNotFoundError, WeatherServiceError):
        return _json_response(
            {"error": "Calendar weather data is temporarily unavailable."},
            503,
        )
    response = app.response_class(
        calendar,
        mimetype="text/calendar",
    )
    response.headers["Content-Disposition"] = "attachment; filename=skycast-plan.ics"
    response.headers["Cache-Control"] = "no-store"
    return response


@app.post("/api/push/subscribe")
def subscribe_to_push():
    configuration = push_configuration()
    if not configuration["enabled"]:
        return _json_response(
            {"error": "Background alerts are not configured on this server."},
            503,
        )
    origin = request.headers.get("Origin", "").strip()
    if origin:
        parsed_origin = urlsplit(origin)
        if parsed_origin.scheme not in {"http", "https"} or parsed_origin.netloc != request.host:
            return _json_response({"error": "Cross-origin subscriptions are not allowed."}, 403)

    payload = request.get_json(silent=True)
    if not isinstance(payload, dict):
        return _json_response({"error": "A JSON subscription is required."}, 400)
    try:
        coordinates = _validated_coordinates(
            payload.get("latitude"),
            payload.get("longitude"),
        )
        if not coordinates:
            raise ValueError("Alert coordinates are required.")
        save_subscription(
            payload.get("subscription"),
            coordinates[0],
            coordinates[1],
            payload.get("unit"),
            payload.get("location"),
            alert_rules=payload.get("alert_rules"),
            utc_offset=payload.get("utc_offset", 0),
        )
    except (TypeError, ValueError) as error:
        return _json_response({"error": str(error)}, 400)
    return _json_response({"subscribed": True}, 201)


@app.post("/api/push/rules")
def manage_push_alert_rules():
    configuration = push_configuration()
    if not configuration["enabled"]:
        return _json_response(
            {"error": "Background alerts are not configured on this server."},
            503,
        )
    origin = request.headers.get("Origin", "").strip()
    if origin:
        parsed_origin = urlsplit(origin)
        if parsed_origin.scheme not in {"http", "https"} or parsed_origin.netloc != request.host:
            return _json_response({"error": "Cross-origin rules are not allowed."}, 403)
    payload = request.get_json(silent=True)
    if not isinstance(payload, dict) or not isinstance(payload.get("subscription"), dict):
        return _json_response(
            {"error": "A browser push subscription is required."},
            400,
        )
    try:
        if "rules" in payload:
            rules = save_alert_rules(
                payload["subscription"],
                validate_alert_rules(payload.get("rules")),
            )
        else:
            rules = get_alert_rules(payload["subscription"])
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)
    return _json_response({"rules": rules})


@app.post("/api/location-time")
def get_location_time():
    payload = request.get_json(silent=True) or {}
    try:
        coordinates = _validated_coordinates(
            payload.get("latitude"),
            payload.get("longitude"),
        )
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)

    if not coordinates:
        return _json_response(
            {"error": "Latitude and longitude are required."},
            400,
        )

    try:
        weather_data = _cached_current_weather(
            latitude=coordinates[0],
            longitude=coordinates[1],
            units="metric",
        )
    except WeatherNotFoundError:
        return _json_response({"error": "Your location could not be found."}, 404)
    except (WeatherConfigurationError, WeatherServiceError):
        return _json_response(
            {"error": "Your local time could not be resolved right now."},
            503,
        )

    city = weather_data.get("name") or "Your current location"
    country = weather_data.get("sys", {}).get("country", "")
    location = f"{city}, {country}" if country else city
    utc_offset = _normalise_utc_offset(weather_data.get("timezone", 0))
    return _json_response(
        {
            "location": location,
            "utc_offset": utc_offset,
            "utc_label": _format_utc_offset(utc_offset),
        }
    )


@app.get("/api/weather-summary")
def get_weather_summary():
    try:
        coordinates = _validated_coordinates(
            request.args.get("lat"),
            request.args.get("lon"),
        )
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)
    if not coordinates:
        return _json_response(
            {"error": "Latitude and longitude are required."},
            400,
        )

    units = (request.args.get("unit") or "metric").lower()
    if units not in {"metric", "imperial"}:
        units = "metric"
    try:
        weather_data = _cached_current_weather(
            latitude=coordinates[0],
            longitude=coordinates[1],
            units=units,
        )
    except WeatherNotFoundError:
        return _json_response({"error": "Weather data was not found."}, 404)
    except (WeatherConfigurationError, WeatherServiceError):
        return _json_response(
            {"error": "Weather data is temporarily unavailable."},
            503,
        )

    weather = _weather_view_model(weather_data, units)
    return _json_response(
        {
            "location": weather["location"],
            "city": weather["city"],
            "country": weather["country"],
            "latitude": weather["latitude"],
            "longitude": weather["longitude"],
            "temperature": weather["temperature"],
            "temperature_unit": weather["temperature_unit"],
            "description": weather["description"],
            "theme": weather["theme"],
            "humidity": weather["humidity"],
            "wind_speed": weather["wind_speed"],
            "wind_unit": weather["wind_unit"],
        }
    )


@app.get("/api/countries")
def get_countries():
    return _json_response({"countries": COUNTRY_CATALOG})


@app.get("/api/states")
def get_states():
    try:
        country_code, _ = _validated_catalog_filters(
            request.args.get("country"),
        )
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)

    if not country_code:
        return _json_response({"error": "A country is required."}, 400)
    return _json_response(
        {
            "country": country_code,
            "states": SUBDIVISIONS_BY_COUNTRY.get(country_code, ()),
        }
    )


@app.get("/api/location-suggestions")
def get_location_suggestions():
    query = (request.args.get("q") or "").strip()[:100]
    if len(query) < 1:
        return _json_response({"suggestions": []})

    try:
        country_code, state_code = _validated_catalog_filters(
            request.args.get("country"),
            request.args.get("state"),
        )
    except ValueError as error:
        return _json_response({"error": str(error)}, 400)

    suggestions = _catalog_matches(
        query,
        country_code,
        state_code,
    )
    notice = ""
    places = []
    if len(query) >= 2:
        try:
            places = _cached_location_search(
                query,
                country_code=country_code,
                state_code=state_code,
                limit=5,
            )
        except (WeatherConfigurationError, WeatherServiceError):
            notice = "Live place matching is temporarily unavailable."
    else:
        notice = "Type one more character to include live place matches."

    seen_places = set()
    for place in places:
        suggestion = _place_suggestion(place)
        key = (
            suggestion["name"].casefold(),
            suggestion["state"].casefold(),
            suggestion["country_code"],
        )
        if key in seen_places:
            continue
        seen_places.add(key)
        suggestions.append(suggestion)

    return _json_response(
        {
            "suggestions": suggestions,
            "counts": {
                "countries": sum(
                    suggestion["kind"] == "country"
                    for suggestion in suggestions
                ),
                "states": sum(
                    suggestion["kind"] == "state"
                    for suggestion in suggestions
                ),
                "places": sum(
                    suggestion["kind"] == "place"
                    for suggestion in suggestions
                ),
            },
            "notice": notice,
        }
    )


@app.get("/weather")
def get_weather():
    city = (request.args.get("city") or "").strip()
    unit = (request.args.get("unit") or "metric").lower()
    if unit not in {"metric", "imperial"}:
        unit = "metric"

    try:
        coordinates = _requested_coordinates()
        country_code, state_code = _validated_catalog_filters(
            request.args.get("country"),
            request.args.get("state"),
        )
    except ValueError as error:
        return _render_error(
            "Location unavailable",
            str(error),
            400,
            city=city,
            unit=unit,
        )

    city = city or DEFAULT_CITY
    resolved_coordinates = coordinates
    try:
        if coordinates:
            weather_data = _cached_current_weather(
                latitude=coordinates[0],
                longitude=coordinates[1],
                units=unit,
            )
        elif country_code or state_code:
            matches = _cached_location_search(
                city,
                country_code=country_code,
                state_code=state_code,
                limit=1,
            )
            if not matches:
                raise WeatherNotFoundError
            resolved_coordinates = (
                float(matches[0]["lat"]),
                float(matches[0]["lon"]),
            )
            weather_data = _cached_current_weather(
                latitude=resolved_coordinates[0],
                longitude=resolved_coordinates[1],
                units=unit,
            )
        else:
            weather_data = _cached_current_weather(city, units=unit)
    except WeatherNotFoundError:
        return _render_error(
            "City not found",
            f'We could not find weather data for “{city}”. Check the spelling or try a nearby city.',
            404,
            city=city,
            unit=unit,
        )
    except WeatherConfigurationError:
        return _render_error(
            "Weather service not configured",
            "Add a valid API_KEY to the project’s .env file, then restart the server.",
            503,
            city=city,
            unit=unit,
        )
    except WeatherServiceError:
        return _render_error(
            "Weather service unavailable",
            "Live conditions could not be loaded right now. Please try again in a moment.",
            503,
            city=city,
            unit=unit,
        )

    weather = _weather_view_model(weather_data, unit)
    forecast = None
    air_quality = None
    history = None
    environment = None
    singapore_official = None
    outdoor_window = None
    selected_activity_guidance = None
    five_hour_guidance = None
    official_advisories = []
    heat_stress = heat_stress_view(
        weather_data.get("main", {}).get("temp"),
        weather_data.get("main", {}).get("humidity"),
        unit,
    )
    latitude = weather.get("latitude")
    longitude = weather.get("longitude")
    if latitude is not None and longitude is not None:
        (
            forecast_data,
            pollution_data,
            history_data,
            one_call_data,
            environment_data,
            singapore_two_hour_data,
            singapore_psi_data,
            singapore_uv_data,
        ) = _load_supplemental_weather(
            latitude,
            longitude,
            unit,
            include_singapore=weather.get("country") == "SG",
        )
        if forecast_data:
            forecast = _forecast_view_model(forecast_data, unit)
        if one_call_data:
            forecast = _enhance_forecast_with_one_call(
                forecast,
                one_call_data,
                unit,
            )
            official_advisories = _official_alerts_view_model(one_call_data)
        if pollution_data:
            air_quality = _air_quality_view_model(pollution_data)
        if history_data:
            history = _history_view_model(history_data, forecast, unit)
        if environment_data:
            environment = _environmental_view_model(environment_data)
        if weather.get("country") == "SG":
            singapore_official = _singapore_official_view_model(
                singapore_two_hour_data,
                singapore_psi_data,
                singapore_uv_data,
                latitude,
                longitude,
            )
    five_hour_guidance = _build_five_hour_guidance(
        forecast,
        unit,
        preferences=DEFAULT_PLANNER_PREFERENCES,
        environment=environment,
        observed_timestamp=weather_data.get("dt"),
    )
    outdoor_window = best_outdoor_window(
        forecast,
        environment,
        unit,
        preferences=DEFAULT_PLANNER_PREFERENCES,
    )
    selected_activity_guidance = activity_guidance(
        "general",
        forecast,
        environment,
        unit,
        preferences=DEFAULT_PLANNER_PREFERENCES,
    )
    planner_bundle = {
        "preferences": DEFAULT_PLANNER_PREFERENCES,
        "activity": "general",
        "guidance": five_hour_guidance,
        "outdoor_window": outdoor_window,
        "activity_guidance": selected_activity_guidance,
    }
    advisories = (
        official_advisories
        + _build_advisories(
            weather_data,
            forecast,
            air_quality,
            unit,
        )
    )[:6]
    location_query = (
        {"lat": resolved_coordinates[0], "lon": resolved_coordinates[1]}
        if resolved_coordinates
        else {"city": city}
    )

    return render_template(
        "weather.html",
        page_title=f"{weather['city']} weather",
        weather=weather,
        forecast=forecast,
        air_quality=air_quality,
        history=history,
        environment=environment,
        singapore_official=singapore_official,
        heat_stress=heat_stress,
        outdoor_window=outdoor_window,
        activity_guidance=selected_activity_guidance,
        activity_profiles=ACTIVITY_PROFILES,
        planner_preferences=DEFAULT_PLANNER_PREFERENCES,
        planner_bundle=planner_bundle,
        five_hour_guidance=five_hour_guidance,
        advisories=advisories,
        city=weather["city"],
        selected_country="",
        selected_state="",
        catalog_subdivisions=(),
        unit=unit,
        theme=weather["theme"],
        metric_url=url_for("get_weather", **location_query, unit="metric"),
        imperial_url=url_for("get_weather", **location_query, unit="imperial"),
    )


def run_skycast():
    """Run Waitress, opening the local site in Chrome only when running locally."""
    # Hosting platforms (Render, Heroku, Fly) assign a port through PORT and
    # route external traffic to it, so the server has to listen on every
    # interface or the platform's health check never finds it. Locally the
    # default stays 127.0.0.1, which keeps the dev server off the network.
    platform_port = os.getenv("PORT", "").strip()
    server_host = os.getenv("SKYCAST_HOST", "").strip() or ("0.0.0.0" if platform_port else "127.0.0.1")

    try:
        server_port = int(os.getenv("SKYCAST_PORT", "").strip() or platform_port or "8000")
    except ValueError:
        server_port = 8000
    if not 1 <= server_port <= 65535:
        server_port = 8000

    browser_host = (
        "127.0.0.1"
        if server_host in {"0.0.0.0", "::", "[::]"}
        else server_host
    )
    browser_url_host = (
        f"[{browser_host}]"
        if ":" in browser_host and not browser_host.startswith("[")
        else browser_host
    )
    website_url = os.getenv("SKYCAST_BROWSER_URL", "").strip() or (
        f"http://{browser_url_host}:{server_port}"
    )
    waitress_server = create_server(
        app,
        host=server_host,
        port=server_port,
        threads=8,
    )
    # Opening a browser on a headless deployment host is pointless, so the
    # default flips off whenever a platform port is present.
    if _environment_flag("SKYCAST_OPEN_BROWSER", not platform_port):
        start_browser_launcher(website_url)
    # Log the address actually bound, not the browsing URL: "running at
    # 127.0.0.1:8000" while listening on 0.0.0.0 is exactly the sort of message
    # that makes a port-binding failure hard to diagnose.
    print(f"SkyCast listening on {server_host}:{server_port}")
    print(f"SkyCast is running at {website_url}")
    try:
        waitress_server.run()
    except KeyboardInterrupt:
        pass
    finally:
        waitress_server.close()


if __name__ == "__main__":
    run_skycast()