From 5dae2801df9865d6d8e5f8d1825bf6c31fa31cd2 Mon Sep 17 00:00:00 2001
From: Aayush Charde <121353160+AayushCharde@users.noreply.github.com>
Date: Wed, 17 Jun 2026 14:32:15 +0530
Subject: [PATCH 1/2] feat(frontend): professional visual overhaul (v1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Preview-driven redesign building on the Volt Green theme.

- Markers: cluster bubbles when zoomed out (with counts), individual chargers
  colored by reliability, and a selected-charger highlight ring.
- Map UI: Nominatim place search (open/free) to jump to a city; a reliability
  legend; refined control bar (search + filters) with elevation.
- StationDetail: full redesign — photo header with name overlay, reliability
  status badge, graceful "Unknown" fields (location-only chargers look
  complete), connector chips, "Get directions" link, disabled "Report status"
  (Phase 2 hint), source + coordinates, slide-in transition, mobile sheet.
- A dismissible welcome/intro card (first visit).
- Design tokens: motion (ease/duration) + a status-badge style.
- Pure, tested helpers: format.ts (power/coords/directions/source/name) and
  geocode.ts (Nominatim URL + parse + fetch).

Verified: svelte-check 0, lint, 36 tests, build. Ships to a Vercel preview for review.
---
 frontend/src/app.css                    |  32 +++
 frontend/src/lib/Legend.svelte          |  52 +++++
 frontend/src/lib/StationDetail.svelte   | 170 +++++++++------
 frontend/src/lib/format.ts              |  36 ++++
 frontend/src/lib/geocode.ts             |  56 +++++
 frontend/src/routes/+page.svelte        | 266 +++++++++++++++++++-----
 frontend/tests/overhaul-helpers.test.ts |  71 +++++++
 7 files changed, 570 insertions(+), 113 deletions(-)
 create mode 100644 frontend/src/lib/Legend.svelte
 create mode 100644 frontend/src/lib/format.ts
 create mode 100644 frontend/src/lib/geocode.ts
 create mode 100644 frontend/tests/overhaul-helpers.test.ts

diff --git a/frontend/src/app.css b/frontend/src/app.css
index df7acd7..22d6aa7 100644
--- a/frontend/src/app.css
+++ b/frontend/src/app.css
@@ -35,6 +35,10 @@
   --shadow-md: 0 4px 12px rgb(15 23 42 / 0.1);
   --shadow-lg: 0 12px 32px rgb(15 23 42 / 0.18);
   --space: 8px;
+
+  /* motion */
+  --ease: cubic-bezier(0.2, 0, 0, 1);
+  --dur: 180ms;
 }
 
 @media (prefers-color-scheme: dark) {
@@ -174,6 +178,34 @@ a {
   flex: none;
 }
 
+/* reliability status badge (used by the station detail panel) */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  padding: 4px 11px;
+  border-radius: 999px;
+  font-size: 0.82rem;
+  font-weight: 600;
+  border: 1px solid color-mix(in srgb, currentColor 35%, transparent);
+  background: color-mix(in srgb, currentColor 12%, var(--surface));
+}
+.badge .dot {
+  background: currentColor;
+}
+.badge-green {
+  color: var(--rel-green);
+}
+.badge-amber {
+  color: var(--rel-amber);
+}
+.badge-red {
+  color: var(--rel-red);
+}
+.badge-grey {
+  color: var(--rel-grey);
+}
+
 /* accessible focus ring everywhere */
 :focus-visible {
   outline: 2px solid var(--accent);
diff --git a/frontend/src/lib/Legend.svelte b/frontend/src/lib/Legend.svelte
new file mode 100644
index 0000000..76c190d
--- /dev/null
+++ b/frontend/src/lib/Legend.svelte
@@ -0,0 +1,52 @@
+<script lang="ts">
+  const items: { color: string; label: string }[] = [
+    { color: "var(--rel-green)", label: "Likely working" },
+    { color: "var(--rel-amber)", label: "Mixed reports" },
+    { color: "var(--rel-red)", label: "Likely down" },
+    { color: "var(--rel-grey)", label: "No recent reports" },
+  ];
+</script>
+
+<aside class="legend" aria-label="Reliability legend">
+  <span class="title">Reliability</span>
+  {#each items as item}
+    <span class="row"><span class="dot" style="background: {item.color}"></span>{item.label}</span>
+  {/each}
+</aside>
+
+<style>
+  .legend {
+    position: fixed;
+    bottom: 16px;
+    left: 16px;
+    z-index: 7;
+    display: flex;
+    flex-direction: column;
+    gap: 5px;
+    padding: 10px 12px;
+    background: color-mix(in srgb, var(--surface) 88%, transparent);
+    backdrop-filter: blur(10px);
+    border: 1px solid var(--border);
+    border-radius: var(--r-md);
+    box-shadow: var(--shadow-sm);
+    font-size: 0.78rem;
+  }
+  .title {
+    font-weight: 700;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    font-size: 0.68rem;
+  }
+  .row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    color: var(--text);
+  }
+  @media (max-width: 520px) {
+    .legend {
+      display: none;
+    }
+  }
+</style>
diff --git a/frontend/src/lib/StationDetail.svelte b/frontend/src/lib/StationDetail.svelte
index 3254dd7..121a813 100644
--- a/frontend/src/lib/StationDetail.svelte
+++ b/frontend/src/lib/StationDetail.svelte
@@ -1,6 +1,8 @@
 <script lang="ts">
   import { createEventDispatcher } from "svelte";
+  import { fly } from "svelte/transition";
   import { describeReliability, evidenceLine } from "$lib/reliability";
+  import { sourceLabel, formatPower, formatCoords, directionsUrl, displayName } from "$lib/format";
   import type { Station } from "$lib/stations";
 
   export let station: Station;
@@ -9,7 +11,6 @@
 
   $: display = describeReliability(station.reliability);
   $: evidence = evidenceLine(station.reliability);
-  $: sourceLabel = station.source === "osm" ? "© OpenStreetMap" : "Open Charge Map";
 
   function onKeydown(e: KeyboardEvent): void {
     if (e.key === "Escape") dispatch("close");
@@ -18,51 +19,59 @@
 
 <svelte:window on:keydown={onKeydown} />
 
-<aside class="panel" role="dialog" aria-label="Station details">
-  <img
-    class="banner"
-    src="/img/ev-charger.webp"
-    alt=""
-    width="360"
-    height="150"
-    loading="lazy"
-    decoding="async"
-  />
-  <button class="close btn-icon" on:click={() => dispatch("close")} aria-label="Close details">
-    ✕
-  </button>
+<aside class="panel" role="dialog" aria-label="Station details" transition:fly={{ y: 24, duration: 180 }}>
+  <div class="banner">
+    <img src="/img/ev-charger.webp" alt="" width="380" height="150" loading="lazy" decoding="async" />
+    <div class="banner-grad"></div>
+    <h2 class="title">{displayName(station)}</h2>
+    <button class="close" on:click={() => dispatch("close")} aria-label="Close details">✕</button>
+  </div>
 
   <div class="body">
-    <h2>{station.name ?? "Unnamed station"}</h2>
-
-    <p class="reliability">
-      <span class="dot" style="background: var(--rel-{display.color})"></span>
-      <strong>{display.text}</strong>
-      <span class="muted">· {evidence}</span>
-    </p>
+    <span class="badge badge-{display.color}">
+      <span class="dot"></span>{display.text}
+    </span>
+    <p class="evidence">{evidence}</p>
 
     <dl>
-      {#if station.operator}
-        <dt>Operator</dt>
-        <dd>{station.operator}</dd>
-      {/if}
+      <dt>Operator</dt>
+      <dd>{station.operator ?? "Unknown"}</dd>
+
       <dt>Max power</dt>
-      <dd>{station.max_power_kw ? `${station.max_power_kw} kW` : "Unknown"}</dd>
-      {#if station.access_type}
-        <dt>Access</dt>
-        <dd>{station.access_type}</dd>
-      {/if}
-      {#if station.connectors.length}
-        <dt>Connectors</dt>
-        <dd class="chips">
-          {#each station.connectors as connector}
-            <span class="chip">{connector}</span>
-          {/each}
-        </dd>
-      {/if}
+      <dd>{formatPower(station.max_power_kw)}</dd>
+
+      <dt>Access</dt>
+      <dd>{station.access_type ?? "Unknown"}</dd>
+
+      <dt>Connectors</dt>
+      <dd>
+        {#if station.connectors.length}
+          <span class="chips">
+            {#each station.connectors as connector}<span class="chip">{connector}</span>{/each}
+          </span>
+        {:else}
+          <span class="muted">Not reported</span>
+        {/if}
+      </dd>
     </dl>
 
-    <p class="source muted">Source: {sourceLabel}</p>
+    <div class="actions">
+      <a
+        class="btn btn-primary"
+        href={directionsUrl(station.lat, station.lng)}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        ➜ Get directions
+      </a>
+      <button class="btn btn-ghost" disabled title="Community reports — coming soon">
+        Report status
+      </button>
+    </div>
+
+    <p class="meta muted">
+      {sourceLabel(station.source)} · {formatCoords(station.lat, station.lng)}
+    </p>
   </div>
 </aside>
 
@@ -72,7 +81,7 @@
     top: 72px;
     right: 16px;
     z-index: 9;
-    width: min(360px, calc(100vw - 32px));
+    width: min(380px, calc(100vw - 32px));
     background: var(--surface);
     border: 1px solid var(--border);
     border-radius: var(--r-lg);
@@ -80,44 +89,61 @@
     overflow: hidden;
   }
   .banner {
-    display: block;
+    position: relative;
+    height: 132px;
+  }
+  .banner img {
     width: 100%;
-    height: 150px;
+    height: 100%;
     object-fit: cover;
+    display: block;
     background: var(--surface-2);
   }
+  .banner-grad {
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(180deg, rgb(0 0 0 / 0.05) 30%, rgb(0 0 0 / 0.72));
+  }
+  .title {
+    position: absolute;
+    left: 16px;
+    right: 48px;
+    bottom: 10px;
+    margin: 0;
+    color: #fff;
+    font-size: 1.15rem;
+    line-height: 1.25;
+    text-shadow: 0 1px 4px rgb(0 0 0 / 0.5);
+  }
   .close {
     position: absolute;
     top: 10px;
     right: 10px;
-    background: color-mix(in srgb, var(--surface) 70%, transparent);
+    width: 30px;
+    height: 30px;
+    border: none;
+    border-radius: 50%;
+    background: rgb(0 0 0 / 0.45);
+    color: #fff;
+    cursor: pointer;
     backdrop-filter: blur(4px);
   }
-  .body {
-    padding: 16px;
+  .close:hover {
+    background: rgb(0 0 0 / 0.65);
   }
-  h2 {
-    font-size: 1.15rem;
-    margin: 0 0 8px;
-  }
-  .reliability {
-    display: flex;
-    align-items: center;
-    gap: 8px;
-    margin: 0 0 12px;
+  .body {
+    padding: 14px 16px 16px;
   }
-  .muted {
+  .evidence {
+    margin: 8px 0 14px;
+    font-size: 0.85rem;
     color: var(--text-muted);
   }
-  .source {
-    margin: 12px 0 0;
-    font-size: 0.78rem;
-  }
   dl {
     display: grid;
-    grid-template-columns: auto 1fr;
-    gap: 6px 14px;
-    margin: 0;
+    grid-template-columns: 92px 1fr;
+    gap: 8px 14px;
+    margin: 0 0 16px;
     font-size: 0.92rem;
   }
   dt {
@@ -138,6 +164,26 @@
     padding: 2px 10px;
     font-size: 0.82rem;
   }
+  .muted {
+    color: var(--text-muted);
+  }
+  .actions {
+    display: flex;
+    gap: 8px;
+  }
+  .actions .btn {
+    flex: 1;
+    justify-content: center;
+    text-decoration: none;
+  }
+  .btn[disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .meta {
+    margin: 14px 0 0;
+    font-size: 0.76rem;
+  }
   @media (max-width: 520px) {
     .panel {
       top: auto;
diff --git a/frontend/src/lib/format.ts b/frontend/src/lib/format.ts
new file mode 100644
index 0000000..92d7be0
--- /dev/null
+++ b/frontend/src/lib/format.ts
@@ -0,0 +1,36 @@
+/**
+ * Pure presentation helpers for the station detail view. No DOM — unit-tested.
+ */
+
+import type { Station } from "$lib/stations";
+
+/** Human label for a data source code. */
+export function sourceLabel(source: string): string {
+  if (source === "osm") return "© OpenStreetMap";
+  if (source === "ocm") return "Open Charge Map";
+  return source;
+}
+
+/** "22 kW" or a fallback when power is unknown. */
+export function formatPower(kw: number | null): string {
+  if (kw == null || !Number.isFinite(kw) || kw <= 0) return "Unknown";
+  // Trim trailing .0 (e.g. 22.0 -> "22", 3.7 -> "3.7").
+  const rounded = Math.round(kw * 10) / 10;
+  return `${rounded % 1 === 0 ? rounded.toFixed(0) : rounded} kW`;
+}
+
+/** "17.4432, 78.4953" rounded for display. */
+export function formatCoords(lat: number, lng: number): string {
+  return `${lat.toFixed(4)}, ${lng.toFixed(4)}`;
+}
+
+/** A maps directions URL for a station's location (opens in a new tab). */
+export function directionsUrl(lat: number, lng: number): string {
+  return `https://www.openstreetmap.org/directions?to=${lat}%2C${lng}`;
+}
+
+/** Fallback display name for stations that only have a location. */
+export function displayName(station: Pick<Station, "name">): string {
+  const n = station.name?.trim();
+  return n && n.length > 0 ? n : "Unnamed station";
+}
diff --git a/frontend/src/lib/geocode.ts b/frontend/src/lib/geocode.ts
new file mode 100644
index 0000000..9460595
--- /dev/null
+++ b/frontend/src/lib/geocode.ts
@@ -0,0 +1,56 @@
+/**
+ * Place search via Nominatim (OpenStreetMap) — open + free, no key.
+ * Pure URL builder + a thin fetch wrapper (injectable) so it's unit-testable.
+ */
+
+export interface GeocodeResult {
+  label: string;
+  lat: number;
+  lng: number;
+}
+
+const NOMINATIM_URL = "https://nominatim.openstreetmap.org/search";
+
+/** Build the Nominatim search URL (JSON, capped results). */
+export function geocodeUrl(query: string, limit = 5): string {
+  const params = new URLSearchParams({
+    q: query,
+    format: "jsonv2",
+    limit: String(limit),
+    addressdetails: "0",
+  });
+  return `${NOMINATIM_URL}?${params.toString()}`;
+}
+
+type FetchLike = (input: string, init?: { signal?: AbortSignal; headers?: Record<string, string> }) => Promise<Response>;
+
+interface NominatimItem {
+  display_name?: string;
+  lat?: string;
+  lon?: string;
+}
+
+/** Parse Nominatim's JSON into our result shape (skips malformed rows). */
+export function parseGeocode(items: unknown): GeocodeResult[] {
+  if (!Array.isArray(items)) return [];
+  const out: GeocodeResult[] = [];
+  for (const raw of items as NominatimItem[]) {
+    const lat = Number(raw?.lat);
+    const lng = Number(raw?.lon);
+    if (!Number.isFinite(lat) || !Number.isFinite(lng)) continue;
+    out.push({ label: raw.display_name ?? `${lat}, ${lng}`, lat, lng });
+  }
+  return out;
+}
+
+/** Search for a place. Returns [] on a non-OK response; aborts propagate. */
+export async function geocode(
+  query: string,
+  fetchImpl: FetchLike = fetch,
+  signal?: AbortSignal,
+): Promise<GeocodeResult[]> {
+  if (!query.trim()) return [];
+  const res = await fetchImpl(geocodeUrl(query), signal ? { signal } : undefined);
+  if (!res.ok) return [];
+  return parseGeocode(await res.json());
+}
diff --git a/frontend/src/routes/+page.svelte b/frontend/src/routes/+page.svelte
index de7727f..8843a3a 100644
--- a/frontend/src/routes/+page.svelte
+++ b/frontend/src/routes/+page.svelte
@@ -5,6 +5,7 @@
     Map as MapLibreMap,
     GeoJSONSource,
     ExpressionSpecification,
+    FilterSpecification,
     MapLayerMouseEvent,
   } from "maplibre-gl";
   import { env } from "$env/dynamic/public";
@@ -12,6 +13,7 @@
   import { debounce } from "$lib/debounce";
   import { reliabilityHex } from "$lib/reliability";
   import { currentTheme, type Theme } from "$lib/theme";
+  import { geocode } from "$lib/geocode";
   import {
     fetchStations,
     minPowerForTier,
@@ -20,14 +22,15 @@
     type Station,
   } from "$lib/stations";
   import StationDetail from "$lib/StationDetail.svelte";
+  import Legend from "$lib/Legend.svelte";
 
   const apiBase = resolveApiBase(env.PUBLIC_API_BASE_URL);
-
   const DEFAULT_CENTER: [number, number] = [78.45, 17.4];
   const DEFAULT_ZOOM = 11;
 
   let mapContainer: HTMLDivElement;
   let map: MapLibreMap | undefined;
+  let mapReady = false;
   let inFlight: AbortController | undefined;
   let themeObserver: MutationObserver | undefined;
 
@@ -35,16 +38,27 @@
   let selectedStation: Station | undefined;
   let loadError: string | undefined;
   let loading = false;
-  let loaded = false; // true after the first successful load
-
-  $: showEmpty = loaded && !loading && !loadError && stationsById.size === 0;
+  let loaded = false;
 
-  // Filters — changing either re-queries immediately.
   let connector = "";
   let powerTier: PowerTier = "any";
-
   const CONNECTORS = ["CCS (Type 2)", "Type 2", "CHAdeMO", "Type 1 (J1772)"];
 
+  let searchQuery = "";
+  let searchBusy = false;
+  let searchCtl: AbortController | undefined;
+
+  let showWelcome = false;
+
+  $: showEmpty = loaded && !loading && !loadError && stationsById.size === 0;
+  // Highlight the selected charger on the map (clears when none selected).
+  $: if (map && mapReady) {
+    const filter: FilterSpecification = selectedStation
+      ? ["==", ["get", "id"], selectedStation.id]
+      : ["==", ["get", "id"], "__none__"];
+    map.setFilter("station-selected", filter);
+  }
+
   function colorExpr(theme: Theme): ExpressionSpecification {
     return [
       "match",
@@ -78,7 +92,7 @@
     loading = true;
     try {
       const stations = await fetchStations(apiBase, query, fetch, controller.signal);
-      if (inFlight !== controller) return; // a newer request superseded this one
+      if (inFlight !== controller) return;
       stationsById = new Map(stations.map((s) => [s.id, s]));
       const source = map.getSource("stations") as GeoJSONSource | undefined;
       source?.setData(stationsToFeatureCollection(stations));
@@ -95,10 +109,43 @@
 
   const debouncedReload = debounce(() => void reload(), 350);
 
+  async function onSearch(e: Event): Promise<void> {
+    e.preventDefault();
+    if (!searchQuery.trim() || !map) return;
+    searchCtl?.abort();
+    const c = new AbortController();
+    searchCtl = c;
+    searchBusy = true;
+    try {
+      const results = await geocode(searchQuery, fetch, c.signal);
+      if (searchCtl === c && results[0]) {
+        map.flyTo({ center: [results[0].lng, results[0].lat], zoom: 13 });
+      }
+    } catch {
+      /* ignore search errors */
+    } finally {
+      if (searchCtl === c) searchBusy = false;
+    }
+  }
+
+  function dismissWelcome(): void {
+    showWelcome = false;
+    try {
+      localStorage.setItem("pp-welcomed", "1");
+    } catch {
+      /* ignore */
+    }
+  }
+
   onMount(() => {
+    try {
+      showWelcome = !localStorage.getItem("pp-welcomed");
+    } catch {
+      /* ignore */
+    }
+
     void (async () => {
       const { Map, NavigationControl, GeolocateControl } = await import("maplibre-gl");
-
       const m = new Map({
         container: mapContainer,
         style: "https://tiles.openfreemap.org/styles/liberty",
@@ -119,11 +166,43 @@
         m.addSource("stations", {
           type: "geojson",
           data: { type: "FeatureCollection", features: [] },
+          cluster: true,
+          clusterRadius: 50,
+          clusterMaxZoom: 13,
         });
+
+        // Cluster bubbles (zoomed out).
+        m.addLayer({
+          id: "clusters",
+          type: "circle",
+          source: "stations",
+          filter: ["has", "point_count"],
+          paint: {
+            "circle-color": ["step", ["get", "point_count"], "#86efac", 10, "#4ade80", 50, "#22c55e"],
+            "circle-radius": ["step", ["get", "point_count"], 15, 10, 19, 50, 25],
+            "circle-stroke-width": 2,
+            "circle-stroke-color": "#ffffff",
+          },
+        });
+        m.addLayer({
+          id: "cluster-count",
+          type: "symbol",
+          source: "stations",
+          filter: ["has", "point_count"],
+          layout: {
+            "text-field": ["get", "point_count_abbreviated"],
+            "text-font": ["Noto Sans Bold"],
+            "text-size": 12,
+          },
+          paint: { "text-color": "#06310f" },
+        });
+
+        // Individual chargers, colored by reliability.
         m.addLayer({
           id: "station-circles",
           type: "circle",
           source: "stations",
+          filter: ["!", ["has", "point_count"]],
           paint: {
             "circle-radius": ["interpolate", ["linear"], ["zoom"], 8, 4, 14, 8],
             "circle-color": colorExpr(currentTheme()),
@@ -131,25 +210,46 @@
             "circle-stroke-color": "#ffffff",
           },
         });
+        // Selected-charger highlight ring (filtered to the selected id).
+        m.addLayer({
+          id: "station-selected",
+          type: "circle",
+          source: "stations",
+          filter: ["==", ["get", "id"], "__none__"],
+          paint: {
+            "circle-radius": ["interpolate", ["linear"], ["zoom"], 8, 9, 14, 14],
+            "circle-color": "rgba(132,204,22,0.18)",
+            "circle-stroke-width": 3,
+            "circle-stroke-color": "#84cc16",
+          },
+        });
 
+        m.on("click", "clusters", (e: MapLayerMouseEvent) => {
+          const f = e.features?.[0];
+          if (!f) return;
+          const clusterId = f.properties?.cluster_id as number;
+          const src = m.getSource("stations") as GeoJSONSource;
+          void src.getClusterExpansionZoom(clusterId).then((zoom) => {
+            const geom = f.geometry;
+            if (geom.type === "Point") {
+              m.easeTo({ center: geom.coordinates as [number, number], zoom });
+            }
+          });
+        });
         m.on("click", "station-circles", (e: MapLayerMouseEvent) => {
-          const feature = e.features?.[0];
-          if (!feature) return;
-          const found = stationsById.get(feature.properties?.id);
+          const found = stationsById.get(e.features?.[0]?.properties?.id);
           if (found) selectedStation = found;
         });
-        m.on("mouseenter", "station-circles", () => {
-          m.getCanvas().style.cursor = "pointer";
-        });
-        m.on("mouseleave", "station-circles", () => {
-          m.getCanvas().style.cursor = "";
-        });
+        for (const layer of ["clusters", "station-circles"]) {
+          m.on("mouseenter", layer, () => (m.getCanvas().style.cursor = "pointer"));
+          m.on("mouseleave", layer, () => (m.getCanvas().style.cursor = ""));
+        }
 
+        mapReady = true;
         m.on("moveend", debouncedReload);
         void reload();
       });
 
-      // Recenter on the user if allowed; otherwise keep the default view.
       if (navigator.geolocation) {
         navigator.geolocation.getCurrentPosition(
           (pos) => m.flyTo({ center: [pos.coords.longitude, pos.coords.latitude], zoom: 13 }),
@@ -158,7 +258,6 @@
         );
       }
 
-      // Recolor circles when the user toggles the theme.
       themeObserver = new MutationObserver(() => {
         if (map?.getLayer("station-circles")) {
           map.setPaintProperty("station-circles", "circle-color", colorExpr(currentTheme()));
@@ -173,6 +272,7 @@
 
   onDestroy(() => {
     inFlight?.abort();
+    searchCtl?.abort();
     themeObserver?.disconnect();
     map?.remove();
   });
@@ -188,40 +288,43 @@
 
 <div class="map" bind:this={mapContainer}></div>
 
-<div class="filters">
-  <label>
-    <span class="sr-only">Connector</span>
-    <select class="field" bind:value={connector} on:change={() => void reload()}>
+<div class="controls">
+  <form class="search" on:submit={onSearch}>
+    <input
+      class="field"
+      type="search"
+      placeholder="Search a city or place…"
+      bind:value={searchQuery}
+      aria-label="Search for a place"
+    />
+    <button class="btn btn-primary" type="submit" disabled={searchBusy}>
+      {searchBusy ? "…" : "Go"}
+    </button>
+  </form>
+  <div class="filters">
+    <select class="field" bind:value={connector} on:change={() => void reload()} aria-label="Connector">
       <option value="">Any connector</option>
-      {#each CONNECTORS as c}
-        <option value={c}>{c}</option>
-      {/each}
+      {#each CONNECTORS as c}<option value={c}>{c}</option>{/each}
     </select>
-  </label>
-  <label>
-    <span class="sr-only">Power</span>
-    <select class="field" bind:value={powerTier} on:change={() => void reload()}>
+    <select class="field" bind:value={powerTier} on:change={() => void reload()} aria-label="Power">
       <option value="any">Any power</option>
       <option value="fast">Fast (≥22 kW)</option>
       <option value="rapid">Rapid (≥50 kW)</option>
     </select>
-  </label>
+  </div>
 </div>
 
-{#if loading}
-  <div class="loading-pill" role="status">Loading chargers…</div>
-{/if}
+<Legend />
 
-{#if loadError}
-  <div class="toast" role="alert">{loadError}</div>
-{/if}
+{#if loading}<div class="loading-pill" role="status">Loading chargers…</div>{/if}
+{#if loadError}<div class="toast" role="alert">{loadError}</div>{/if}
 
 {#if showEmpty}
   <div class="empty" role="status">
     <img src="/img/ev-charger.webp" alt="" width="320" height="120" loading="lazy" decoding="async" />
     <div class="empty-body">
       <h2>No chargers in view</h2>
-      <p>Try zooming out or panning to a populated area — chargers load automatically as you move the map.</p>
+      <p>Try zooming out, searching a city, or panning to a populated area.</p>
     </div>
   </div>
 {/if}
@@ -230,24 +333,57 @@
   <StationDetail station={selectedStation} on:close={() => (selectedStation = undefined)} />
 {/if}
 
+{#if showWelcome}
+  <div class="welcome-backdrop" role="dialog" aria-label="Welcome to PlugPulse">
+    <div class="welcome">
+      <img src="/img/ev-charger.webp" alt="" width="420" height="150" loading="eager" decoding="async" />
+      <div class="welcome-body">
+        <h2>⚡ Find chargers that actually work</h2>
+        <p>
+          PlugPulse shows EV chargers from open data (Open Charge Map + OpenStreetMap) with a
+          community-verified reliability score. Browse the map, search a city, and tap a charger
+          for details.
+        </p>
+        <button class="btn btn-primary" on:click={dismissWelcome}>Explore the map</button>
+      </div>
+    </div>
+  </div>
+{/if}
+
 <style>
   .map {
     position: absolute;
     inset: 0;
   }
-  /* Keep MapLibre's controls clear of the floating header. */
-  :global(.maplibregl-ctrl-top-right),
-  :global(.maplibregl-ctrl-top-left) {
+  :global(.maplibregl-ctrl-top-right) {
     top: 64px;
   }
-  .filters {
+  .controls {
     position: fixed;
     top: 68px;
     left: 16px;
     z-index: 8;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    width: min(320px, calc(100vw - 32px));
+  }
+  .search {
+    display: flex;
+    gap: 6px;
+  }
+  .search .field {
+    flex: 1;
+    box-shadow: var(--shadow-sm);
+  }
+  .filters {
     display: flex;
     gap: 8px;
   }
+  .filters .field {
+    flex: 1;
+    box-shadow: var(--shadow-sm);
+  }
   .toast {
     position: fixed;
     bottom: 16px;
@@ -260,17 +396,9 @@
     border-radius: var(--r-md);
     box-shadow: var(--shadow-md);
   }
-  .sr-only {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    overflow: hidden;
-    clip: rect(0 0 0 0);
-    white-space: nowrap;
-  }
   .loading-pill {
     position: fixed;
-    top: 68px;
+    top: 132px;
     left: 50%;
     transform: translateX(-50%);
     z-index: 8;
@@ -318,6 +446,42 @@
     font-size: 0.88rem;
     color: var(--text-muted);
   }
+  .welcome-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 20;
+    display: grid;
+    place-items: center;
+    padding: 16px;
+    background: rgb(0 0 0 / 0.45);
+    backdrop-filter: blur(2px);
+  }
+  .welcome {
+    width: min(440px, 100%);
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--r-lg);
+    box-shadow: var(--shadow-lg);
+    overflow: hidden;
+  }
+  .welcome img {
+    width: 100%;
+    height: 150px;
+    object-fit: cover;
+    display: block;
+  }
+  .welcome-body {
+    padding: 18px 20px 20px;
+  }
+  .welcome-body h2 {
+    margin: 0 0 8px;
+    font-size: 1.2rem;
+  }
+  .welcome-body p {
+    margin: 0 0 16px;
+    color: var(--text-muted);
+    font-size: 0.92rem;
+  }
   @media (max-width: 520px) {
     .empty img {
       width: 84px;
diff --git a/frontend/tests/overhaul-helpers.test.ts b/frontend/tests/overhaul-helpers.test.ts
new file mode 100644
index 0000000..2d09062
--- /dev/null
+++ b/frontend/tests/overhaul-helpers.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import {
+  sourceLabel,
+  formatPower,
+  formatCoords,
+  directionsUrl,
+  displayName,
+} from "../src/lib/format";
+import { geocodeUrl, parseGeocode, geocode } from "../src/lib/geocode";
+
+describe("format helpers", () => {
+  it("sourceLabel", () => {
+    expect(sourceLabel("osm")).toBe("© OpenStreetMap");
+    expect(sourceLabel("ocm")).toBe("Open Charge Map");
+    expect(sourceLabel("other")).toBe("other");
+  });
+
+  it("formatPower", () => {
+    expect(formatPower(null)).toBe("Unknown");
+    expect(formatPower(0)).toBe("Unknown");
+    expect(formatPower(22)).toBe("22 kW");
+    expect(formatPower(3.7)).toBe("3.7 kW");
+    expect(formatPower(50.0)).toBe("50 kW");
+  });
+
+  it("formatCoords", () => {
+    expect(formatCoords(17.443289, 78.495271)).toBe("17.4433, 78.4953");
+  });
+
+  it("directionsUrl", () => {
+    expect(directionsUrl(17.44, 78.49)).toBe(
+      "https://www.openstreetmap.org/directions?to=17.44%2C78.49",
+    );
+  });
+
+  it("displayName falls back", () => {
+    expect(displayName({ name: "Shell" })).toBe("Shell");
+    expect(displayName({ name: null })).toBe("Unnamed station");
+    expect(displayName({ name: "  " })).toBe("Unnamed station");
+  });
+});
+
+describe("geocode", () => {
+  it("geocodeUrl encodes the query + json format", () => {
+    const url = geocodeUrl("Hyderabad");
+    expect(url).toContain("q=Hyderabad");
+    expect(url).toContain("format=jsonv2");
+    expect(url).toContain("limit=5");
+  });
+
+  it("parseGeocode keeps valid rows, drops malformed, tolerates non-array", () => {
+    const parsed = parseGeocode([
+      { display_name: "London", lat: "51.5", lon: "-0.1" },
+      { display_name: "bad", lat: "x", lon: "y" },
+    ]);
+    expect(parsed).toEqual([{ label: "London", lat: 51.5, lng: -0.1 }]);
+    expect(parseGeocode("nope")).toEqual([]);
+  });
+
+  it("geocode returns [] on empty query and on non-OK", async () => {
+    expect(await geocode("", async () => new Response())).toEqual([]);
+    const notOk = async () => ({ ok: false }) as unknown as Response;
+    expect(await geocode("x", notOk)).toEqual([]);
+  });
+
+  it("geocode parses an OK response", async () => {
+    const ok = async () =>
+      ({ ok: true, json: async () => [{ display_name: "Paris", lat: "48.85", lon: "2.35" }] }) as unknown as Response;
+    expect(await geocode("Paris", ok)).toEqual([{ label: "Paris", lat: 48.85, lng: 2.35 }]);
+  });
+});

From 6f0c6cf6d27d2edc322789dc6931fb216bb18209 Mon Sep 17 00:00:00 2001
From: Aayush Charde <121353160+AayushCharde@users.noreply.github.com>
Date: Wed, 17 Jun 2026 15:09:46 +0530
Subject: [PATCH 2/2] fix(frontend): default API base to live backend + polish

End-to-end everywhere:
- Default API base is now the deployed Render backend, so the app shows real
  data on production, Vercel previews, and shared links even when
  PUBLIC_API_BASE_URL isn't set for that environment. Local dev overrides via
  .env (PUBLIC_API_BASE_URL=http://localhost:8000).

Polish:
- Header brand mark (rounded badge) + subtle header shadow.
- Soft reliability-colored halo under each charger marker for depth.

Tests updated to assert against DEFAULT_API_BASE. svelte-check 0, lint, 36 tests, build OK.
---
 frontend/src/lib/Header.svelte   | 22 ++++++++++++++++------
 frontend/src/lib/api.ts          |  8 ++++++--
 frontend/src/routes/+page.svelte | 19 ++++++++++++++++---
 frontend/tests/stations.test.ts  |  8 ++++----
 4 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/frontend/src/lib/Header.svelte b/frontend/src/lib/Header.svelte
index 7dc3c3a..9a83e2a 100644
--- a/frontend/src/lib/Header.svelte
+++ b/frontend/src/lib/Header.svelte
@@ -20,9 +20,11 @@
 
 <header class="header">
   <a class="brand" href="/" aria-label="PlugPulse home">
-    <svg class="bolt" viewBox="0 0 24 24" width="22" height="22" aria-hidden="true">
-      <path d="M13 2 4 14h6l-1 8 9-12h-6l1-8z" fill="currentColor" />
-    </svg>
+    <span class="mark">
+      <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
+        <path d="M13 2 4 14h6l-1 8 9-12h-6l1-8z" fill="currentColor" />
+      </svg>
+    </span>
     <span class="word">PlugPulse</span>
   </a>
 
@@ -68,19 +70,27 @@
     background: color-mix(in srgb, var(--surface) 82%, transparent);
     backdrop-filter: blur(10px);
     border-bottom: 1px solid var(--border);
+    box-shadow: var(--shadow-sm);
   }
   .brand {
     display: inline-flex;
     align-items: center;
-    gap: 8px;
+    gap: 9px;
     text-decoration: none;
     color: var(--text);
     font-weight: 800;
     font-size: 18px;
     letter-spacing: -0.01em;
   }
-  .bolt {
-    color: var(--primary);
+  .mark {
+    display: inline-grid;
+    place-items: center;
+    width: 30px;
+    height: 30px;
+    border-radius: 9px;
+    background: var(--primary);
+    color: var(--on-primary);
+    box-shadow: var(--shadow-sm);
   }
   .word {
     color: var(--text);
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 1173782..1cd62b2 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -20,9 +20,13 @@ export interface StationQuery {
 
 export const DEFAULT_STATION_LIMIT = 300;
 
-export const DEFAULT_API_BASE = "http://localhost:8000";
+// Default to the deployed backend so the app works end-to-end everywhere
+// (production, Vercel previews, shared links) even when PUBLIC_API_BASE_URL
+// isn't set for that environment. Local dev overrides it via .env
+// (PUBLIC_API_BASE_URL=http://localhost:8000).
+export const DEFAULT_API_BASE = "https://plugpulse-backend-v5bu.onrender.com";
 
-/** Normalize a configured API base URL: fall back to localhost, strip trailing slash. */
+/** Normalize a configured API base URL: fall back to the default, strip trailing slash. */
 export function resolveApiBase(raw: string | undefined): string {
   const base = (raw ?? "").trim() || DEFAULT_API_BASE;
   return base.replace(/\/+$/, "");
diff --git a/frontend/src/routes/+page.svelte b/frontend/src/routes/+page.svelte
index 8843a3a..b594fca 100644
--- a/frontend/src/routes/+page.svelte
+++ b/frontend/src/routes/+page.svelte
@@ -197,6 +197,19 @@
           paint: { "text-color": "#06310f" },
         });
 
+        // Soft reliability-colored halo under each charger (depth/polish).
+        m.addLayer({
+          id: "station-halo",
+          type: "circle",
+          source: "stations",
+          filter: ["!", ["has", "point_count"]],
+          paint: {
+            "circle-radius": ["interpolate", ["linear"], ["zoom"], 8, 9, 14, 18],
+            "circle-color": colorExpr(currentTheme()),
+            "circle-opacity": 0.18,
+            "circle-blur": 0.4,
+          },
+        });
         // Individual chargers, colored by reliability.
         m.addLayer({
           id: "station-circles",
@@ -259,9 +272,9 @@
       }
 
       themeObserver = new MutationObserver(() => {
-        if (map?.getLayer("station-circles")) {
-          map.setPaintProperty("station-circles", "circle-color", colorExpr(currentTheme()));
-        }
+        const expr = colorExpr(currentTheme());
+        if (map?.getLayer("station-circles")) map.setPaintProperty("station-circles", "circle-color", expr);
+        if (map?.getLayer("station-halo")) map.setPaintProperty("station-halo", "circle-color", expr);
       });
       themeObserver.observe(document.documentElement, {
         attributes: true,
diff --git a/frontend/tests/stations.test.ts b/frontend/tests/stations.test.ts
index 72e5a42..caed5b5 100644
--- a/frontend/tests/stations.test.ts
+++ b/frontend/tests/stations.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { resolveApiBase } from "../src/lib/api";
+import { resolveApiBase, DEFAULT_API_BASE } from "../src/lib/api";
 import {
   fetchStations,
   minPowerForTier,
@@ -32,9 +32,9 @@ function okResponse(data: unknown): Response {
 }
 
 describe("resolveApiBase", () => {
-  it("falls back to localhost when empty/undefined", () => {
-    expect(resolveApiBase(undefined)).toBe("http://localhost:8000");
-    expect(resolveApiBase("   ")).toBe("http://localhost:8000");
+  it("falls back to the default when empty/undefined", () => {
+    expect(resolveApiBase(undefined)).toBe(DEFAULT_API_BASE);
+    expect(resolveApiBase("   ")).toBe(DEFAULT_API_BASE);
   });
   it("strips a trailing slash and keeps explicit values", () => {
     expect(resolveApiBase("https://api.example.com/")).toBe("https://api.example.com");