geo-clock-card.ts

import { LitElement, html, css, svg, type TemplateResult } from 'lit';
import { customElement, property, state } from 'lit/decorators.js';
import { subsolarPoint, type SubsolarPoint } from './sun.js';
import { isDaylightAt, pickDayNightColor } from './marker-color.js';
import { terminatorCurve } from './terminator.js';
import { polygonToSvgPoints, latLonToPx } from './projection.js';
import { timezoneBand, BAND_H } from './timezone-band.js';
import { loadTimezones, timezonesToPolygons, type TzPolygon } from './timezones.js';
import {
  loadIanaTimezones,
  ianaToPolygons,
  zoneNow,
  findIanaZoneForLatLon,
  type IanaPolygon,
} from './timezones-iana.js';
import { dayImageForDate } from './day-image.js';
import type {
  GeoClockCardConfig,
  HassLike,
  MarkerConfig,
  ResolvedConfig,
} from './types.js';

// Equirectangular working canvas. The SVG scales to fit, so this is
// just internal coordinate space for the polygon math + image extents.
const MAP_W = 2048;
const MAP_H = 1024;

const NIGHT_IMAGE = 'black-marble-2048.jpg';
const TZ_DATA = 'timezones.json';
const TZ_IANA_DATA = 'timezones-iana.json';

// Re-projection threshold for the TZ polygon overlay, in degrees of
// centerLon drift. Re-projecting all 419 IANA features (~1 MB of
// path data, then browser re-tessellation) is the heaviest periodic
// task in the card, and sun mode moves centerLon ~0.044° per map
// tick — a quarter-pixel. We only rebuild past this threshold and
// absorb the residual drift with a group translate (pixel-exact,
// because translating the projected paths is mathematically the
// same as re-projecting on an equirectangular map).
const TZ_REBUILD_DEG = 0.5;



// The terminator + imagery + TZ overlay + hour band are derived from
// the subsolar point and only meaningfully change when the subsolar
// longitude has shifted by ≥0.5 px at a 4K-wide map:
//
//   360° / 4096 px / 2  =  0.0439° per half-pixel
//   ÷ 15° per hour        →   ~10.5 seconds
//
// Anything finer is sub-pixel even on hypothetical 4K dashboards, so
// throttling here saves polygon + path-string churn while leaving the
// wall-clock readout free to tick once a second.
const FOUR_K_WIDTH_PX = 4096;
const HALF_PX_DEG_AT_4K = 360 / FOUR_K_WIDTH_PX / 2;
const SUN_DEG_PER_MS = 15 / 3_600_000;
const MAP_UPDATE_INTERVAL_MS = HALF_PX_DEG_AT_4K / SUN_DEG_PER_MS;

// When the card is off-screen or the tab is backgrounded we cut the
// timer all the way down to one update every 30 minutes — enough to
// keep displayed values from being absurdly stale if the user
// suddenly brings the card back, but cheap enough to be invisible
// in CPU profiles. The card refreshes immediately the moment it
// becomes visible again.
const HIDDEN_INTERVAL_MS = 30 * 60 * 1000;

// HassLike is hoisted to types.ts so the editor can share the same
// minimal shape — see types.ts for the field-by-field rationale.

@customElement('geo-clock-card')
export class GeoClockCard extends LitElement {
  @property({ attribute: false }) hass?: HassLike;
  /** Wall-clock time used by the readout. Ticks at the configured
   *  updateInterval (default 1 s) so the displayed seconds advance
   *  smoothly. */
  @state() private displayNow = new Date();
  /** Time used by everything map-shaped (terminator, imagery offset,
   *  TZ overlay, hour band). Only advances when the subsolar point
   *  has moved ≥0.5 px at 4K — see MAP_UPDATE_INTERVAL_MS. */
  @state() private mapNow = new Date();
  /** Projected TZ overlay paths. Deliberately NOT @state: they are
   *  computed inside render() (from tzData/tzIanaData + centerLon)
   *  and read in the same pass. Making them reactive caused Lit to
   *  schedule a second full update cycle every time they were
   *  rebuilt ("update after update completed"), doubling the most
   *  expensive render path. The async data loads call
   *  requestUpdate() themselves, so reactivity here adds nothing. */
  private tzPolygons: TzPolygon[] | null = null;
  private tzIanaPolygons: IanaPolygon[] | null = null;
  /** centerLon used the last time we built the TZ overlay paths.
   *  Re-projection is quantized: in sun mode centerLon drifts
   *  ~0.044° every map tick, and rebuilding 419 polygons (~1 MB of
   *  path data) for a sub-pixel shift caused a periodic jank spike.
   *  We rebuild only when the drift exceeds TZ_REBUILD_DEG and
   *  absorb the residue with a group translate (see render()). */
  private tzPolygonsCenterLon: number | null = null;
  private tzData: Awaited<ReturnType<typeof loadTimezones>> | null = null;
  private tzIanaData: Awaited<ReturnType<typeof loadIanaTimezones>> | null = null;
  private ianaTzCache = new Map<string, string | null>();
  @state() private hoveredIana: IanaPolygon | null = null;
  @state() private hoveredOffset: TzPolygon | null = null;
  @state() private hoveredMarker: ResolvedMarker | null = null;
  @state() private hoverPos: { x: number; y: number } | null = null;

  /** Memoized terminator geometry. The tiled night polygon is
   *  ~1,085 vertices and the two SVG points strings total ~30 KB;
   *  their only inputs are mapNow (advances every ~10 s) and
   *  centerLon — but render() runs at 1 Hz for the clock readout
   *  and on every hover-state change. Rebuilding per render was
   *  the single biggest steady-state CPU cost in the card. */
  private terminatorCache: {
    mapNowMs: number;
    centerLon: number;
    points: string;
    curvePoints: string;
  } | null = null;

  /** Pending hover position + rAF handle for the coalescer in
   *  updateHoverPos(). */
  private hoverPosPending: { x: number; y: number } | null = null;
  private hoverPosRaf = 0;

  private config?: ResolvedConfig;
  private timer?: ReturnType<typeof setInterval>;
  /** Combined "the card is visible right now" signal: viewport
   *  intersection AND the document's tab visibility. When false we
   *  switch the timer to a 30-minute cadence. */
  private isCardVisible = true;
  private intersecting = true;
  private intersectionObserver?: IntersectionObserver;
  private onTabVisibility?: () => void;

  static override styles = css`
    :host {
      display: block;
      background: var(--ha-card-background, var(--card-background-color, #111));
      border-radius: var(--ha-card-border-radius, 12px);
      overflow: hidden;
      color: var(--primary-text-color, #fff);
      --geo-tz-bg: rgba(8, 14, 28, 0.85);
      --geo-tz-hour: #d8e2f0;
      --geo-tz-noon: #ffd866;
      --geo-tz-mid: #6ab0ff;
      --geo-tz-tick: rgba(255, 255, 255, 0.35);
      --geo-tz-line: rgba(255, 255, 255, 0.18);
      --geo-tz-line-width: 1;
      --geo-home-marker: var(--accent-color, #ff7a3d);
      --geo-marker-color: #3da9fc;
      --geo-day-brightness: 1.15;
      --geo-night-contrast: 1;
      --geo-twilight-color: #463701;
      --geo-twilight-opacity: 0.26;
    }
    .day-image {
      filter: brightness(var(--geo-day-brightness));
    }
    .night-image {
      filter: contrast(var(--geo-night-contrast));
    }
    /* Warm sunrise/sunset glow stroked along the terminator great
       circle. Blurred + screen-blended so it brightens the day side
       without dimming the night side. */
    .twilight-glow {
      fill: none;
      stroke: var(--geo-twilight-color);
      stroke-linecap: round;
      stroke-linejoin: round;
      opacity: var(--geo-twilight-opacity);
      mix-blend-mode: screen;
      pointer-events: none;
    }
    .frame {
      position: relative;
      width: 100%;
    }
    svg {
      display: block;
      width: 100%;
      height: 100%;
    }
    .readout {
      position: absolute;
      bottom: 10px;
      left: 14px;
      font-family: var(--paper-font-headline_-_font-family, system-ui, sans-serif);
      text-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
      line-height: 1.15;
    }
    .local-time {
      font-size: clamp(1rem, 2.4vw, 1.7rem);
      font-weight: 500;
    }
    .utc-time {
      font-size: clamp(0.75rem, 1.4vw, 1rem);
      color: #ffd866;
      opacity: 0.92;
    }
    .date {
      position: absolute;
      bottom: 10px;
      right: 14px;
      font-family: var(--paper-font-headline_-_font-family, system-ui, sans-serif);
      text-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
      font-size: clamp(0.85rem, 1.6vw, 1.15rem);
    }

    /* Hour band */
    .tz-bg {
      fill: var(--geo-tz-bg);
    }
    .tz-hour {
      fill: var(--geo-tz-hour);
      font-family: var(--paper-font-headline_-_font-family, system-ui, sans-serif);
      font-weight: 500;
      font-size: 26px;
    }
    .tz-hour.noon {
      fill: var(--geo-tz-noon);
      font-weight: 700;
    }
    .tz-hour.mid {
      fill: var(--geo-tz-mid);
      font-weight: 600;
    }
    .tz-tick {
      stroke: var(--geo-tz-tick);
      stroke-width: 1;
    }

    /* Time-zone boundary overlay — visible offset boundaries with a
       transparent fill so the polygon interior is hit-testable.
       Renders BELOW the IANA layer; IANA captures hover where it
       has coverage (land), and we fall back to this layer's hover
       in the gaps (open ocean, polar strips). */
    .tz-region {
      fill: rgba(255, 255, 255, 0);
      stroke: var(--geo-tz-line);
      stroke-width: var(--geo-tz-line-width);
      stroke-linejoin: round;
      stroke-linecap: round;
      pointer-events: visiblePainted;
      cursor: default;
      transition: fill 120ms ease;
    }
    .tz-region:hover {
      fill: rgba(255, 255, 255, 0.05);
    }
    /* Bands shown as pure chrome (showTimezoneRegions on, hover/popup
       off): no hit-testing, no hover tint. This compound selector
       outranks the bare .tz-region pointer-events rule above, which a
       presentation attribute alone would NOT (CSS beats attributes). */
    .tz-region.is-inert {
      pointer-events: none;
    }
    .tz-region.is-inert:hover {
      fill: rgba(255, 255, 255, 0);
    }
    /* Invisible IANA hit-test layer — tagged with each region's IANA
       tzid so the popup can ask Intl.DateTimeFormat for DST-aware
       local time. Faint tint on hover gives visual feedback that
       the user is over an interactive region. */
    .tz-iana-region {
      fill: rgba(255, 255, 255, 0);
      stroke: rgba(255, 255, 255, 0);
      stroke-width: 0;
      pointer-events: visiblePainted;
      cursor: default;
      transition: fill 120ms ease, stroke 120ms ease, stroke-width 120ms ease;
    }
    .tz-iana-region:hover,
    .tz-iana-region.is-active {
      fill: rgba(255, 255, 255, 0.08);
      stroke: rgba(255, 255, 255, 0.65);
      stroke-width: 1.5;
    }
    /* Home marker — overlay sibling of the SVG, same shape/CSS as
       a regular marker but coloured via the home-specific theme
       variable so users can restyle without touching card config.
       The selector specificity (.home-marker .marker-halo /
       .marker-dot) beats the bare .marker-halo / .marker-dot rules
       above, so the home marker uses --geo-home-marker rather than
       --geo-marker-color. The dot is non-interactive (no popup);
       the label is rendered inline when showHomeMarkerLabel is true. */
    .home-marker .marker-halo,
    .home-marker .marker-dot {
      background: var(--geo-home-marker);
    }
    .home-marker .marker-dot {
      pointer-events: none;
      cursor: default;
    }
    /* User-configured location markers. Rendered as HTML overlay
       (not SVG) so their dot, halo, and label keep a constant CSS
       pixel size regardless of the card's rendered width — SVG
       <text> and circle radii live in viewBox units and shrink
       linearly with the card, which made labels illegible at any
       size below full-screen. The marker container itself is
       positioned in percent (so it tracks the map's drift) but
       its children are sized in px. */
    .marker {
      position: absolute;
      width: 0;
      height: 0;
      pointer-events: none;
      z-index: 3;
    }
    .marker-halo {
      position: absolute;
      width: 36px;
      height: 36px;
      left: -18px;
      top: -18px;
      border-radius: 50%;
      opacity: 0.22;
      pointer-events: none;
      /* Default fill — themes override via --geo-marker-color, and
         per-marker overrides via inline style still win because the
         element-level style attribute beats a host-scope variable. */
      background: var(--geo-marker-color);
    }
    .marker-dot {
      position: absolute;
      width: 14px;
      height: 14px;
      left: -7px;
      top: -7px;
      border-radius: 50%;
      border: 1.2px solid rgba(0, 0, 0, 0.7);
      box-sizing: border-box;
      pointer-events: auto;
      cursor: default;
      transition: transform 120ms ease;
      background: var(--geo-marker-color);
    }
    .marker.is-active .marker-dot {
      transform: scale(1.3);
    }
    .marker-text {
      position: absolute;
      top: 9px;
      left: 0;
      transform: translateX(-50%);
      text-align: center;
      white-space: nowrap;
      pointer-events: none;
      font-family: var(--paper-font-headline_-_font-family, system-ui, sans-serif);
      /* Multi-direction shadow gives a readable outline against
         either bright daylight or dark city-lights imagery without
         the cost of a true SVG paint-order stroke. */
      text-shadow:
        0 1px 2px rgba(0, 0, 0, 0.95),
        0 0 3px rgba(0, 0, 0, 0.85),
        0 0 6px rgba(0, 0, 0, 0.6);
      color: #fff;
    }
    .marker-label {
      font-size: 13px;
      font-weight: 600;
      line-height: 1.15;
    }
    .marker-time {
      font-size: 12px;
      font-weight: 500;
      font-variant-numeric: tabular-nums;
      letter-spacing: 0.02em;
      line-height: 1.15;
      margin-top: 1px;
    }
    /* Custom popup. Positioned via inline transform from JS so it
       follows the cursor; ignores its own pointer events so it never
       steals hover from the underlying region. */
    .tz-popup {
      position: absolute;
      left: 0;
      top: 0;
      pointer-events: none;
      background: rgba(8, 14, 28, 0.92);
      color: var(--primary-text-color, #fff);
      border-radius: 8px;
      padding: 8px 12px;
      font-family: var(--paper-font-headline_-_font-family, system-ui, sans-serif);
      box-shadow: 0 4px 18px rgba(0, 0, 0, 0.55);
      max-width: 280px;
      z-index: 5;
    }
    .tz-popup-time {
      font-size: 1.15rem;
      font-weight: 600;
      font-variant-numeric: tabular-nums;
      letter-spacing: 0.02em;
    }
    .tz-popup-date {
      font-size: 0.78rem;
      opacity: 0.78;
      margin-top: 1px;
    }
    .tz-popup-name {
      font-size: 0.9rem;
      color: #ffd866;
      font-weight: 600;
      margin-top: 2px;
    }
    .tz-popup-city {
      font-size: 0.82rem;
      opacity: 0.92;
      margin-top: 1px;
    }
    .tz-popup-offset {
      font-size: 0.72rem;
      opacity: 0.62;
      margin-top: 4px;
      font-variant-numeric: tabular-nums;
    }
    .tz-popup-places {
      font-size: 0.72rem;
      opacity: 0.62;
      margin-top: 3px;
      line-height: 1.3;
    }
  `;

  setConfig(config: GeoClockCardConfig): void {
    if (!config) {
      throw new Error('geo-clock-card: missing config');
    }
    const base = sanitizeImageryBase(config.imageryBase)
      ?? new URL('.', import.meta.url).href;
    const frozenNow = parseFrozenNow(config.now);
    this.config = {
      twilightDegrees: clamp(config.twilightDegrees ?? 8, 1, 18),
      updateInterval: clamp(config.updateInterval ?? 1, 1, 600),
      showUTC: config.showUTC ?? true,
      showTimezoneBand: config.showTimezoneBand ?? true,
      showTimezoneBoundaries: config.showTimezoneBoundaries ?? true,
      // Vertical offset bands default to the boundaries flag so existing
      // configs (and the HA editor, which only exposes boundaries) behave
      // exactly as before. The web demo sets it independently to group the
      // bands with the hour band.
      showTimezoneRegions:
        config.showTimezoneRegions ?? config.showTimezoneBoundaries ?? true,
      showTimezonePopup: config.showTimezonePopup ?? true,
      timezoneLineColor:
        sanitizeCssColor(config.timezoneLineColor) ??
        'rgba(255, 255, 255, 0.18)',
      dayBrightness: clamp(config.dayBrightness ?? 1.15, 0, 5),
      nightContrast: clamp(config.nightContrast ?? 1, 0, 5),
      twilightColor: sanitizeCssColor(config.twilightColor) ?? '#463701',
      twilightOpacity: clamp(config.twilightOpacity ?? 0.26, 0, 1),
      imageryBase: base.endsWith('/') ? base : base + '/',
      center: config.center ?? 'sun',
      centerLongitude:
        typeof config.centerLongitude === 'number'
          ? clamp(config.centerLongitude, -180, 180)
          : undefined,
      centerEntity: config.centerEntity,
      showHomeMarker: config.showHomeMarker ?? false,
      showHomeMarkerLabel: config.showHomeMarkerLabel ?? false,
      markers: sanitizeMarkers(config.markers),
      markerLabelMode:
        config.markerLabelMode === 'hover' ? 'hover' : 'always',
      // markerColor stays undefined when the user hasn't explicitly
      // set it so `--geo-marker-color` is the true default. The
      // sanitiser drops anything that isn't a recognised CSS color.
      markerColor: sanitizeCssColor(config.markerColor),
      // Card-level day/night defaults. Both undefined unless the
      // user sets them — that's what keeps day/night mode opt-in so
      // existing single-color cards don't change.
      markerDayColor: sanitizeCssColor(config.markerDayColor),
      markerNightColor: sanitizeCssColor(config.markerNightColor),
      markerShowDay: config.markerShowDay ?? true,
      mainTimeSource: pickMainTimeSource(config.mainTimeSource),
      mainTimeEntity: config.mainTimeEntity,
      // Empty string would make Intl throw a RangeError, so coerce it
      // (and any falsy) to undefined → browser/runtime default locale.
      locale: config.locale || undefined,
      frozenNow,
    };
    // Pin or release the clocks based on the frozen setting.
    const seed = frozenNow ?? new Date();
    this.displayNow = seed;
    this.mapNow = seed;
    this.ianaTzCache.clear();
    // New config might change centerLon → invalidate cached paths.
    this.tzPolygons = null;
    this.tzIanaPolygons = null;
    this.tzPolygonsCenterLon = null;
    this.restartTimer();
    this.maybeLoadTimezones();
    this.maybeLoadIanaTimezones();
  }

  override connectedCallback(): void {
    super.connectedCallback();
    if (!this.config?.frozenNow) {
      const now = new Date();
      this.displayNow = now;
      this.mapNow = now;
    }
    this.attachVisibilityObservers();
    this.restartTimer();
    this.maybeLoadTimezones();
    this.maybeLoadIanaTimezones();
  }

  override disconnectedCallback(): void {
    super.disconnectedCallback();
    this.stopTimer();
    this.clearDismissTimer();
    this.clearIdleTimer();
    this.detachVisibilityObservers();
    if (this.hoverPosRaf) {
      cancelAnimationFrame(this.hoverPosRaf);
      this.hoverPosRaf = 0;
    }
  }

  /** Track whether this card is on-screen and the tab is foregrounded.
   *  Either signal turning off cuts updates to a 30-minute cadence. */
  private attachVisibilityObservers(): void {
    if (typeof IntersectionObserver !== 'undefined' && !this.intersectionObserver) {
      this.intersectionObserver = new IntersectionObserver(
        (entries) => {
          const e = entries[entries.length - 1];
          this.intersecting = e ? e.isIntersecting : true;
          this.recomputeVisibility();
        },
        { threshold: 0 },
      );
      this.intersectionObserver.observe(this);
    }
    if (typeof document !== 'undefined' && !this.onTabVisibility) {
      this.onTabVisibility = () => this.recomputeVisibility();
      document.addEventListener('visibilitychange', this.onTabVisibility);
    }
  }

  private detachVisibilityObservers(): void {
    this.intersectionObserver?.disconnect();
    this.intersectionObserver = undefined;
    if (this.onTabVisibility && typeof document !== 'undefined') {
      document.removeEventListener('visibilitychange', this.onTabVisibility);
    }
    this.onTabVisibility = undefined;
  }

  private recomputeVisibility(): void {
    const tabVisible =
      typeof document === 'undefined' ||
      document.visibilityState !== 'hidden';
    const visible = this.intersecting && tabVisible;
    if (visible === this.isCardVisible) return;
    this.isCardVisible = visible;
    if (visible) {
      // Snap clocks forward to "now" so the user doesn't see a stale
      // readout while the timer is restarting at fast cadence.
      const now = new Date();
      this.displayNow = now;
      this.mapNow = now;
    }
    this.restartTimer();
  }

  private restartTimer(): void {
    this.stopTimer();
    if (!this.config || !this.isConnected) return;
    if (this.config.frozenNow) return; // frozen clock — no timer
    const intervalMs = this.isCardVisible
      ? this.config.updateInterval * 1000
      : HIDDEN_INTERVAL_MS;
    this.timer = setInterval(() => this.tick(), intervalMs);
  }

  private tick(): void {
    const now = new Date();
    this.displayNow = now;
    if (now.getTime() - this.mapNow.getTime() >= MAP_UPDATE_INTERVAL_MS) {
      this.mapNow = now;
    }
  }

  private stopTimer(): void {
    if (this.timer !== undefined) {
      clearInterval(this.timer);
      this.timer = undefined;
    }
  }

  private maybeLoadTimezones(): void {
    // tzData feeds the vertical offset bands, gated on showTimezoneRegions
    // (the IANA hover layer loads separately in maybeLoadIanaTimezones).
    if (!this.config?.showTimezoneRegions || this.tzData !== null) return;
    const url = this.config.imageryBase + TZ_DATA;
    loadTimezones(url)
      .then((data) => {
        this.tzData = data;
        // Force re-render so the overlay path gets built with the
        // current centerLon.
        this.requestUpdate();
      })
      .catch((err) => {
        // Don't fail the card if the file is missing — log and move on
        // with a bare map. Common during dev before the asset is built.
        console.warn('geo-clock-card: timezone overlay failed to load:', err);
      });
  }

  private maybeLoadIanaTimezones(): void {
    if (!this.config || this.tzIanaData !== null) return;
    // We need IANA data for: (a) the on-map polygon overlay, (b)
    // resolving tzid for any configured marker, (c) resolving tzid
    // for `mainTimeSource: 'entity'`, and (d) the home tzid lookup
    // when HA hasn't reported a `time_zone` config. Skip the fetch
    // only when none of these apply.
    const needForMarkers = this.config.markers.length > 0;
    const needForEntityClock = this.config.mainTimeSource === 'entity';
    const needForHomeClock =
      this.config.mainTimeSource === 'home' &&
      typeof this.hass?.config?.time_zone !== 'string';
    if (
      !this.config.showTimezoneBoundaries &&
      !needForMarkers &&
      !needForEntityClock &&
      !needForHomeClock
    ) {
      return;
    }
    const url = this.config.imageryBase + TZ_IANA_DATA;
    loadIanaTimezones(url)
      .then((data) => {
        this.tzIanaData = data;
        this.ianaTzCache.clear();
        this.requestUpdate();
      })
      .catch((err) => {
        // Same fallback as the offset layer: skip silently if the
        // file isn't there. The offset layer alone still works.
        console.warn(
          'geo-clock-card: IANA timezone overlay failed to load:',
          err,
        );
      });
  }

  /** Used for fallbacks below — Greenwich rather than subsolar so a
   *  misconfigured non-sun mode looks visibly different from sun. */
  private static readonly FALLBACK_CENTER_LON = 0;
  private warnedFallback = '';

  /**
   * Resolve the longitude (degrees, signed) that should appear at the
   * center of the map. Driven by mapNow — for 'sun' mode this means
   * the map shifts only when the subsolar longitude has moved enough
   * to be visible (≥0.5 px at 4K).
   *
   * Modes that need data which isn't available (no HA longitude,
   * entity missing, centerLongitude unset) fall back to GREENWICH
   * (lon=0), not subsolar — that way a broken `home` config doesn't
   * look identical to `sun` mode and the user sees their selection
   * registered. A console warning is emitted so the cause is visible
   * in DevTools.
   */
  private resolveCenterLon(mapNow: Date): number {
    if (!this.config) return subsolarPoint(mapNow).lon;
    switch (this.config.center) {
      case 'home': {
        const lon = this.hass?.config?.longitude;
        if (typeof lon === 'number') return lon;
        this.warnFallback(
          'home',
          'hass.config.longitude is not set; falling back to Greenwich (0°)',
        );
        return GeoClockCard.FALLBACK_CENTER_LON;
      }
      case 'longitude':
        if (typeof this.config.centerLongitude === 'number') {
          return this.config.centerLongitude;
        }
        this.warnFallback(
          'longitude',
          'centerLongitude not set; falling back to Greenwich (0°)',
        );
        return GeoClockCard.FALLBACK_CENTER_LON;
      case 'entity': {
        const id = this.config.centerEntity;
        const state = id ? this.hass?.states?.[id] : undefined;
        const lon = state?.attributes?.longitude;
        if (typeof lon === 'number') return lon;
        this.warnFallback(
          'entity',
          id
            ? `entity '${id}' has no numeric longitude attribute; falling back to Greenwich (0°)`
            : 'centerEntity not set; falling back to Greenwich (0°)',
        );
        return GeoClockCard.FALLBACK_CENTER_LON;
      }
      case 'sun':
      default:
        return subsolarPoint(mapNow).lon;
    }
  }

  /** De-duped console warning per (mode, message) so we don't spam
   *  the console with the same warning every render. */
  private warnFallback(mode: string, message: string): void {
    const key = `${mode}|${message}`;
    if (this.warnedFallback === key) return;
    this.warnedFallback = key;
    console.warn(`geo-clock-card: center mode '${mode}' — ${message}`);
  }

  /** Returns (lat, lon) for the home marker, or null if we have no
   *  HA-configured location. Always reads from hass.config — the
   *  marker represents the user's actual home regardless of the
   *  map's centering mode. */
  private resolveHomeLatLon(): { lat: number; lon: number } | null {
    const lat = this.hass?.config?.latitude;
    const lon = this.hass?.config?.longitude;
    if (typeof lat !== 'number' || typeof lon !== 'number') return null;
    return { lat, lon };
  }

  private lookupIanaTz(lat: number, lon: number): string | null {
    if (!this.tzIanaData) return null;
    // 2-decimal key (~1 km grid) — far finer than the 1%-simplified
    // polygon boundaries we hit-test against, and it keeps a moving
    // device_tracker from minting a fresh cache entry on every
    // position report. The size cap guards always-on dashboards
    // tracking many movers: 4-decimal keys grew the map unboundedly.
    const key = `${lat.toFixed(2)},${lon.toFixed(2)}`;
    let val = this.ianaTzCache.get(key);
    if (val === undefined) {
      val = findIanaZoneForLatLon(this.tzIanaData, lat, lon);
      if (this.ianaTzCache.size >= 512) this.ianaTzCache.clear();
      this.ianaTzCache.set(key, val);
    }
    return val;
  }

  /**
   * Resolve the IANA tzid the main clock readout should use, based on
   * `mainTimeSource`. Returns undefined to mean "use the browser's
   * default zone" — that's also the fallback whenever a configured
   * source can't be resolved (e.g. entity missing, IANA data still
   * loading).
   */
  private resolveMainTimezone(): string | undefined {
    if (!this.config) return undefined;
    switch (this.config.mainTimeSource) {
      case 'device':
        return undefined;
      case 'home': {
        // HA almost always exposes its own zone via config.time_zone,
        // and using that directly avoids an unnecessary polygon
        // lookup. Only fall through to the polygon hit-test when the
        // attribute is missing (rare).
        const tz = this.hass?.config?.time_zone;
        if (typeof tz === 'string' && tz) return tz;
        const home = this.resolveHomeLatLon();
        if (home && this.tzIanaData) {
          return (
            this.lookupIanaTz(home.lat, home.lon) ??
            undefined
          );
        }
        return undefined;
      }
      case 'entity': {
        const id = this.config.mainTimeEntity;
        const state = id ? this.hass?.states?.[id] : undefined;
        const lat = state?.attributes?.latitude;
        const lon = state?.attributes?.longitude;
        if (
          typeof lat === 'number' &&
          typeof lon === 'number' &&
          this.tzIanaData
        ) {
          return (
            this.lookupIanaTz(lat, lon) ?? undefined
          );
        }
        return undefined;
      }
    }
  }

  /**
   * Walk the configured markers, resolving each one's entity to a
   * (lat, lon, tzid) triple. Markers whose entity is missing or has
   * no numeric lat/lon are silently dropped so a stale config doesn't
   * crash the render. The tzid is null until the IANA dataset has
   * loaded — in that interim case we still render the dot, just with
   * no time line.
   */
  private resolveMarkers(): ResolvedMarker[] {
    if (!this.config || this.config.markers.length === 0) return [];
    const out: ResolvedMarker[] = [];
    for (const m of this.config.markers) {
      const state = this.hass?.states?.[m.entity];
      if (!state) continue;
      const lat = state.attributes?.latitude;
      const lon = state.attributes?.longitude;
      if (typeof lat !== 'number' || typeof lon !== 'number') continue;
      const friendly =
        typeof state.attributes?.friendly_name === 'string'
          ? (state.attributes.friendly_name as string)
          : m.entity;
      const label =
        (typeof m.label === 'string' && m.label.trim()) || friendly;
      const tzid = this.lookupIanaTz(lat, lon);
      out.push({
        entity: m.entity,
        label,
        // Per-marker > card-level > undefined (CSS variable wins).
        // sanitizeCssColor returns undefined for anything that doesn't
        // match the safe-color regex, so a malicious entry can't slip
        // a `; url(...)` into the inline style.
        color: sanitizeCssColor(m.color) ?? this.config.markerColor,
        // Same precedence for the day/night colors. When either
        // resolves, the renderer switches this marker to day/night
        // mode (picking by sun elevation at its lat/lon).
        dayColor:
          sanitizeCssColor(m.dayColor) ?? this.config.markerDayColor,
        nightColor:
          sanitizeCssColor(m.nightColor) ?? this.config.markerNightColor,
        lat,
        lon,
        tzid,
      });
    }
    return out;
  }

  /**
   * Terminator geometry as SVG points strings, tiled across
   * x = [-MAP_W, 2·MAP_W] and memoized on (mapNow, centerLon).
   *
   * Why tiled: the day/night image pair is drawn at offsetPx and
   * offsetPx-MAP_W, so when the SVG element is letterboxed inside a
   * viewport wider than the viewBox aspect (21:9 ultrawides) map
   * content lands in the side bars — and the night region + dusk rim
   * must follow it there. One merged polygon (rather than three
   * separately-feathered copies) keeps the feather filter from
   * rendering visible vertical fade edges at the wrap seams: the
   * polygon's only vertical closing edges sit at x=-MAP_W and
   * x=+2·MAP_W, well outside the viewBox. Same for the polyline:
   * one continuous stroke means no per-segment round-caps at seams.
   *
   * Why memoized: the inputs change every ~10 s (mapNow tick) or on
   * a center change, but render() runs at 1 Hz plus on every hover
   * update. Rebuilding ~1,085 vertices + ~30 KB of points strings
   * per render was pure waste.
   */
  private terminatorGeometry(
    mapNow: Date,
    centerLon: number,
  ): { points: string; curvePoints: string } {
    const mapNowMs = mapNow.getTime();
    const cached = this.terminatorCache;
    if (
      cached &&
      cached.mapNowMs === mapNowMs &&
      cached.centerLon === centerLon
    ) {
      return cached;
    }

    const sub = subsolarPoint(mapNow);
    const curve = terminatorCurve(sub, { centerLon });
    // Dark-pole latitude, mirroring terminatorPolygon's declination
    // clamp: a clamped declination is always the same sign as
    // sub.lat (>= 0 maps to +MIN_ABS_DECL), so the dark pole is
    // south for northern declinations and vice versa. Computing it
    // directly avoids re-running the whole 361-point curve a second
    // time via terminatorPolygon just to read its last vertex.
    const darkPoleLat = sub.lat >= 0 ? -90 : 90;

    // terminatorCurve emits lonE ∈ [0, 360] INCLUSIVE, so naive
    // concatenation would duplicate the seam vertex (left copy's
    // lonE=360-360=0 followed by center copy's lonE=0). Slice the
    // closing vertex off the non-final copies so the tiled arrays
    // stay strictly monotonic in x.
    const open = curve.slice(0, -1);
    // Twilight polyline: full ±1 tile so the dusk rim runs
    // continuously through the letterbox bars (strokes have no
    // mask interactions; this has been solid in practice).
    const tiledCurve = [
      ...open.map(([lonE, lat]) => [lonE - 360, lat] as const),
      ...open,
      ...curve.map(([lonE, lat]) => [lonE + 360, lat] as const),
    ];
    // Night polygon: small overhang (lonE -45..405, ≈±256 px).
    // The night-mask region is exactly one viewport wide
    // (x ∈ [0, MAP_W]) and the bars are covered by <use> copies
    // of the whole masked night unit — so the polygon only needs
    // to overhang far enough that the feather blur (3σ ≤ ~77 px
    // at the max twilight setting) never samples its vertical
    // closing edges from inside the region. Keep the overhang
    // SMALL: WebKit silently clips filtered mask content to
    // roughly one viewport's width measured from the geometry's
    // left edge, so every extra degree of overhang is a degree
    // of night lost on the right side of the map. (A 3-tile
    // polygon lost a third of the night layer; a half-world
    // overhang still lost the right ~quarter.)
    const OVERHANG_DEG = 45;
    const tiledPolyVertices: [number, number][] = [
      ...open.slice(open.length - OVERHANG_DEG).map(
        ([lonE, lat]) => [lonE - 360, lat] as [number, number],
      ),
      ...open.map(([lonE, lat]) => [lonE, lat] as [number, number]),
      ...curve.slice(0, OVERHANG_DEG + 1).map(
        ([lonE, lat]) => [lonE + 360, lat] as [number, number],
      ),
      [360 + OVERHANG_DEG, darkPoleLat],
      [-OVERHANG_DEG, darkPoleLat],
    ];

    const next = {
      mapNowMs,
      centerLon,
      points: polygonToSvgPoints(tiledPolyVertices, MAP_W, MAP_H),
      curvePoints: polygonToSvgPoints(tiledCurve, MAP_W, MAP_H),
    };
    this.terminatorCache = next;
    return next;
  }

  override render(): TemplateResult {
    if (!this.config) return html``;

    // Two clocks: mapNow drives anything tied to the planet's
    // orientation (terminator, imagery, hour band, TZ overlay path);
    // displayNow drives the readout. When `frozenNow` is set both
    // collapse to the same value.
    const mapNow = this.config.frozenNow ?? this.mapNow;
    const displayNow = this.config.frozenNow ?? this.displayNow;

    const centerLon = this.resolveCenterLon(mapNow);
    // Subsolar point for this frame — drives day/night marker color
    // selection. Computed from mapNow so a marker flips exactly as
    // the rendered terminator (also mapNow-based) sweeps over it.
    const sub = subsolarPoint(mapNow);
    const { points, curvePoints } = this.terminatorGeometry(
      mapNow,
      centerLon,
    );

    // Twilight band → Gaussian σ in image-pixel space. Total fade
    // ≈ 8σ end-to-end; mapping elevation degrees → arc degrees → px
    // via the lat axis scale.
    const fadePxFull = (this.config.twilightDegrees * 2 * MAP_H) / 180;
    const sigma = Math.max(0.5, fadePxFull / 8);
    // Twilight glow polyline: thick stroke at the curve, then
    // softened with a smaller Gaussian. Together they paint a warm
    // band roughly the same width as the night-mask fade, but
    // additive (screen-blended) instead of subtractive — that's what
    // gives the terminator an atmospheric "rim of dusk" look.
    const glowStrokeWidth = Math.max(4, fadePxFull * 0.55);
    const glowBlurSigma = Math.max(1, fadePxFull / 5);

    const dayHref = this.config.imageryBase + dayImageForDate(mapNow);
    const nightHref = this.config.imageryBase + NIGHT_IMAGE;

    // Imagery offset for the configured centerLon. The source JPEGs
    // are Greenwich-centered (lon=0 at source x=W/2). We render the
    // source at output x = offsetPx and again at offsetPx − W so the
    // wraparound is covered by exactly two <image> tags. Both share
    // an href so the browser issues one HTTP request per layer.
    const offsetPx = (((-centerLon / 360) * MAP_W) % MAP_W + MAP_W) % MAP_W;

    // (Re)project overlays when the centerLon has drifted past the
    // rebuild threshold OR a layer exists in data form but hasn't
    // been projected yet (the async fetch usually arrives after the
    // first render). Sub-threshold drift is absorbed by translating
    // the layer groups by tzDriftPx instead of re-projecting — see
    // TZ_REBUILD_DEG. Late-arriving layers are built at the lon the
    // earlier layer was recorded against so both stay aligned with
    // each other and with the shared drift translate.
    let tzDriftPx = 0;
    // Project whenever either layer is shown: the bands key on
    // showTimezoneRegions, the IANA hover layer on showTimezoneBoundaries.
    if (this.config.showTimezoneRegions || this.config.showTimezoneBoundaries) {
      const recorded = this.tzPolygonsCenterLon;
      const needsRebuild =
        recorded === null || Math.abs(recorded - centerLon) > TZ_REBUILD_DEG;
      const buildLon = needsRebuild ? centerLon : (recorded ?? centerLon);
      if (this.tzData && (needsRebuild || this.tzPolygons === null)) {
        this.tzPolygons = timezonesToPolygons(this.tzData, MAP_W, MAP_H, buildLon);
      }
      if (this.tzIanaData && (needsRebuild || this.tzIanaPolygons === null)) {
        this.tzIanaPolygons = sortByVisualArea(
          ianaToPolygons(this.tzIanaData, MAP_W, MAP_H, buildLon),
        );
      }
      this.tzPolygonsCenterLon = buildLon;
      // Paths were projected for buildLon; the map is at centerLon.
      // Increasing centerLon shifts map content left, so the
      // compensation is (buildLon − centerLon) in pixel space.
      tzDriftPx = ((buildLon - centerLon) / 360) * MAP_W;
    }

    const mainTz = this.resolveMainTimezone();
    const localTime = formatLocalTime(displayNow, mainTz, this.config.locale);
    const utcTime = formatUtcTime(displayNow);
    const dateStr = formatDate(displayNow, mainTz, this.config.locale);
    const markers = this.resolveMarkers();

    const showBand = this.config.showTimezoneBand;
    const yMin = showBand ? -BAND_H : 0;
    const totalH = showBand ? MAP_H + BAND_H : MAP_H;

    const frameStyle =
      `aspect-ratio: ${MAP_W} / ${totalH};` +
      // Numeric aspect ratio (unitless) so the web page's fullscreen
      // letterbox can size the frame to FIT the viewport — see
      // setCardFullBleed() in index.html. Updates with the band toggle
      // (totalH changes), so the letterbox stays exact either way.
      ` --geo-frame-ar: ${(MAP_W / totalH).toFixed(6)};` +
      ` --geo-day-brightness: ${this.config.dayBrightness};` +
      ` --geo-night-contrast: ${this.config.nightContrast};` +
      ` --geo-twilight-color: ${this.config.twilightColor};` +
      ` --geo-twilight-opacity: ${this.config.twilightOpacity};` +
      ` --geo-tz-line: ${this.config.timezoneLineColor};`;

    return html`
      <div class="frame" style="${frameStyle}">
        <svg
          viewBox="0 ${yMin} ${MAP_W} ${totalH}"
          preserveAspectRatio="xMidYMid slice"
          aria-label="World map with current day/night terminator"
        >
          <defs>
            <!-- objectBoundingBox percentages, NOT userSpaceOnUse:
                 WebKit rasterizes mask content per masked element,
                 and an explicit user-space filter region spanning
                 the full 3×MAP_W tile range made the mask resolve
                 to black for the second night-image tile — a hard
                 day/night edge at the image seam. Percentages of
                 the polygon's bbox (which always spans the full
                 tiled width and nearly full map height) sidestep
                 that and still leave 3σ headroom: 5% of 6144 px
                 horizontally and ~10% of ≥757 px vertically both
                 comfortably exceed 3σ at the max twilightDegrees
                 of 18 (σ ≈ 51 px). -->
            <filter
              id="feather"
              x="-5%"
              y="-10%"
              width="110%"
              height="120%"
              filterUnits="objectBoundingBox"
            >
              <feGaussianBlur stdDeviation="${sigma}" />
            </filter>
            <!-- Mask region is exactly ONE viewport (x 0..MAP_W):
                 WebKit silently drops mask content beyond roughly
                 a viewport's width, so the previous 3x-wide
                 region truncated the night layer with a hard
                 vertical edge at the image-tile boundary. The
                 polygon overhangs the region by half a world on
                 each side (see tiledPolyVertices) so the feather
                 blur never reaches its closing edges, and the
                 region's own hard clip at x=0/MAP_W is invisible
                 because adjacent <use> instances of the night
                 unit abut exactly there with periodic content. -->
            <mask
              id="night-mask"
              maskUnits="userSpaceOnUse"
              x="0"
              y="0"
              width="${MAP_W}"
              height="${MAP_H}"
            >
              <rect
                x="0" y="0"
                width="${MAP_W}" height="${MAP_H}"
                fill="black" />
              <!-- Three copies of the feathered night polygon at
                   ±MAP_W. WebKit clips each FILTERED mask element
                   to ~one viewport's width from the element's own
                   left edge (measured empirically: the night
                   layer always truncated at polygonLeft + MAP_W).
                   Tiling the polygon as separate copies means
                   each copy's clipped right tail is covered by
                   the next copy — and because every copy blurs
                   the SAME periodic geometry, the hand-off pixels
                   compute identical values, so no seam. -->
              <polygon id="night-poly" points="${points}" fill="white" filter="url(#feather)" />
              <use href="#night-poly" x="${-MAP_W}" />
              <use href="#night-poly" x="${MAP_W}" />
            </mask>
            <!-- Same objectBoundingBox rationale as #feather above.
                 The vertical margin is the one that was clipping:
                 the polyline's bbox height at solstice is ~757 px
                 and the glow needs 3σ + strokeWidth/2 ≈ 180 px at
                 twilightDegrees 18, so ±25% (~190 px) clears it.
                 Horizontally the bbox spans the full 6144 px tiled
                 width, so even 3% is over 180 px. -->
            <filter
              id="twilight-blur"
              x="-5%"
              y="-25%"
              width="110%"
              height="150%"
              filterUnits="objectBoundingBox"
            >
              <feGaussianBlur stdDeviation="${glowBlurSigma}" />
            </filter>
          </defs>

          <image class="day-image" href="${dayHref}"
                 x="${offsetPx - MAP_W}" y="0"
                 width="${MAP_W}" height="${MAP_H}"
                 preserveAspectRatio="none"/>
          <image class="day-image" href="${dayHref}"
                 x="${offsetPx}" y="0"
                 width="${MAP_W}" height="${MAP_H}"
                 preserveAspectRatio="none"/>
          <!-- The night unit: both wrap tiles of the night image
               under one mask whose region is a single viewport.
               Letterbox bars are covered by <use> copies of the
               whole unit — each instance carries its mask region
               along with it, so every copy is self-consistently
               masked and the seams at x=0/MAP_W are invisible
               (periodic content meets exactly). This sidesteps
               the WebKit wide-mask truncation described at the
               mask definition above. -->
          <g id="night-unit" mask="url(#night-mask)">
            <image class="night-image" href="${nightHref}"
                   x="${offsetPx - MAP_W}" y="0"
                   width="${MAP_W}" height="${MAP_H}"
                   preserveAspectRatio="none"/>
            <image class="night-image" href="${nightHref}"
                   x="${offsetPx}" y="0"
                   width="${MAP_W}" height="${MAP_H}"
                   preserveAspectRatio="none"/>
          </g>
          <use href="#night-unit" x="${-MAP_W}" pointer-events="none"/>
          <use href="#night-unit" x="${MAP_W}" pointer-events="none"/>

          <!-- Single tiled twilight-glow polyline. Points are
               pre-tiled at x = curve, curve-MAP_W, curve+MAP_W
               (see tiledCurve above) so the dusk rim is one
               continuous stroke across the wrap range — no
               per-segment round-caps creating jags at the
               seams, and the Gaussian-blur filter has a single
               bounding box to work against. -->
          <polyline class="twilight-glow"
                    points="${curvePoints}"
                    stroke-width="${glowStrokeWidth}"
                    filter="url(#twilight-blur)"/>

          <!-- Wrap-tile copies are <use> references to the central
               layer, not duplicated subtrees: one node per copy
               instead of ~419, no duplicated path data in the DOM,
               and the instances track the referenced subtree live
               (a hover highlight on the central copy mirrors into
               the wrap copies, which is correct — it IS the same
               zone). The outer translate absorbs sub-threshold
               centerLon drift (see tzDriftPx above). -->
          ${this.tzPolygons && this.config.showTimezoneRegions
            ? svg`
                <g transform="translate(${tzDriftPx} 0)">
                  <g id="tz-offset-layer">
                    ${this.tzPolygons.map((p) =>
                      // The bands carry their hover popup only when the
                      // hover/popup feature (showTimezoneBoundaries) is on.
                      // The demo can show the bands as pure chrome (band
                      // toggle) while the popup rides the timezone toggle.
                      // (Optional chain: TS can't narrow this.config inside
                      // this nested map closure even though render guards it.)
                      this.config?.showTimezoneBoundaries
                        ? svg`<path class="tz-region" d="${p.d}"
                                       @pointerenter=${(e: PointerEvent) => this.onOffsetEnter(e, p)}
                                       @pointermove=${this.onZoneMove}
                                       @pointerleave=${this.onOffsetLeave}/>`
                        : svg`<path class="tz-region is-inert" d="${p.d}"/>`,
                    )}
                  </g>
                  <use href="#tz-offset-layer" x="${-MAP_W}" pointer-events="none"/>
                  <use href="#tz-offset-layer" x="${MAP_W}" pointer-events="none"/>
                </g>
              `
            : ''}
          ${this.tzIanaPolygons && this.config.showTimezoneBoundaries
            ? svg`
                <g transform="translate(${tzDriftPx} 0)">
                  <g id="tz-iana-layer">
                    ${this.tzIanaPolygons.map(
                      (p) => svg`<path class="tz-iana-region${
                                        this.hoveredIana === p ? ' is-active' : ''
                                      }" d="${p.d}"
                                       @pointerenter=${(e: PointerEvent) => this.onIanaEnter(e, p)}
                                       @pointermove=${this.onZoneMove}
                                       @pointerleave=${this.onIanaLeave}/>`,
                    )}
                  </g>
                  <use href="#tz-iana-layer" x="${-MAP_W}" pointer-events="none"/>
                  <use href="#tz-iana-layer" x="${MAP_W}" pointer-events="none"/>
                </g>
              `
            : ''}

          ${showBand
            ? svg`
                <g id="hour-band">${timezoneBand(mapNow, MAP_W, centerLon)}</g>
                <use href="#hour-band" x="${-MAP_W}" pointer-events="none"/>
                <use href="#hour-band" x="${MAP_W}" pointer-events="none"/>
              `
            : ''}
        </svg>
        ${this.config.showHomeMarker
          ? this.renderHomeMarkerOverlay(
              displayNow,
              centerLon,
              yMin,
              totalH,
            )
          : ''}
        ${markers.length > 0
          ? this.renderMarkerOverlay(
              markers,
              displayNow,
              centerLon,
              yMin,
              totalH,
              sub,
            )
          : ''}
        <div class="readout">
          <div class="local-time">${localTime}</div>
          ${this.config.showUTC
            ? html`<div class="utc-time">${utcTime}</div>`
            : ''}
        </div>
        <div class="date">${dateStr}</div>
        ${this.renderPopup(displayNow)}
      </div>
    `;
  }

  getCardSize(): number {
    return 4;
  }

  /** HA Lovelace hook: returns an element instance for the visual
   *  card editor. Lazy-imported so the editor's HA-component
   *  dependencies don't bloat the runtime card bundle. */
  static async getConfigElement(): Promise<HTMLElement> {
    await import('./geo-clock-card-editor.js');
    return document.createElement('geo-clock-card-editor');
  }

  /** Returns a sensible default config for the card-picker preview. */
  static getStubConfig(): GeoClockCardConfig {
    return { type: 'custom:geo-clock-card', center: 'sun' };
  }

  /** Set when the user is touching the screen — the hover handlers
   *  use this to keep the popup visible after lift instead of
   *  dismissing immediately. */
  private dismissTimer?: ReturnType<typeof setTimeout>;
  private static readonly TOUCH_DISMISS_MS = 2500;

  // Mouse-idle auto-dismiss. A cursor parked over a zone never fires a
  // pointerleave, so a hover popup would otherwise stay up forever. We
  // re-arm this on every pointer move (via updateHoverPos) and clear the
  // popup after HOVER_IDLE_MS of stillness. Separate from dismissTimer
  // (touch) so the two can't clobber each other.
  private idleTimer?: ReturnType<typeof setTimeout>;
  private static readonly HOVER_IDLE_MS = 30_000;

  private clearDismissTimer(): void {
    if (this.dismissTimer !== undefined) {
      clearTimeout(this.dismissTimer);
      this.dismissTimer = undefined;
    }
  }

  private clearIdleTimer(): void {
    if (this.idleTimer !== undefined) {
      clearTimeout(this.idleTimer);
      this.idleTimer = undefined;
    }
  }

  private armIdleDismiss(): void {
    this.clearIdleTimer();
    this.idleTimer = setTimeout(() => {
      this.idleTimer = undefined;
      this.hoveredIana = null;
      this.hoveredOffset = null;
      this.hoveredMarker = null;
      this.hoverPos = null;
      // Cursor is still parked over the zone, so no pointerenter fires
      // until the user crosses into another zone (or leaves and returns),
      // at which point the popup reappears. That's the intended "moved
      // again → show again" behavior.
    }, GeoClockCard.HOVER_IDLE_MS);
  }

  private onIanaEnter = (e: PointerEvent, p: IanaPolygon): void => {
    this.clearDismissTimer();
    this.hoveredIana = p;
    this.updateHoverPos(e);
    if (e.pointerType === 'touch') this.armTouchAutoDismiss();
  };

  private onIanaLeave = (e: PointerEvent): void => {
    if (e.pointerType === 'touch') {
      this.scheduleTouchDismiss(() => {
        this.hoveredIana = null;
        if (!this.hoveredOffset && !this.hoveredMarker) {
          this.hoverPos = null;
        }
      });
      return;
    }
    this.hoveredIana = null;
    if (!this.hoveredOffset && !this.hoveredMarker) {
      this.hoverPos = null;
    }
  };

  private onOffsetEnter = (e: PointerEvent, p: TzPolygon): void => {
    this.clearDismissTimer();
    this.hoveredOffset = p;
    this.updateHoverPos(e);
    if (e.pointerType === 'touch') this.armTouchAutoDismiss();
  };

  private onOffsetLeave = (e: PointerEvent): void => {
    if (e.pointerType === 'touch') {
      this.scheduleTouchDismiss(() => {
        this.hoveredOffset = null;
        if (!this.hoveredIana && !this.hoveredMarker) {
          this.hoverPos = null;
        }
      });
      return;
    }
    this.hoveredOffset = null;
    if (!this.hoveredIana && !this.hoveredMarker) {
      this.hoverPos = null;
    }
  };

  private onZoneMove = (e: PointerEvent): void => {
    this.updateHoverPos(e);
  };

  private scheduleTouchDismiss(action: () => void): void {
    this.clearDismissTimer();
    this.dismissTimer = setTimeout(() => {
      this.dismissTimer = undefined;
      action();
    }, GeoClockCard.TOUCH_DISMISS_MS);
  }

  private updateHoverPos(e: MouseEvent): void {
    // Restart the mouse-idle dismiss on every move. Touch popups have
    // their own shorter dismiss path (armTouchAutoDismiss), so skip them.
    if ((e as PointerEvent).pointerType !== 'touch') this.armIdleDismiss();
    const frame = (e.currentTarget as Element).closest('.frame');
    if (!frame) return;
    const r = frame.getBoundingClientRect();
    this.hoverPosPending = { x: e.clientX - r.left, y: e.clientY - r.top };
    // Coalesce to at most one reactive write per animation frame.
    // pointermove fires at input-device rate (120+ Hz on ProMotion)
    // and hoverPos is @state, so a raw assignment scheduled a full
    // card render per move event — the popup only needs to track
    // the cursor at display refresh rate.
    if (this.hoverPosRaf) return;
    this.hoverPosRaf = requestAnimationFrame(() => {
      this.hoverPosRaf = 0;
      if (this.hoverPosPending) this.hoverPos = this.hoverPosPending;
    });
  }

  /** Render the HA-configured home as an HTML overlay sibling of the
   *  SVG. Same percentage-positioning trick as renderMarkerOverlay so
   *  the dot tracks the map's drift, but the dot, halo, and (optional)
   *  label + time stay at fixed CSS pixel size. The marker color
   *  comes from the existing `--geo-home-marker` CSS variable rather
   *  than a per-marker fill, preserving theme support.
   */
  private renderHomeMarkerOverlay(
    displayNow: Date,
    centerLon: number,
    yMin: number,
    totalH: number,
  ): TemplateResult | string {
    const home = this.resolveHomeLatLon();
    if (!home) return '';
    if (!this.config) return '';
    const { x, y } = latLonToPx(home.lat, home.lon, MAP_W, MAP_H, centerLon);
    const leftPct = (x / MAP_W) * 100;
    const topPct = ((y - yMin) / totalH) * 100;
    const showLabel = this.config.showHomeMarkerLabel;
    const tz = this.resolveHomeTimezone();
    const label =
      this.hass?.config?.location_name &&
      typeof this.hass.config.location_name === 'string'
        ? this.hass.config.location_name
        : 'Home';
    const time = tz
      ? formatMarkerTime(displayNow, tz, this.config.markerShowDay, this.config.locale)
      : '';
    return html`
      <div
        class="marker home-marker"
        style="left: ${leftPct}%; top: ${topPct}%;"
      >
        <div class="marker-halo"></div>
        <div class="marker-dot"></div>
        ${showLabel
          ? html`
              <div class="marker-text">
                <div class="marker-label">${label}</div>
                ${time
                  ? html`<div class="marker-time">${time}</div>`
                  : ''}
              </div>
            `
          : ''}
      </div>
    `;
  }

  /** Resolve the IANA tzid the HOME marker should use for its time
   *  display — same logic as the home branch of resolveMainTimezone
   *  but pulled out so the home marker can compute its time
   *  independently of `mainTimeSource`. */
  private resolveHomeTimezone(): string | undefined {
    const tz = this.hass?.config?.time_zone;
    if (typeof tz === 'string' && tz) return tz;
    const home = this.resolveHomeLatLon();
    if (home && this.tzIanaData) {
      return (
        this.lookupIanaTz(home.lat, home.lon) ??
        undefined
      );
    }
    return undefined;
  }

  /**
   * Render every configured marker as an HTML overlay sibling of the
   * SVG. We project the marker to viewBox pixel coords via
   * latLonToPx, then express the result as percentages of the
   * frame's total width/height so the overlay tracks the map as it
   * resizes — but the dot, halo, and label text are sized in CSS
   * pixels and stay legible at any card width. Hover hit-testing is
   * on the dot itself (the only child with pointer-events: auto),
   * matching the SVG behavior we replaced.
   */
  private renderMarkerOverlay(
    markers: ResolvedMarker[],
    displayNow: Date,
    centerLon: number,
    yMin: number,
    totalH: number,
    sub: SubsolarPoint,
  ) {
    if (!this.config) return '';
    const mode = this.config.markerLabelMode;
    return markers.map((m) => {
      const { x, y } = latLonToPx(m.lat, m.lon, MAP_W, MAP_H, centerLon);
      const leftPct = (x / MAP_W) * 100;
      const topPct = ((y - yMin) / totalH) * 100;
      const time = m.tzid
        ? formatMarkerTime(displayNow, m.tzid, this.config!.markerShowDay, this.config!.locale)
        : '';
      const isActive = this.hoveredMarker?.entity === m.entity;
      // Day/night color when either is set (recolors live as the
      // terminator passes), else the single `color`. When the final
      // fill is undefined we omit the inline background so the
      // `.marker-halo` / `.marker-dot` CSS rules fall through to
      // var(--geo-marker-color) — the theme-override path.
      const fill =
        pickDayNightColor(
          m.dayColor,
          m.nightColor,
          isDaylightAt(m.lat, m.lon, sub),
        ) ?? m.color;
      const fillStyle = fill ? `background: ${fill};` : '';
      return html`
        <div
          class="marker${isActive ? ' is-active' : ''}"
          style="left: ${leftPct}%; top: ${topPct}%;"
        >
          <div class="marker-halo" style=${fillStyle}></div>
          <div
            class="marker-dot"
            style=${fillStyle}
            @pointerenter=${(e: PointerEvent) => this.onMarkerEnter(e, m)}
            @pointermove=${this.onZoneMove}
            @pointerleave=${this.onMarkerLeave}
          ></div>
          ${mode === 'always'
            ? html`
                <div class="marker-text">
                  <div class="marker-label">${m.label}</div>
                  ${time
                    ? html`<div class="marker-time">${time}</div>`
                    : ''}
                </div>
              `
            : ''}
        </div>
      `;
    });
  }

  private onMarkerEnter = (e: PointerEvent, m: ResolvedMarker): void => {
    this.clearDismissTimer();
    this.hoveredMarker = m;
    this.updateHoverPos(e);
    if (e.pointerType === 'touch') this.armTouchAutoDismiss();
  };

  private onMarkerLeave = (e: PointerEvent): void => {
    if (e.pointerType === 'touch') {
      this.scheduleTouchDismiss(() => {
        this.hoveredMarker = null;
        if (!this.hoveredIana && !this.hoveredOffset) this.hoverPos = null;
      });
      return;
    }
    this.hoveredMarker = null;
    if (!this.hoveredIana && !this.hoveredOffset) this.hoverPos = null;
  };

  /**
   * Schedule a blanket popup-dismissal after TOUCH_DISMISS_MS. iOS
   * Safari (and several Android browsers) don't fire pointerleave
   * on tap-and-release, so the existing leave-handler dismissal
   * never runs on mobile and a popup gets stuck on-screen until
   * the user taps another region. Calling this on pointerenter
   * with pointerType 'touch' guarantees the popup will clear after
   * a readable interval regardless of whether leave ever fires.
   *
   * Tapping a different region calls clearDismissTimer via the next
   * onIanaEnter / onOffsetEnter / onMarkerEnter, so the new popup
   * gets its own fresh timer and the old one is cancelled.
   */
  private armTouchAutoDismiss(): void {
    this.scheduleTouchDismiss(() => {
      this.hoveredIana = null;
      this.hoveredOffset = null;
      this.hoveredMarker = null;
      this.hoverPos = null;
    });
  }

  private renderPopup(displayNow: Date): TemplateResult {
    if (!this.hoverPos) return html``;
    if (this.config?.showTimezonePopup === false) return html``;

    // Position the popup near the cursor:
    //  - horizontal: lower-right by default; flip to the left when
    //    past the canvas midline so it doesn't fall off the right edge.
    //  - vertical:   below the cursor by default; flip to ABOVE when
    //    the cursor is in the bottom half so the popup doesn't fall
    //    off the bottom edge of the card.
    // The vertical flip uses translateY(-100%) so we don't need to
    // measure the popup's actual height.
    const frame = this.shadowRoot?.querySelector('.frame') as HTMLElement | null;
    const w = frame?.clientWidth ?? 1280;
    const h = frame?.clientHeight ?? 720;
    const flipX = this.hoverPos.x > w * 0.55;
    const flipY = this.hoverPos.y > h * 0.5;
    const popupOffsetX = flipX ? -260 : 14;
    const popupOffsetY = flipY ? -14 : 14;
    const yShift = flipY ? ' translateY(-100%)' : '';
    const style =
      `transform: translate(${this.hoverPos.x + popupOffsetX}px, ` +
      `${this.hoverPos.y + popupOffsetY}px)${yShift};`;

    // Marker hover takes priority over both TZ layers — the user
    // explicitly placed the marker, so its label is the more
    // informative thing to show.
    if (this.hoveredMarker) {
      const m = this.hoveredMarker;
      if (m.tzid) {
        const live = zoneNow(displayNow, m.tzid, this.config?.locale);
        return html`
          <div class="tz-popup" style=${style}>
            <div class="tz-popup-time">${live.time}</div>
            <div class="tz-popup-date">${live.date}</div>
            <div class="tz-popup-name">${m.label}</div>
            <div class="tz-popup-offset">${live.offset} · ${m.tzid}</div>
          </div>
        `;
      }
      return html`
        <div class="tz-popup" style=${style}>
          <div class="tz-popup-name">${m.label}</div>
          <div class="tz-popup-offset">${m.entity}</div>
        </div>
      `;
    }
    // IANA hover takes priority — it's DST-aware and represents an
    // actual jurisdiction. Fall back to the offset overlay when the
    // cursor is over open ocean / Antarctica strips with no IANA
    // polygon coverage.
    if (this.hoveredIana) {
      const z = this.hoveredIana;
      const live = zoneNow(displayNow, z.tzid, this.config?.locale);
      return html`
        <div class="tz-popup" style=${style}>
          <div class="tz-popup-time">${live.time}</div>
          <div class="tz-popup-date">${live.date}</div>
          <div class="tz-popup-name">${live.name}</div>
          <div class="tz-popup-city">${z.cityLabel}</div>
          <div class="tz-popup-offset">${live.offset} · ${z.tzid}</div>
        </div>
      `;
    }
    if (this.hoveredOffset) {
      const z = this.hoveredOffset;
      const live = atOffset(displayNow, z.offset, this.config?.locale);
      return html`
        <div class="tz-popup" style=${style}>
          <div class="tz-popup-time">${live.time}</div>
          <div class="tz-popup-date">${live.date}</div>
          ${z.name
            ? html`<div class="tz-popup-name">${z.name}</div>`
            : ''}
          <div class="tz-popup-offset">${z.offsetLabel}</div>
          ${z.places
            ? html`<div class="tz-popup-places">${z.places}</div>`
            : ''}
        </div>
      `;
    }
    return html``;
  }
}

/** Locale-formatted time + date at a numeric UTC offset. Used for
 *  the offset popup branch (open ocean / Antarctic strips that have
 *  no IANA tzid). We shift UTC by the offset and feed the shifted
 *  Date into Intl with `timeZone: 'UTC'` so the runtime locale
 *  decides 24-hour vs AM/PM but no further zone math is applied. */
function atOffset(
  now: Date,
  offsetHours: number,
  locale?: string,
): { time: string; date: string } {
  const shifted = new Date(now.getTime() + offsetHours * 3_600_000);
  const time = new Intl.DateTimeFormat(locale, {
    timeZone: 'UTC',
    hour: 'numeric',
    minute: '2-digit',
    second: '2-digit',
  }).format(shifted);
  const date = new Intl.DateTimeFormat(locale, {
    timeZone: 'UTC',
    weekday: 'short',
    month: 'short',
    day: 'numeric',
  }).format(shifted);
  return { time, date };
}

function clamp(n: number, lo: number, hi: number): number {
  return Math.max(lo, Math.min(hi, n));
}

/**
 * Sort polygons by visual bounding-box area DESCENDING so that big
 * zones (Russia, Antarctica) render first and small ones (Bermuda,
 * Cayman, Vatican-style enclaves) render last. In SVG, later siblings
 * sit on top of earlier ones for hit-testing, so this gives small
 * islands hover priority over their continent-sized neighbors. We
 * estimate area cheaply by parsing the path's M/L coords for the
 * bounding box; full polygon area would require triangulation.
 */
function sortByVisualArea(polys: IanaPolygon[]): IanaPolygon[] {
  const area = (d: string): number => {
    let xMin = Infinity;
    let yMin = Infinity;
    let xMax = -Infinity;
    let yMax = -Infinity;
    // Match coord pairs that follow M or L commands.
    const re = /[ML]([\d.\-]+),([\d.\-]+)/g;
    let m;
    while ((m = re.exec(d))) {
      const x = parseFloat(m[1]);
      const y = parseFloat(m[2]);
      if (x < xMin) xMin = x;
      if (x > xMax) xMax = x;
      if (y < yMin) yMin = y;
      if (y > yMax) yMax = y;
    }
    if (!isFinite(xMin)) return 0;
    return (xMax - xMin) * (yMax - yMin);
  };
  return [...polys].sort((a, b) => area(b.d) - area(a.d));
}

function parseFrozenNow(input: string | number | Date | undefined): Date | undefined {
  if (input == null) return undefined;
  const d = input instanceof Date ? input : new Date(input);
  return Number.isFinite(d.getTime()) ? d : undefined;
}

/**
 * Restrict imageryBase to http(s), relative paths, or the page's own
 * scheme. Config can arrive from an attacker-controlled `?cfg=` URL
 * parameter on the public demo pages; a crafted base would make the
 * visitor's browser issue GET requests (imagery + the two timezone
 * JSON fetches) to an arbitrary origin. The fetched data is always
 * rendered through escaped bindings so this was never script
 * injection — but there's no reason to allow `javascript:`-shaped
 * or cross-protocol bases at all. Returns undefined (→ caller falls
 * back to the bundle-relative default) for anything unrecognized.
 */
function sanitizeImageryBase(input: string | undefined): string | undefined {
  if (typeof input !== 'string' || input.length === 0) return undefined;
  try {
    const resolved = new URL(input, import.meta.url);
    const pageProto =
      typeof location !== 'undefined' ? location.protocol : 'https:';
    const ok =
      resolved.protocol === 'https:' ||
      resolved.protocol === 'http:' ||
      resolved.protocol === pageProto;
    return ok ? input : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Restrict twilightColor to a small, well-known set of CSS color
 * forms. We splice this value into a `style` attribute, and Lit's
 * attribute-escaping already prevents breaking out of the attribute
 * — but a value like `red; background: url(http://attacker.tld/x)`
 * would still inject a rule that pings the URL. Locking the input
 * to hex / rgb[a] / hsl[a] / named-color forms closes that vector.
 * Returns undefined for anything unrecognized so the caller can
 * fall back to its default.
 */
function sanitizeCssColor(input: string | undefined): string | undefined {
  if (typeof input !== 'string') return undefined;
  const v = input.trim();
  // #abc, #abcd, #aabbcc, #aabbccdd
  if (/^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(v)) return v;
  // rgb(...) / rgba(...) / hsl(...) / hsla(...) — digits, dots, commas,
  // percent, whitespace, slashes (CSS-color-4 syntax). No semicolons,
  // braces, or url().
  if (/^(?:rgb|rgba|hsl|hsla)\([\d.,%\s/]+\)$/i.test(v)) return v;
  // Plain alphabetic CSS color names (red, transparent, currentcolor…)
  if (/^[a-z]+$/i.test(v)) return v;
  return undefined;
}

/**
 * Marker time format, tailored for the on-map label.
 *
 * Time format is locale-aware ("12:22 PM" en-US / "12:22" en-GB) and
 * we deliberately drop seconds — markers update every map tick
 * (usually 10 s) so a second hand jitters distractingly.
 *
 * When `withDay` is true we append the weekday ("12:22 PM Friday")
 * so a marker on the far side of the planet whose date has rolled
 * over is obvious at a glance next to your home's "9:22 PM Friday".
 * We use two separate Intl formatters and concatenate manually rather
 * than letting `Intl.DateTimeFormat` interleave the parts itself —
 * Intl puts the weekday first in most locales ("Friday, 12:22 PM"),
 * and on a marker label readers want to scan time first, day second.
 */
function formatMarkerTime(
  d: Date,
  tz: string | undefined,
  withDay: boolean,
  locale?: string,
): string {
  const opts: Intl.DateTimeFormatOptions = {
    hour: 'numeric',
    minute: '2-digit',
    ...(tz ? { timeZone: tz } : {}),
  };
  const time = new Intl.DateTimeFormat(locale, opts).format(d);
  if (!withDay) return time;
  // Short weekday ("Wed" / "mié.") rather than long ("Wednesday")
  // — marker labels stay narrow enough to fit under the dot at
  // typical card widths and the wallpaper-app's overlay markers
  // already render this format, so the two readings agree.
  const dayOpts: Intl.DateTimeFormatOptions = {
    weekday: 'short',
    ...(tz ? { timeZone: tz } : {}),
  };
  const day = new Intl.DateTimeFormat(locale, dayOpts).format(d);
  return `${time} ${day}`;
}

function formatLocalTime(d: Date, tz?: string, locale?: string): string {
  // When a tz is supplied, the readout shows that zone's wall time
  // (DST-aware via Intl). Without one we fall through to the
  // browser's default zone — Pre-0.2.0 behavior.
  return d.toLocaleTimeString(locale, {
    hour: 'numeric',
    minute: '2-digit',
    second: '2-digit',
    timeZoneName: 'short',
    ...(tz ? { timeZone: tz } : {}),
  });
}

function formatUtcTime(d: Date): string {
  const hh = String(d.getUTCHours()).padStart(2, '0');
  const mm = String(d.getUTCMinutes()).padStart(2, '0');
  const ss = String(d.getUTCSeconds()).padStart(2, '0');
  return `${hh}:${mm}:${ss} UTC`;
}

function formatDate(d: Date, tz?: string, locale?: string): string {
  return d.toLocaleDateString(locale, {
    weekday: 'short',
    month: 'short',
    day: 'numeric',
    year: 'numeric',
    ...(tz ? { timeZone: tz } : {}),
  });
}

/** A marker after we've resolved its entity to live coordinates +
 *  timezone. `tzid` may be null when the IANA dataset hasn't loaded
 *  yet — the marker still renders, just without a time line. `color`
 *  is undefined when neither the per-marker nor card-level default
 *  is set; the renderer skips the inline `style` so the
 *  `--geo-marker-color` CSS variable wins. */
interface ResolvedMarker {
  entity: string;
  label: string;
  color: string | undefined;
  /** Resolved day/night colors (per-marker > card-level, sanitized).
   *  When either is defined the renderer flips the dot live with the
   *  terminator; when both are undefined it falls back to `color`. */
  dayColor: string | undefined;
  nightColor: string | undefined;
  lat: number;
  lon: number;
  tzid: string | null;
}

/** Trim and validate the raw marker config. Drops entries with no
 *  entity ID; otherwise leaves `label`/`color` as-is for the
 *  resolveMarkers() step to combine with the entity's friendly_name
 *  and the card-level default color. */
function sanitizeMarkers(
  input: GeoClockCardConfig['markers'],
): MarkerConfig[] {
  if (!Array.isArray(input)) return [];
  const out: MarkerConfig[] = [];
  for (const raw of input) {
    if (!raw || typeof raw.entity !== 'string') continue;
    const entity = raw.entity.trim();
    if (!entity) continue;
    out.push({
      entity,
      label:
        typeof raw.label === 'string' && raw.label.trim() !== ''
          ? raw.label
          : undefined,
      color: typeof raw.color === 'string' ? raw.color : undefined,
      dayColor: typeof raw.dayColor === 'string' ? raw.dayColor : undefined,
      nightColor:
        typeof raw.nightColor === 'string' ? raw.nightColor : undefined,
    });
  }
  return out;
}

function pickMainTimeSource(
  input: GeoClockCardConfig['mainTimeSource'],
): 'home' | 'device' | 'entity' {
  if (input === 'device' || input === 'entity') return input;
  return 'home';
}

window.customCards = window.customCards || [];
window.customCards.push({
  type: 'geo-clock-card',
  name: 'Geo Clock Card',
  description:
    'World map with a live day/night terminator (NASA Blue/Black Marble).',
  preview: true,
});