weather_app/AGENTS.md

# WeatherLens — Agent Context

## Project Overview

A single-file, offline-capable weather app built with **Svelte 5** (runes-based reactivity). Pulls data from the free **Open-Meteo API** (no API key required), persists user locations and settings in IndexedDB, and provides configurable weather alerts. The production build is a single `dist/index.html` with zero network dependencies — it works from `file://`, USB, or any static server. Weather data is fetched live from the CDN.

## Architecture

```
src/
├── App.svelte                  # Root component — geolocation init, sidebar + main layout
├── main.js                     # Entry point, mounts App + imports CSS
├── components/
│   ├── LocationSidebar.svelte  # Saved locations list, inline geocoding search
│   ├── AddLocationDialog.svelte# Modal: geocoding search → add location
│   ├── CurrentWeather.svelte   # Hero card: current conditions, dynamic gradient bg
│   ├── HourlyForecast.svelte   # Horizontal scroll: next 24h with precip bars
│   ├── DailyForecast.svelte    # 7-day forecast cards with icons + detail
│   ├── WeatherDetail.svelte    # Expanded metrics: wind, atmosphere, sun/UV, temps
│   ├── NotificationBell.svelte  # Bell icon with badge; dropdown lists/dismisses alerts
│   ├── StormWatch.svelte       # Storms tab: active alerts, SPC outlook, recent reports
│   └── SettingsDialog.svelte   # Units (metric/imperial), alert thresholds, data reset
├── lib/
│   ├── autofocus.js            # Svelte action for autofocus on mount
│   ├── api/
│   │   ├── weather.js          # Open-Meteo fetch functions (forecast + geocoding)
│   │   ├── nws.js              # NWS forecast + official advisories normalization
│   │   ├── storm.js            # NWS alerts, SPC outlooks, IEM storm reports (+ geo helpers)
│   │   ├── moon.js             # Moon phase calculation
│   │   └── weather-codes.js    # WMO code → icon/description/severity mapping
│   ├── storage/
│   │   └── db.js               # IndexedDB layer (idb): locations, settings
│   └── stores/
│       ├── app.svelte.js       # AppStore: $state for locations, forecast, UI, settings
│       ├── storm.svelte.js     # StormStore: alerts/outlook/reports for the selected point
│       └── notifications.svelte.js # Alert generation from forecast data
```

## Key Design Decisions

- **Svelte 5 runes** — Use `$state`, `$derived`, `$effect`. Props-based event passing. No legacy Svelte events.
- **$state proxy pitfall** — Svelte 5 `$state` wraps values in JavaScript Proxy objects. Any API that uses the structured clone algorithm (IndexedDB `put()`/`add()`, `structuredClone()`, `postMessage()`, `history.pushState()`) will throw `"Proxy object could not be cloned"` if given a `$state` value directly. To avoid this:
  - **Never pass `$state` objects directly to IndexedDB.** Always spread into a plain object first: `db.put('store', { ...proxyObj })`.
  - **Never use `structuredClone()` on `$state` values.** Use `{ ...obj, nested: { ...obj.nested } }` or `JSON.parse(JSON.stringify(obj))` for deep copies.
  - **DB functions should sanitize inputs** at the storage layer: `JSON.parse(JSON.stringify(settings))` before `db.put()`.
  - **Reading from IndexedDB returns plain objects** (no proxies), so reads are safe.
- **Open-Meteo API** — Free forecast API (no key required). Two endpoints used:
  - `api.open-meteo.com/v1/forecast` — Current + hourly (24h) + daily (7 days) weather
  - `geocoding-api.open-meteo.com/v1/search` — City/location search by name
- **Weather state via emoji** — All weather icons use Unicode emoji, so no icon fonts or image assets are needed. WMO codes map to emoji via `weather-codes.js`.
- **Dynamic backgrounds** — CurrentWeather uses CSS gradient classes (`weather-bg-clear`, `weather-bg-rain`, `weather-bg-storm`, etc.) determined by weather severity.
- **Alert/notification system** — `notifications.svelte.js` analyzes forecast data each time it changes and generates alerts for: high precipitation, thunderstorms, extreme temps, high UV, strong winds. Alerts are shown only in the 🔔 bell dropdown. Dismissed alerts persist in IndexedDB and only auto-reset when the forecast date changes (so refreshing the same day won't resurrect cleared alerts).
- **Geolocation on first launch** — If no locations are saved, the app requests browser geolocation and adds "Current Location" automatically. Falls back to manual "Add Location" if denied.
- **Locations persist in IndexedDB** — Via `idb`. Two stores: `locations` and `settings`. Current location pinned at top of sidebar.
- **Single-file build** — `vite-plugin-singlefile` inlines all JS/CSS; post-build script inlines favicon as base64 data URI.
- **Mobile-first responsive** — Slide-over sidebar on mobile (same pattern as password manager). Bottom tab nav on mobile, desktop tab bar on wide screens. Touch-friendly with large tap targets.
- **No minification** — `minify: false` in vite.config.js for readable single-file output.

## Weather Alert System

The notification store checks each forecast refresh for:

| Alert Type | Trigger | Severity |
|---|---|---|
| Thunderstorm (current) | WMO code 65, 75, 82, 86, 95-99 active now | danger |
| Thunderstorm (forecast) | WMO code 65, 75, 82, 86, 95-99 in next 3 days | danger |
| Precipitation | precipitation_probability_max ≥ threshold (default 70%) | warning |
| High Temperature | temperature_2m_max > threshold (default 35°C) | warning |
| Low Temperature | temperature_2m_min < threshold (default 0°C) | warning |
| UV Index | uv_index_max ≥ threshold (default 6) | warning |
| Wind | wind_speed_10m_max ≥ threshold (default 40 km/h) | warning |

All thresholds are configurable in Settings.

## Storm Watch (SPC / NWS / IEM)

The **Storms** tab (and the red banner above the content when a tornado, severe
thunderstorm or other Extreme alert is in force) is driven by three keyless,
CORS-enabled feeds. All of them are fetched directly from the browser.

| Source | Endpoint | Refresh |
|---|---|---|
| NWS active alerts | `api.weather.gov/alerts/active?point={lat},{lon}` | 2 min HTTP cache |
| SPC Day 1–3 outlook | `spc.noaa.gov/products/outlook/day{1,2,3}otlk_{cat,torn,wind,hail}.nolyr.geojson` | 20 min HTTP cache |
| NWS Local Storm Reports | `mesonet.agron.iastate.edu/geojson/lsr.geojson?west=…&sts=…&ets=…` | 5 min HTTP cache |

- **SPC risk at a point** comes from point-in-polygon on the GeoJSON features
  (`LABEL` of the *highest* containing category wins: TSTM < MRGL < SLGT < ENH
  < MDT < HIGH). Day-1 tornado/hail/wind probabilities use the same test, with
  the "Less Than 2% All Areas" background polygon ignored.
- **There is no Skywarn API** — Skywarn is a per-WFO volunteer program. The
  equivalent machine-readable ground truth is NWS Local Storm Reports (LSRs),
  which include trained-spotter and Spotter Network submissions.
- The IEM LSR query **must include `sts`/`ets`**; a bbox alone (or `hours=`)
  returns national reports. `normalizeStormReports` then applies the exact
  radius cut (160 km by default) and sorts nearest-first.
- Non-US points skip the SPC/LSR requests (`isUsPoint`) and the UI explains the
  US-only coverage.
- The store de-dupes concurrent loads, ignores stale responses after a
  location switch, and polls every 5 min only while the document is visible.

## Scripts

| Command | Description |
|---|---|
| `npm run dev` | Vite dev server with HMR on `:5173` |
| `npm run build` | Production build → `dist/index.html` (single self-contained file) |
| `npm run preview` | Preview production build |
| `npm run test` | Vitest (watch mode) |
| `npm run test:run` | Vitest (single run) |

## Testing

- Framework: **Vitest** with **jsdom** environment
- Test setup: `tests/setup.js` (fake-indexeddb polyfill, Web Crypto API polyfill, mock matchMedia, mock navigator)
- Test files:
  - `tests/lib/api/weather-codes.test.js` — WMO code → icon/desc/severity mapping, isSevereWeather
  - `tests/lib/storage/db.test.js` — Locations CRUD (add, update, delete, setCurrent, clear), settings CRUD with defaults
  - `tests/lib/stores/app.test.js` — AppStore initialization and derived selectedLocation
  - `tests/lib/stores/notifications.test.js` — Alert generation for all alert types, dismissal, reset, day filtering
  - `tests/lib/api/storm.test.js` — Point-in-polygon, risk ranking, SPC probabilities, LSR radius filter, alert sorting
  - `tests/lib/stores/storm.test.js` — StormStore loading, caching, location switches, partial failures, non-US points
  - `tests/components/storm-watch.test.js` — StormWatch renders populated and empty states (Svelte `mount` in jsdom)
- Run with `npm run test` or `npm run test:run`

## API Notes

- Open-Meteo is free and requires no API key.
- Forecast parameters: current (10 metrics), hourly (4 metrics × time), daily (8 metrics × 7 days)
- Geocoding API returns up to 8 results per query with name, coordinates, country, admin1, timezone.
- Rate limits are generous (~10,000 requests/day for the free tier).
- Used only via `fetch()` in browser — no server-side API calls needed.
- SPC outlook files are regenerated at each issuance (roughly 12Z/13Z/16:30Z/01Z);
  never hardcode a timestamp, just re-fetch the stable `.nolyr.geojson` names.
- NWS/SPC/IEM all send `Access-Control-Allow-Origin: *`, so the static single-file
  build can call them without a proxy.