Weather Map

Live radar, wind, and forecasts over a satellite map, phone first. One screen: the map is the app.

Live: https://boorussia.github.io/weather-map/

Two themes

• Liquid (default): close to Apple's own apps. Liquid-glass controls, SF Pro on iPhone/Mac (Inter elsewhere), system colors, and a weather page with a live sky.
• Classic: the original black-and-amber look, sharp corners, IBM Plex.

Switch under Layers → Units, sound & appearance → Theme. The choice is remembered. Both themes share one layout; DESIGN.md defines both.

On the map

• Search (top): cities and street addresses, suggestions as you type, nearby results first. Press / on a keyboard to jump to it. Tap the empty field for your tagged places.
• Tagged places: press and hold the map (right-click with a mouse) to tag a spot. It's named after the nearest town, and you can type your own name ("Lake house"). Or tap Tag this place on a place's weather page. Each tag is a white pin with its name, small when zoomed out and bigger as you zoom in; tap it to fly there and get its weather, under its own name (the pin turns blue while you're on it). Press and hold a pin to rename or remove it, or remove tags from the search list. Tags stay on the device, up to 50.
• You are the blue dot. The locate button (top right, under Layers) snaps the map back to you and fills in blue while it follows you.
• The weather stays on you (or the place you searched) while you look around: the pin in the weather card's bottom corner is on by default, and a pin marks a searched place on the map. Hover it for what it does. Tap it off and the readout follows the center cross instead: drag, tap, or search, and it reloads when the map settles. Units, thunder sound, the look, and where the data comes from sit at the bottom of the Layers drawer.
• Readout (glass card): place ("My location" when it's you), temperature, condition, H:87° L:76°. Tap it for the weather page.
• Alert pill: appears under the readout while an NWS alert is active there; tap for the full text.
• Alerts (top-right controls): a count of the warnings and watches in view; tap for the list by type (most dangerous first), each alert's zones and full NWS text, and "Show on map". Alert areas on the map use the NWS hazard colors; tap one (or a storm outlook area) for a small card naming every alert there, warnings first, with when each ends; tap an alert in it for its full text.
• Single-site radar: tap a NEXRAD tower (dots with call signs from zoom 6.5, while Radar is on) to see that radar's own scans at full resolution, the past 24 hours and now, with Reflectivity / Velocity in a bar on the timeline card and a dashed ring at the radar's range. Velocity: green toward the radar, red away. The forecast part of the timeline stays HRRR (reflectivity only). Close returns to the composite.
• Storm tracks (Layers, off by default): strong storm cells from the radars' storm tracking with where they're headed (half an hour, or an hour with 15-minute ticks for storms with hail or rotation), colored by threat: red tornado signature, orange rotation, green large hail. Tap for motion, strongest echo, top, hail, rotation. Option: storm reports from the past 24 hours.
• Storm outlook (Layers): SPC severe-storm or WPC flash-flood outlook areas for today, tomorrow, or day 3, labeled by risk.
• Shareable view: the address bar keeps the map position (#map=zoom/lat/lon); reloads and links open there.
• Layers drawer (on the right, like Windy's menu): "On the map" — Radar, Satellite clouds, Lightning (live from the GOES lightning mapper, with a crackle you can mute), Wind; "Storms" — Storm tracks, Alert areas (warnings outlined, watches and hurricane / tropical-storm / surge alerts tinted, every tint under the radar so rain keeps its colors), Storm outlook, Hurricanes (last, with its long list of options); the weather map, picked from thumbnails; radar colors (Color / Mono). The drawer has three tabs: Weather (the layers above, the weather map, the radar's look), Map (style: Satellite / Standard / Dark; State lines, County lines from about one state's zoom in, Traffic: live TomTom speeds, freeways only when zoomed out and every road from city level in, needs VITE_TOMTOM_KEY), and Settings, Snow, mix & ice, Falling rain.
• Weather maps, one at a time, drawn smooth under the radar and wind: wind, gusts, temperature, feels like, rain, rain total (next 24 h), thunderstorms (CAPE), clouds, low clouds, humidity, dew point, pressure, fog/visibility, waves, swell, currents, sea temperature, air quality, snow depth, new snow, and infrared satellite. They follow the timeline (past hours from earlier model runs) and crossfade between hours; a legend under the timeline shows the scale and the value at your point. Model maps come from Environment Canada's global model (15 km) through GeoMet as raw values, decoded from GeoTIFF in the browser and colored on the GPU; infrared is NASA GIBS GOES imagery decoded back to cloud-top temperature; the rest are Open-Meteo points.
• Radar is drawn smooth, like TV-weather radar: each tile's colors are decoded back to reflectivity on the GPU, blurred at screen resolution (smooth shapes instead of square data cells), and recolored (translucent greens for light rain, then yellow, orange, red), leaving out the faint "clear air" returns.
• Hurricanes (layer switch, on by default): while storms are active, a pill under the readout opens the storm panel (wind, pressure, movement, GOES satellite of the storm in color or infrared with a loop, NHC's forecast, an intensity chart of the models, a switch per model group, and NHC's graphics: key messages, cone, wind field, wind odds, arrival times, WPC rainfall). The chevron on the Hurricanes switch lists what it shows, each with its own switch: cone, track, spaghetti and ensemble members, past track, warnings, wind field, wind-speed odds (39+ / 58+ / 74+ mph), arrival of storm winds, storm surge, development outlook, and sea temperature. First load shows only the essentials: the cone, forecast track and points, past track, coastal watches and warnings, and the seven-day outlook; spaghetti, wind field, surge, wind odds, arrival times, and sea temperature are a tap away (turning a model group on in the storm panel brings the spaghetti back with that group). With everything on it still reads: tints (cone, wind field, odds, surge, outlook) lie under the radar and lines over it, and each model is drawn from now on (the part of an older run before now is dropped). The spaghetti: official, consensus, hurricane models (HWRF, HMON, HAFS-A/B, COAMPS-TC), global models (GFS, UKMET, Canadian, NAVGEM, ECMWF when public), ensemble means, statistical/trajectory models, and the 31 GFS ensemble members. Tap a storm to open it.
• Wind is short comets, like Windy's: each a tapered streak along the wind (longer and brighter where it's stronger) that fades in and out instead of popping. The wind comes from Environment Canada's global model (15 km, GeoMet), blended between hours as the timeline plays.
• Hurricane tracker (top-right controls): turns hurricanes on and opens the storm panel, or off again. Off on first load.
• Map only (last of the top-right controls, or F): hides every control so you can just look at the map, fullscreen where the browser allows (not iPhone Safari). The corner button that brings the controls back fades away until you touch the screen or move the mouse; Escape works too.
• Timeline (bottom): scrub or play radar from 24 hours ago, through now, into the forecast (HRRR simulated radar, as far as the latest run reaches, about 15–18 hours), in 15-minute frames, and inside the last 2 hours MRMS's own frames about 5 minutes apart, so the recent radar (and the loop on open) plays the storms' real motion. Playback glides at one hour per second: the rain's motion between each pair of frames is tracked on the GPU (block-matching optical flow over a three-level pyramid), both frames slide along it, and they're mixed as rain amounts before coloring, so storms move and their edges travel instead of one picture fading through the other; the field is rebuilt only when the frames on screen change. The radar is drawn a margin past the screen's edges, and the rain's motion is measured when the frames change or the map settles (not on every frame of a zoom or pan, which made the edges ripple), then mapped into the moving view. 12 frames load ahead (the opening loop all of it, around to its start, and the tile cache grows to hold it on big screens), and it never skips a frame that hasn't arrived, but it doesn't stutter either: it starts once 3 frames are in and eases up to speed, eases down to what has loaded when the network falls behind, and while full resolution can't keep up it plays a zoom coarser (a quarter of the tiles) until it stops. Satellite rain and precipitation type load at z5 (their own resolution), each host has its own request cap (IEM's four HTTP/1.1 hostnames 6 each, others 8), and the slow satellite host never holds a frame up: a nearby estimate stands in until its own arrives. Scrubbing follows the thumb continuously, gliding between frames, anywhere on the timeline: a preview of every frame two zooms coarser (a tile or two each) loads in the background while nothing plays, stands in at once, and sharpens when the thumb rests; letting go glides to the nearest frame. Now and the last 2 hours are NOAA's MRMS mosaic (base reflectivity: every radar merged, clutter and birds removed, about 2 minutes old); older frames are IEM's archive of the same MRMS (its lowest-level composite reflectivity, every 2 minutes), so the whole past is quality-controlled: the raw NEXRAD composite used before showed migrating birds and insects after sunset as a green sheet over the land. Beyond radar range (a hurricane's core far out in the Gulf, the Caribbean) NOAA's satellite rain estimate fills in, converted to radar-like reflectivity, so storms there aren't blank. The first forecast hour carries "now" along its tracked motion and hands off to the HRRR model by +1¾ h, so playback doesn't jump from what the radar sees to what the model drew. Colors follow The Weather Channel's look: solid light-to-deep greens, then yellow (~38 dBZ), orange, red (~50), dark red, magenta. Snow, mix & ice (Map and radar, on by default): snow in light aqua to navy, mix (sleet) pink to magenta, ice (freezing rain) lavender to purple, from the HRRR's precipitation type at each frame's time (the run started that hour for the past, the latest run ahead), spread ~12 km past the model's own precipitation so it covers what the radar sees; the legend shows all four scales. Wind and falling-rain particles follow the same hour. On a keyboard: Space plays/pauses, ← → step an hour, Home returns to now, F toggles map only.
• Traffic cameras (camera button, under trip weather): about 19,000 state DOT cameras on the map, grouped into counts until you zoom in. Tap one to watch it: live video where the DOT streams it to any site (Caltrans, Nevada, Wisconsin, Louisiana; HLS, played natively on Safari and with hls.js, loaded only then, elsewhere), otherwise the DOT's snapshot as often as it renews it, with a link to the DOT's site for its own live player (Florida, Georgia, and Pennsylvania lock their video to their sites). Other views of the same camera, and a strip of the cameras nearby.
• Lightning only (bolt button, under the hurricane tracker): one tap for radar and live lightning alone — hurricanes, storm tracks, outlooks, alert areas, traffic cameras, clouds, wind, and the weather map go away; tap again to put them back. Flashes show as small glows at each flash center, marked with a yellow bolt so you can tell where it struck, with short bolts landing on them.
• Satellite clouds (beta): a main layer switch. Live GOES imagery with the ground and sea removed, so only the clouds lie on the map, in place: by day the visible band (clouds bright, sea dark), at night and for thin high cloud the infrared (clouds cold, surface warm), blended by the sun's height at each pixel. Past GOES's view (the eastern Atlantic, the deep tropics, the rest of the world) NOAA's global satellite mosaic takes over, infrared only, blended in where the GOES picture actually ends (its edge is ragged, so the blend follows its pixels). Limits: bright land or haze can read as thin cloud by day, low warm fog is faint at night, tall cloud tops lean a few kilometers away from the satellite (parallax), and the imagery is about 10–15 minutes old (the global mosaic, ~3 km, a couple of hours).
• Trip weather (route button, under locate): enter where you are starting (your location by default) and where you are going, leave now or later, and it checks the drive at the time you will be at each spot: NWS warnings, watches, and advisories the route crosses (and whether they are in effect while you pass), SPC severe-storm and WPC flash-flood outlooks, and the forecast at a stop every 30 minutes of driving (thunderstorms, heavy rain, snow, freezing rain, fog, strong gusts). Tap a stop to fly there and set the radar to that hour (when forecast radar reaches it). On the map, hover a stop's dot (tap it on a phone) for a card with when you'll get there, the forecast then, and any watches or warnings over that spot at that time.
  • Overnight stops: choose up to 8, 10, or 12 hours of driving a day (or Nonstop) and when mornings start (7, 8, or 9 AM). The drive is split into balanced days, each night lands where a day ends, and the next morning starts at that hour in the town's own time zone (at least 8 hours later). Each night shows the evening and next-morning forecast, alerts count for the whole stay, and every time reads in local time (marked, e.g. "CDT", when it differs from yours). Drive times are typical speeds with no breaks.
• Opens on the Satellite map with Color radar, Radar and Wind on, falling rain off, and the radar looping from an hour ago to an hour ahead (half speed) until you pause, play, or scrub. Skipped if your device is set to reduce motion.

Weather page

Apple Weather's main screen for the selected point: a live sky that matches the current weather and time of day behind glass cards. It's drawn on the GPU: soft clouds lit from the sun's side, the sun moving on its real arc between that day's sunrise and sunset (warm at golden hour), stars and the moon in its actual phase at night, rain at three depths, drifting snow, rolling fog, and lightning that lights the clouds from inside. It shows alerts (tap to expand), the next 2 hours of rain in plain words with 15-minute bars, an hourly strip with sunrise/sunset, 7 days with temperature-colored range bars, and tiles for feels like, UV, wind (compass), humidity, sunrise/sunset, visibility, pressure (gauge), and precipitation. On phones it slides up full screen (swipe down or ✕ to close); at 1100px and wider it stays docked on the right.

Which ideas came from which apps is logged in docs/inspiration.md. PRODUCT.md is the brief; DESIGN.md is the locked visual language; read it before changing any UI.

Run

npm install
npm run dev        # http://localhost:5173
npm test           # unit tests (vitest)
npm run build      # typecheck + production build into dist/
npm run preview    # serve dist/ locally

Node 20+ is recommended. npm run dev binds to your LAN address too (server.host), so you can open it on your phone while on the same Wi-Fi to test the real thing.

Configure: NWS User-Agent (required)

api.weather.gov asks every client to send a User-Agent that names the app and a contact (website or email), so NWS can reach you if your traffic causes trouble. Set yours before deploying:

cp .env.example .env.local
# then edit .env.local:
# VITE_NWS_USER_AGENT="WeatherMap/1.0 ([email protected])"

How it's sent: every NWS request includes User-Agent: <your value>. NWS allows this header in CORS. Firefox honors it; Chrome and Safari don't let page scripts set User-Agent, so they send the browser's own string instead. NWS accepts that, but if you want your contact string on every request, put a small proxy in front of api.weather.gov (a Netlify/Vercel/Cloudflare function that adds the header) and point NWS_BASE in src/config.ts at it.

Data sources and attribution

Source	Used for	Terms
NWS api.weather.gov	Place name (/points), latest observation, forecast, active alerts	U.S. government data, no key. User-Agent required (above).
NWS warnings map service	Alert areas and the alerts list (warnings and watches; marine products, including the offshore hurricane boxes, and advisories filtered out); trip weather (every alert the route crosses, advisories included)	U.S. government data, no key. Each alert's full text comes from api.weather.gov.
NOAA MRMS via NCEP GeoServer (conus_bref_qcd WMS)	Radar now and for the last 2 hours: the quality-controlled reflectivity mosaic, every 2 minutes	Free, no key, CORS open. Tiles come pre-colored with no published table; the ramp (an anchor color every 5 dBZ, 0.5 dBZ steps) was worked out from the server's colors and checked against IEM's dBZ at the same places and time, and is decoded back to dBZ like IEM's. Frame times from WMS GetCapabilities each minute.
NOAA NESDIS Hydro-Estimator via SSEC RealEarth (NESDIS-GHE-HourlyRainfall)	Rain beyond radar range, under every observed frame	Free, no key, CORS open. Satellite (infrared) rain rate every 15 minutes, ~45 minutes behind, kept 2 days. Tiles are colored in discrete bins (read from RealEarth's legend); each bin's rate is drawn as the reflectivity radar would show for it (Marshall–Palmer). Used only past ~230–300 km from every NEXRAD tower and never over an echo the radar has; tiles fully inside radar coverage aren't requested.
IEM HRRR precipitation type (hrrr::REFP)

The on-screen attribution strip (bottom-left) credits Open-Meteo, NWS, CARTO, and OpenStreetMap, each linked. Esri and NOAA GOES credits appear while their imagery is showing.

Staying inside Open-Meteo's free tier

Each grid point counts as one call. The app requests about 40 points per view in one batched request and refetches only when the view leaves the padded grid, the zoom changes by 2+ levels, or the data is 15 minutes old. Requests are at least 8 seconds apart (45 seconds when only detail would improve), and the last 6 grids are cached for panning back and forth. A normal session uses a few hundred calls.

Lightning is live

Lightning comes from the GOES satellites' Geostationary Lightning Mapper (flash extent density, a frame every minute, about a minute behind) through SSEC RealEarth's tiles. The tiles are colored; the app reads the colors back into flash locations and strengths, draws a soft glow where lightning is flashing, and sets the animated bolts (and the crackle) inside those flashes, about one every few seconds per active spot, capped at 1.2 per second for the view. It refreshes every minute and when you pan off the fetched area. If the feed is down, bolts fall back to forecast thunderstorm cells from Open-Meteo, and a note says so. If no lightning is in view when you turn it on, a short note says that too.

Deploy

It's a static site: build, then host dist/ anywhere.

• GitHub Pages (live now): .github/workflows/pages.yml tests, builds, and deploys on every push to master. It sets BASE_PATH=/<repo>/ because Pages serves the site from a sub-path, and sets the NWS User-Agent contact to the repo URL. To use your email instead, edit VITE_NWS_USER_AGENT in the workflow.
• Netlify: netlify.toml is included (build npm run build, publish dist). Add VITE_NWS_USER_AGENT under Site settings → Environment variables.
• Vercel: import the repo; it detects Vite (build npm run build, output dist). Add VITE_NWS_USER_AGENT in Project → Settings → Environment Variables.

VITE_ variables are baked in at build time, so redeploy after changing it.

Install on a phone

The site ships a web app manifest, so it can go on the home screen today: Safari → Share → Add to Home Screen (iOS), or Chrome → Install app (Android). It opens full screen, black, with no browser chrome.

Project layout

src/
  config.ts             defaults, endpoints, fetch budgets
  state.ts              tiny store; units + sound persist, layers do not
  main.ts               wiring: map, data, layers, UI
  data/                 NWS, Open-Meteo, grid fetching, geolocation, routes + trip hazards (framework-free)
  field/grid.ts         Open-Meteo lattice + bilinear sampling
  layers/               wind / rain / thunder particle layers on canvas
  map/                  MapLibre setup, smoothed radar (WebGL layer + palette), trip route, basemap grayscale
  audio/crackle.ts      procedural thunder sound (Web Audio)
  ui/                   HUD, sheet, panels, trip planner, icons
  styles.css            tokens from DESIGN.md
tests/                  vitest unit tests for the pure logic

iPhone app (App Store)

The App Store version wraps this same site with Capacitor (ios/, capacitor.config.json). Inside the app the page runs edge to edge like the home-screen app (html.native), and location comes from iOS through @capacitor/geolocation (src/util/position.ts), since the web view's own asks twice. iPhone only, portrait; bundle ID com.boorussia.weathermap. The privacy policy is public/privacy.html, served by Pages and linked from Layers → Settings.

1. Install Xcode from the Mac App Store, open it once, and sign in under Settings → Accounts with your Apple Developer account.
2. Put VITE_NWS_USER_AGENT and VITE_TOMTOM_KEY in .env.local; they're baked in at build time.
3. npm run ios builds the site and copies it into the Xcode project; npm run ios:open also opens Xcode.
4. In Xcode: the App target → Signing & Capabilities → pick your Team. Run it on a simulator or your iPhone.
5. Product → Archive → Distribute App → App Store Connect, then test it in TestFlight before submitting.

After any change to the site, run npm run ios again before building in Xcode.

Taking it native later

Everything under data/, field/, and layers/ is plain TypeScript with no framework, written so the logic can move. Three routes, from least to most work:

1. Home-screen web app (now). Already works. No App Store listing, no push notifications on older iOS.
2. Wrap this site with Capacitor (started 2026-10-24: see iPhone app above). Same code inside a native iOS/Android shell. Native plugins add push, haptics, and background location when you want them.
3. Native Swift (SwiftUI + MapKit or MapLibre Native). Port data/ and field/ almost line for line, and redraw the particles with Metal or Core Animation. MapKit gives you Apple Maps, including its satellite and hybrid views, free and built in. Best feel and battery life; needed for widgets, Live Activities, and the Apple Watch. The most work.

Apple Maps on the website (MapKit JS) is possible but needs a paid Apple Developer account ($99/yr) for a MapKit key, and Apple doesn't allow its tiles inside other map libraries, so MapLibre would have to be swapped out. The free Esri imagery covers the satellite look on the web until the native app.

Known limits (v1)

• Wind and rain fields are model data (Open-Meteo), not observations. Radar is observed, but only in the US. Satellite clouds are worldwide to 72° N/S: GOES East + West where they see (minutes old), NOAA's global mosaic elsewhere (a couple of hours old).
• Outside NWS coverage the place shows as coordinates, with Open-Meteo filling in temperature and conditions. There are no alerts there.
• The map stays north-up (no rotation or tilt). That keeps the particle math cheap on phones.