v0.2.5

First stable release since v0.2.2 — promotes the v0.2.3/v0.2.4 beta line. No breaking changes; existing configs work unchanged.

What's new

• Ultrawide / letterbox rendering. The night mask, twilight glow, hour band, and time-zone boundaries now wrap-tile across the seam, so the map fills displays wider than its native 2048×1068 viewBox instead of leaving the side bars blank. Matters most for fullscreen dashboards and the geoclock.world demo / wallpaper page.
• Short weekday in marker times. Marker labels now read e.g. 3:50 PM Wed instead of 3:50 PM Wednesday — narrower, locale-aware, and consistent with the companion wallpaper app. Toggle the day off entirely with markerShowDay: false.
• Editor robustness. The visual editor now guards against non-numeric entry in number fields (no more NaN brightness), normalizes the twilight color to a valid hex for the swatch, preserves custom alpha on color pickers, and shows corrected ranges + entity-fallback help text.

Performance

Steady-state and interaction CPU on always-on dashboards (tablets, Pi) is substantially lower:

• Terminator geometry is memoized on (map time, center longitude) instead of rebuilt every render.
• Hover updates are coalesced to one per animation frame — mousing over the map no longer triggers a full re-render per pointer event.
• The time-zone overlay re-projects only when the center longitude drifts past 0.5° (was rebuilding ~419 polygons every ~10 s in sun mode); sub-threshold drift is absorbed by a group translate.
• Wrap-tile copies of the TZ layers and hour band are <use> references rather than duplicated subtrees, and the TZ polygon fields are no longer reactive state (eliminating a double render).

Correctness / internal

• WebKit filtered-mask viewport-clip workaround. WebKit clips each filtered element inside an SVG <mask> to roughly one viewport width, which truncated the night layer with a hard vertical edge that shifted with the aspect-fit mode. The night mask is now a single-viewport region with the feathered polygon tiled as <use> copies — seamless under all fit modes.
• IANA time-zone lookup cache coarsened to ~1 km keys and capped at 512 entries so a moving device_tracker marker can't grow it without bound.
• imageryBase sanitization — restricted to http(s) / page-scheme, since config can arrive from a URL parameter on the public demo page.

Upgrading

HACS users: update as normal. No config changes are required. If you set markerShowDay and want the old long-weekday text, that format is no longer available — the short weekday is now the only labelled form.

Full Changelog: v0.2.2...v0.2.5

v0.2.3-beta

Release v0.2.3-beta

This pre-release includes critical performance improvements, coordinate edge-case robustness fixes, and configuration editor enhancements identified during the recent code review.

🚀 Key Improvements & Optimizations

1. IANA Timezone Lookup Caching (Performance)

   • Replaced the $O(N)$ linear scans through the polygon boundary dataset (which run on every 1Hz render tick) with a coordinate-keyed ianaTzCache inside GeoClockCard.
   • Keys are based on 4-decimal coordinates (providing highly accurate $\sim 11$-meter resolution).
   • Reduces CPU usage dramatically, particularly on wall-mounted low-power tablets.
   • The cache is automatically cleared on configuration updates and initial data loads.

2. Longitude Normalization (Robustness)

   • Integrated standard longitude wrapping (-180 to 180 degrees) into the findIanaZoneForLatLon utility inside timezones-iana.ts.
   • Prevents point-in-polygon lookups from failing when tracked entities or Home Assistant zone sensors report out-of-bounds coordinates (e.g. 185 or -190).
   • Covered with robust unit tests in test/timezones-iana.test.ts.

3. Editor Color Alpha Preservation (Visual Editor Quality)

   • Implemented a smart alpha channel parser and formatting helper (hexToRgb, applyAlpha) inside the card configuration editor.
   • Opening and saving settings through the visual editor no longer strips alpha transparency. It intelligently parses previous configurations (including #rrggbbaa, #rgba, standard rgba(), and modern space-separated rgba()) and merges existing alpha channels when selecting new colors using the 6-digit visual color picker.
   • Cleaned up and removed the unused private strField helper to maintain a warning-free compilation.

---

📝 Release Note Standards Guideline

To ensure maximum transparency, future releases will consistently include detailed descriptive logs outlining performance impacts, architectural adjustments, and stability gains rather than raw autogenerated logs alone.

v0.2.2

Fix

Hour-of-day band read one hour low in sun-centered mode. In sun-centered mode the band's columns sit at fractional 15° offsets from whole hours — centerLon = subsolar is fractional because of the equation of time (typically ±1° away from where it would be under uniform mean time). The per-column local hour was floor-truncated via | 0, so a column whose true local time was 11:55 got displayed as 11:00 — every column read one hour low whenever EoT was positive (April 15 → June 13, September 1 → December 25).

Cards that center on a fixed longitude (center: home, center: longitude, center: entity) were unaffected — those columns sit at integer-hour-aligned meridians where the fraction is exactly zero, hiding the bug.

The fix rounds to the nearest whole hour rather than truncating; an outer % 24 handles Math.round wrapping 23.7 → 24 → midnight.

No new features, no breaking changes

Drop-in upgrade from v0.2.1.

Internal

• Regression test added against buildHourCells simulating noon UTC in May (EoT ≈ +3 min, subsolar ≈ -0.75°): the center column must read noon, not 11.

Full Changelog: v0.2.1...v0.2.2

v0.2.1

Fixes

Time-zone popup never dismissed on mobile. iOS Safari and several Android browsers don't fire pointerleave on tap-and-release, so the popup got stuck on-screen until you tapped another region. The auto-dismiss is now also scheduled on pointerenter for touch events — popups self-clear after 2.5 s regardless of whether pointerleave ever fires. Tapping a different region cancels and re-arms the timer for the new popup.

Marker-only hover edge case. When the user had only ever interacted with location markers (no IANA polygons, no offset bands), hoverPos could remain set after the marker was dismissed. Leave handlers now consider all three layers when deciding whether to clear the position.

Live demo (geoclock.world) only — not in the HACS card

iOS fullscreen fallback. iOS Safari refuses Element.requestFullscreen() on anything but <video> tags, so the fullscreen button on geoclock.world was a silent no-op for iPhone / iPad users. Added a CSS-based pseudo-fullscreen path: page chrome hides, the map pins to the viewport. The browser URL bar still shows (no API can hide that from a regular web page) but the map fills the rest of the screen — close enough to wall-display mode for kiosk use. Esc exits on desktops.

This change is in docs/web/ and only affects the live demo, not the HACS-installed card.

Internal

• Deploy workflow now reads version via jq instead of node -p with shell-escaped quotes — the latter silently produced an empty string and uploaded one batch of assets to geoclock-world/v/ instead of /v0.2.0/. R2 paths now reliably track package.json#version.

No breaking changes

Drop-in upgrade from v0.2.0. Same config schema, same defaults, same rendering — only the touch-event behaviour changes.

Full Changelog: v0.2.0...v0.2.1

v0.2.0

⚠️ Breaking change

mainTimeSource defaults to home — the wall-clock readout now shows the time at your HA-configured location, not the viewing browser's local time. To restore pre-0.2.0 behavior, add mainTimeSource: device to your card config.

What's new

Location markers. Pin any list of HA entities on the map. Each marker shows a colored dot, its label, and the current local time at that location (DST-aware via IANA polygon hit-test). Per-marker color, card-wide default via markerColor, or --geo-marker-color CSS variable for theme-only restyling. Visibility is always (label + time under the dot) or hover (popup-only). The weekday is appended by default so a marker on the far side of the planet whose date has rolled over is obvious — toggle off with markerShowDay: false for time-only.

Configurable main clock. New mainTimeSource: home | device | entity config (default home). Reads from your HA zone (default), the viewing browser, or any HA entity with lat/lon attributes.

Home marker label + time. Opt-in via showHomeMarkerLabel, shows the home name and current local time under the existing dot.

Visual editor fixes. Entity selection now uses HA's <ha-selector> and reliably renders. Color and number inputs commit on change instead of input — no more map redraw on every drag step or keystroke.

Markers config example

type: custom:geo-clock-card
markers:
  - entity: zone.work
    label: Office
  - entity: person.alice
    color: '#ff7a3d'
markerLabelMode: always
markerShowDay: true
mainTimeSource: home
showHomeMarker: true
showHomeMarkerLabel: true

Internal changes

• Markers render as HTML overlays (not SVG) so dot, halo, and label stay at fixed CSS pixel size regardless of card width — previous SVG version was illegible on anything below full screen.
• Editor awaits loadCardHelpers() before rendering, which is what registers <ha-selector> and friends; without it the picker tags mount as inert elements.
• HassLike type unified across card and editor.
• Greenwich (lon=0°) is now the explicit fallback for misconfigured non-sun centering modes — visually distinct from sun so a broken config doesn't silently look right. Watch the console for a warn line that names the broken field.

Notable since v0.1.2

• v0.1.2 — visual editor fixes (center selection, entity picker UX)
• v0.1.1 — first HACS-ready release with NASA Blue/Black Marble imagery, day/night terminator, hour band, IANA TZ overlay, and DST-aware hover popups

Full Changelog: v0.1.2...v0.2.0

v0.1.2 — visual editor fixes

Patch release fixing two user-reported issues with the visual card editor.

What's fixed

• Center-mode dropdown wasn't applying selections. Switched from ha-select + mwc-list-item to a native <select> element. The selected event from the MWC stack was silently dropping values across HA frontend versions; native selects fire change deterministically.
• Entity picker not appearing in entity mode. Removed an over-defensive readiness check that was rendering a fallback message instead of letting the browser do its normal late-upgrade of <ha-entity-picker>. Now uses the same direct-render pattern every other HA custom card uses.
• Misconfigured non-sun centering looked identical to sun. Card-side resolveCenterLon now falls back to Greenwich (0°) instead of the subsolar point when a mode's required data is missing (no HA longitude, no centerLongitude, no entity longitude). A console warning fires on the fallback so the cause is visible in DevTools.

What's the same

Everything else in v0.1.1: 24-month NASA Blue Marble + Black Marble imagery, real day/night terminator, DST-aware hover popups for 419 IANA zones, sun/home/longitude/entity centering, time scrubbing, viewport-aware throttling, full visual editor.

Install via HACS

• Already on v0.1.1: HACS will pick up the upgrade automatically.
• New install: HACS → ⋮ → Custom repositories → add https://github.com/jpettitt/geo-clock-card, category Lovelace.

Bundle

29 release assets: geo-clock-card.js (49 KB), geo-clock-card.js.gz (16 KB), 24 daylight composites, night map, offset GeoJSON, IANA GeoJSON.

NASA imagery is public domain. timezone-boundary-builder data is ODbL.

v0.1.1 — first HACS-installable release

First HACS-installable release of geo-clock-card.

Highlights

• Live world map with NASA Blue Marble (24 frames, start + mid of each month) + Black Marble imagery.
• Day/night terminator computed from real solar geometry, with a tunable warm twilight glow at the boundary.
• DST-aware hover popup for every IANA time zone on the planet — taps work on mobile (pointer events + 2.5 s touch dismissal). Open ocean falls back to a generic offset popup.
• Centering modes: sun (default — subsolar, daylight stays in the middle), home (HA-configured location), longitude (numeric), or entity (any zone / person / device_tracker).
• Optional home marker at your HA location that tracks the map's drift.
• Visual editor (HA Lovelace) — every option that matters is exposed; advanced visual knobs tucked under an expansion panel.
• Locale-aware time format in the popup (24h or AM/PM follows browser config) with a date line so remote-zone day rollovers are visible.
• Power-aware: the timer drops to 30 min cadence when the card is off-screen or the browser tab is backgrounded.

Install via HACS

1. HACS → ⋮ → Custom repositories → add https://github.com/jpettitt/geo-clock-card, category Lovelace.
2. Install Geo Clock Card.
3. Refresh. Resource is auto-added at /hacsfiles/geo-clock-card/geo-clock-card.js.
4. Add the card from the UI picker — visual editor opens.

Full config reference and CSS-variable theming hooks: see README.md.

Bundle

• geo-clock-card.js — 46 KB, single file
• blue-marble-{01..12}-{start,mid}-2048.jpg — 24 daylight composites
• black-marble-2048.jpg — night map
• timezones.json — 8 KB offset bands
• timezones-iana.json — 958 KB IANA polygons (419 zones)

NASA imagery is public domain. timezone-boundary-builder data is ODbL.

v0.1.1-alpha

Full Changelog: v0.1.0...v0.1.1-alpha