v0.2.0: location markers, configurable main clock, theme-friendly colors

Markers
- new `markers:` config: pin any number of HA entities (zone /
  person / device_tracker) on the map. Each shows a colored dot,
  the entity's friendly_name (or a per-marker override), and the
  current local time at that location, DST-aware via IANA polygon
  hit-test.
- per-marker `color`, card-wide `markerColor`, or — when neither
  is set — the new `--geo-marker-color` CSS variable lets themes
  restyle without touching card config.
- `markerLabelMode: always | hover` controls whether the label +
  time render under the dot or only on hover/tap.
- `markerShowDay` (default true) appends the weekday after the
  time so a marker on the far side of the planet whose date has
  rolled over reads obviously.
- markers are HTML overlays, not SVG, so the dot, halo, and label
  text stay at fixed CSS pixel size regardless of card width
  (previous SVG version was illegible on anything but full screen).

Home marker
- new `showHomeMarkerLabel` toggle adds the home name +
  current local time under the existing home dot, using the
  HA-configured `time_zone` (or polygon hit-test as fallback).

Main clock — BREAKING
- new `mainTimeSource: home | device | entity` (default `home`).
  Pre-0.2.0 cards always read the viewing browser's zone; that's
  now `mainTimeSource: device`. To preserve old behavior, set
  `mainTimeSource: device` explicitly.
- `mainTimeEntity` companion field for `entity` mode.

Editor
- markers panel: per-row entity selector + label + color picker,
  add/remove buttons, label-visibility + show-day toggles.
- entity selection now uses HA's `<ha-selector>` (the official
  high-level wrapper). Editor awaits `loadCardHelpers()` before
  rendering, which is what registers the selector internals —
  without this gate the picker tags stayed inert and invisible.
- color pickers now fire on `change` (commit) instead of `input`
  (every drag step), eliminating the redraw thrash that made the
  picker feel laggy.
- numeric textfields likewise commit on `change` so typing a
  number doesn't trigger a map redraw per keystroke.

Internals
- HassLike type unified in src/types.ts; drops the divergent
  copies in card and editor.
- `sunElevation` documented as a public test-ground-truth export.
- console.debug noise from earlier debugging dropped.

Docs
- README updated for the breaking change, the new config keys,
  the Greenwich (not sun) fallback for non-sun centering modes
  when their data is missing, and the editor's actual component
  list.
- TODO.md groomed: monthly Blue Marble, HACS release, and the
  in-HA-test items ticked off.
- dev/index.html gained controls for the new toggles + colors.

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

Author: jpettitt

README.md

@@ -41,8 +41,27 @@ the planet.
   hemisphere stays in the middle and the map slowly drifts),
   `home` (your HA-configured longitude), `longitude` (any numeric
   value), or `entity` (follow a zone / person / device-tracker entity).
+  All non-`sun` modes fall back to **Greenwich (lon=0°)** with a
+  console warning when their data isn't available — so a misconfigured
+  mode looks visibly different from `sun` instead of silently behaving
+  the same.
 - **Home marker** — optional dot at your HA-configured location that
-  tracks the map's drift.
+  tracks the map's drift, with an opt-in label + current local time
+  beneath it.
+- **Location markers** — pin any list of HA entities (zones, persons,
+  device-trackers) on the map; each shows the entity's label and the
+  current local time at that zone (DST-aware, looked up from its
+  longitude/latitude). Labels are always-visible by default; flip to
+  hover-only if you'd rather keep the map tidy. The weekday is
+  appended to the time so a marker on the far side of the planet
+  whose date has rolled over is obvious at a glance — toggle off if
+  you want time-only. Per-marker color, or a card-wide default that
+  themes can override via `--geo-marker-color`.
+- **Main-clock time source** — the wall-clock readout can read from
+  your HA location (default), the viewing device, or any HA entity
+  with a longitude/latitude. *(Breaking change in v0.2.0: pre-0.2.0
+  cards behaved as if the source was the viewing device. Set
+  `mainTimeSource: device` to keep the old behavior.)*
 - **Time scrubbing** — freeze the clock at any UTC moment via `now: …`
   for screenshots or to preview the look at, say, the December solstice.
 - **Visual editor** — opens automatically when adding the card; advanced
@@ -116,6 +135,7 @@ center: sun
 centerLongitude: -119       # required when center: longitude. -180..180.
 centerEntity: zone.home     # required when center: entity. Must expose a longitude attribute.
 showHomeMarker: false       # render a dot at hass.config.latitude/longitude
+showHomeMarkerLabel: false  # also show home name + current local time under the dot
 
 # Imagery + atmosphere (under "Advanced visual settings" in the editor)
 dayBrightness: 1.15         # CSS brightness() on the day layer (0.5..2.0)
@@ -131,6 +151,25 @@ updateInterval: 1           # seconds between clock-readout ticks (1..600).
                             # both drop to 30 minutes when the card is off-screen.
 now: "2024-12-21T09:21:00Z" # freeze the clock at this moment (omit for live)
 
+# Main-clock time source — home (default) | device | entity
+# - 'home'   reads hass.config.time_zone (the HA-configured zone)
+# - 'device' uses the viewing browser's zone (pre-0.2.0 behavior)
+# - 'entity' picks the IANA zone of an HA entity's lat/lon
+mainTimeSource: home
+mainTimeEntity: zone.work   # required when mainTimeSource: entity
+
+# Location markers — list of HA entities to pin on the map.
+# Each entity must expose numeric `latitude` and `longitude` attributes.
+markers:
+  - entity: zone.work
+    label: Office            # optional — defaults to the entity's friendly_name
+    color: "#3da9fc"         # optional — defaults to markerColor
+  - entity: person.alice
+markerLabelMode: always     # always | hover
+markerColor: "#3da9fc"      # default fill for markers without their own color
+                            # — omit (or unset) to let `--geo-marker-color` win
+markerShowDay: true         # append weekday after the time (e.g. "12:22 PM Friday")
+
 # Overlays
 showTimezoneBand: true      # hour-of-day numbers across the top
 showTimezoneBoundaries: true # 15° offset rectangle bands + IANA polygons
@@ -145,12 +184,17 @@ imageryBase: ""             # override the assets URL (e.g. host on a CDN)
 
 - **`sun`** (default) — centered on the current subsolar longitude. The map
   drifts westward as the sun moves; the daylit hemisphere stays in the middle.
-- **`home`** — centered on `hass.config.longitude`. Falls back to `sun` if HA
-  hasn't reported a location.
-- **`longitude`** — centered on a numeric `centerLongitude` value.
+- **`home`** — centered on `hass.config.longitude`. Falls back to **Greenwich
+  (0°)** with a `console.warn` if HA hasn't reported a longitude.
+- **`longitude`** — centered on a numeric `centerLongitude` value. Falls back
+  to **Greenwich (0°)** if the value is missing or non-numeric.
 - **`entity`** — centered on the longitude attribute of an HA entity. Works
   with `zone.*`, `person.*`, and most `device_tracker.*` entities. Falls back
-  to `sun` if the entity is missing or has no longitude.
+  to **Greenwich (0°)** if the entity is missing or has no numeric longitude.
+
+The Greenwich fallback is deliberate — it's visually distinct from `sun`
+mode so a misconfiguration doesn't silently look right. Watch the browser
+console for a one-off warn line that names the broken field.
 
 ### Theme via CSS variables
 
@@ -169,6 +213,7 @@ geo-clock-card:
   --geo-tz-mid: "#6ab0ff"
   --geo-tz-line: rgba(255, 255, 255, 0.18)
   --geo-home-marker: var(--accent-color, "#ff7a3d")
+  --geo-marker-color: "#3da9fc"
 ```
 
 Most of these have a matching named config option (e.g. `dayBrightness`
@@ -210,7 +255,7 @@ center mode, time-scrubbing with solstice/equinox presets, etc.
 - [`src/timezone-band.ts`](src/timezone-band.ts) — top-of-map hour band + tick lines.
 - [`src/day-image.ts`](src/day-image.ts) — picks the right monthly daylight image for a given date.
 - [`src/geo-clock-card.ts`](src/geo-clock-card.ts) — the Lit element that wires it all together.
-- [`src/geo-clock-card-editor.ts`](src/geo-clock-card-editor.ts) — visual config editor (HA `ha-textfield` / `ha-select` / `ha-formfield` / `ha-switch` / `ha-entity-picker` / `ha-expansion-panel`); lazy-loaded by the card via `getConfigElement()` and bundled inline.
+- [`src/geo-clock-card-editor.ts`](src/geo-clock-card-editor.ts) — visual config editor (HA `ha-textfield` / `ha-switch` / `ha-formfield` / `ha-selector` / `ha-expansion-panel`, plus native `<select>` for the centering / time-source / marker-mode dropdowns where `ha-select` was unreliable). Awaits `loadCardHelpers()` before rendering so the entity selectors register correctly. Lazy-loaded by the card via `getConfigElement()` and bundled inline.
 
 The original design notes are in [`DESIGN.md`](DESIGN.md).
 

TODO.md

@@ -9,8 +9,8 @@
 - [x] Lit element with SVG mask + feathered terminator
 - [x] Local time + UTC + date readout
 - [x] NASA Blue/Black Marble fetch script
-- [ ] First in-Home-Assistant test (pending user verification)
-- [ ] HACS metadata polish + first tagged release
+- [x] First in-Home-Assistant test
+- [x] HACS metadata polish + first tagged release (v0.1.x shipped, v0.2.0 in flight)
 
 ## Stage 2 — time-zone affordances
 
@@ -24,12 +24,13 @@
 
 ## Stage 3 — decisions deferred to here
 
-- [ ] Monthly Blue Marble variant (auto-pick by current month)
+- [x] Monthly Blue Marble variant (auto-pick by current month) — 24 frames (start + mid each month) shipped via day-image.ts
 - [ ] Better terminator: WebGL/canvas with sun-elevation alpha + tinted twilight
-- [ ] Bundling strategy: ship imagery in HACS package vs. fetch on first load vs. CDN
-- [ ] Optional: location pins (config + HA zones)
+- [x] Bundling strategy: imagery ships alongside the JS bundle in dist/, copied by HACS / manual install
+- [x] Location pins (config + HA zones) — `markers:` array with per-marker label + color, always-visible or hover label modes
+- [x] Configurable main-clock time source (home/device/entity, default `home`) — **breaking change** in 0.2.0: pre-0.2.0 cards behaved like `device`
 - [ ] Optional: alternate projection (Mercator)
-- [ ] Optional: Lovelace visual config editor
+- [x] Lovelace visual config editor
 
 ## Quality / housekeeping (ongoing)
 

dev/index.html

@@ -64,6 +64,28 @@ <h1>geo-clock-card — local preview</h1>
     <label><input id="band" type="checkbox" checked> show hour band</label>
     <label><input id="boundaries" type="checkbox" checked> show TZ boundaries</label>
     <label><input id="homemarker" type="checkbox"> home marker</label>
+    <label><input id="homemarkerlabel" type="checkbox"> home marker label + time</label>
+    <label><input id="markers" type="checkbox"> sample markers (London, Tokyo)</label>
+    <label>marker labels:
+      <select id="markerLabelMode">
+        <option value="always" selected>always</option>
+        <option value="hover">hover only</option>
+      </select>
+    </label>
+    <label><input id="markerShowDay" type="checkbox" checked> show weekday on markers</label>
+    <label>marker default color:
+      <input id="markerColor" type="color" value="#3da9fc">
+    </label>
+    <label>tz line color:
+      <input id="tzLineColor" type="color" value="#ffffff">
+    </label>
+    <label>main time source:
+      <select id="mainTimeSource">
+        <option value="home" selected>home (HA tz)</option>
+        <option value="device">device</option>
+        <option value="entity">entity</option>
+      </select>
+    </label>
     <label>center:
       <select id="center">
         <option value="sun" selected>sun (subsolar)</option>
@@ -101,6 +123,13 @@ <h1>geo-clock-card — local preview</h1>
     const center = document.getElementById('center');
     const centerLongitude = document.getElementById('centerLongitude');
     const homemarker = document.getElementById('homemarker');
+    const homemarkerlabel = document.getElementById('homemarkerlabel');
+    const markersEl = document.getElementById('markers');
+    const markerLabelMode = document.getElementById('markerLabelMode');
+    const markerShowDayEl = document.getElementById('markerShowDay');
+    const markerColor = document.getElementById('markerColor');
+    const tzLineColor = document.getElementById('tzLineColor');
+    const mainTimeSource = document.getElementById('mainTimeSource');
     const live = document.getElementById('live');
     const datetime = document.getElementById('datetime');
     const brightness = document.getElementById('brightness');
@@ -147,8 +176,23 @@ <h1>geo-clock-card — local preview</h1>
         center: center.value,
         centerLongitude: Number(centerLongitude.value),
         showHomeMarker: homemarker.checked,
+        showHomeMarkerLabel: homemarkerlabel.checked,
+        markerLabelMode: markerLabelMode.value,
+        markerShowDay: markerShowDayEl.checked,
+        markerColor: markerColor.value,
+        timezoneLineColor: tzLineColor.value,
+        mainTimeSource: mainTimeSource.value,
         imageryBase: '../dist/',
       };
+      if (markersEl.checked) {
+        cfg.markers = [
+          { entity: 'zone.london', label: 'London', color: '#3da9fc' },
+          { entity: 'zone.tokyo', label: 'Tokyo', color: '#ff7a3d' },
+        ];
+      }
+      if (mainTimeSource.value === 'entity') {
+        cfg.mainTimeEntity = 'zone.london';
+      }
       if (!live.checked && datetime.value) {
         cfg.now = inputUtcToIso(datetime.value);
       }
@@ -157,8 +201,27 @@ <h1>geo-clock-card — local preview</h1>
       // on the first render. (HA itself sets hass after construction
       // too, but the preview is single-shot per rebuild.)
       card.hass = {
-        config: { latitude: 36.5, longitude: -119 },
-        states: {},
+        config: {
+          latitude: 36.5,
+          longitude: -119,
+          time_zone: 'America/Los_Angeles',
+        },
+        states: {
+          'zone.london': {
+            attributes: {
+              latitude: 51.5074,
+              longitude: -0.1278,
+              friendly_name: 'London',
+            },
+          },
+          'zone.tokyo': {
+            attributes: {
+              latitude: 35.6762,
+              longitude: 139.6503,
+              friendly_name: 'Tokyo',
+            },
+          },
+        },
       };
       stage.appendChild(card);
       twilightVal.textContent = `${twilight.value}°`;
@@ -187,6 +250,13 @@ <h1>geo-clock-card — local preview</h1>
     center.addEventListener('change', rebuild);
     centerLongitude.addEventListener('input', rebuild);
     homemarker.addEventListener('change', rebuild);
+    homemarkerlabel.addEventListener('change', rebuild);
+    markersEl.addEventListener('change', rebuild);
+    markerLabelMode.addEventListener('change', rebuild);
+    markerShowDayEl.addEventListener('change', rebuild);
+    markerColor.addEventListener('change', rebuild);
+    tzLineColor.addEventListener('change', rebuild);
+    mainTimeSource.addEventListener('change', rebuild);
     live.addEventListener('change', rebuild);
     datetime.addEventListener('input', () => {
       if (datetime.value) live.checked = false;