Worker A (v2-core): port core package + scoring v2 with offline tests

- wavereader/openmeteo.py from app/forecasts.py + swell_wave_direction/period, CACHE_VERSION 3
- wavereader/scoring.py merges app/adapters.py + app/scoring.py; v2: swell-first,
arc distance, type-based logistic wind cap, daylight filter, p75 daily_summary,
surfable-hours rank_spots
- wavereader/seafloor.py from app/seafloor.py; per-axis lon step via cos(lat), None-safe cells
- wavereader/breaks.py from app/breaks_data.py; pandas dropped, jsonschema validation,
resolve_break fuzzy match
- tests: 51 offline tests + recorded Bells Beach fixture; deps pydantic/jsonschema/pytest

.env.example

@@ -1,3 +1,9 @@
 # Copy to .env and fill in. Never commit .env.
 # HF token for the HF Router (Nemotron) — https://huggingface.co/settings/tokens
 HF_TOKEN=
+# Model override (default: nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16)
+WR_MODEL=
+# Inference provider override (default: fireworks-ai)
+WR_PROVIDER=
+# Base URL override for a local OpenAI-compatible endpoint (e.g. Ollama/NIM)
+WR_BASE_URL=

pyproject.toml

@@ -8,7 +8,12 @@ dependencies = [
     "gradio>=5.0.0",
     "huggingface-hub>=1.30.0",
     "httpx>=0.27.0",
+    "jsonschema>=4.0.0",
     "pandas>=3.0.5",
     "plotly>=7.0.0",
+    "pydantic>=2.0.0",
     "smolagents[openai]>=1.26.0",
 ]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0"]

tests/conftest.py

@@ -0,0 +1,27 @@
+"""Shared fixtures: no test may hit the network.
+
+The single live Open-Meteo call was recorded once to
+``tests/fixtures/openmeteo_bells.json``. Here every HTTP attempt fails
+fast so an accidental network dependency surfaces as an error, while
+stale-cache fallback paths still work (they catch ``httpx.HTTPError``).
+"""
+
+import sys
+from pathlib import Path
+
+import httpx
+import pytest
+
+# Repo root on sys.path so `wavereader` imports however pytest is invoked
+# (subset runs must not depend on other test modules' bootstraps).
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+
+@pytest.fixture(autouse=True)
+def _no_network(monkeypatch):
+    class _DeadClient:
+        def __init__(self, *a, **k):
+            raise httpx.ConnectError("network disabled in tests")
+
+    monkeypatch.setattr(httpx, "Client", _DeadClient)
+    yield

tests/fixtures/openmeteo_bells.json

@@ -0,0 +1 @@
+{"hourly": [{"time": "2026-09-09T00:00", "wave_height": 2.98, "wave_period": 9.7, "wave_direction": 209, "wind_wave_height": 2.2, "swell_wave_height": 1.84, "swell_wave_direction": 219, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 12.3, "wind_direction_10m": 273, "wind_gusts_10m": 23.0}, {"time": "2026-09-09T01:00", "wave_height": 2.98, "wave_period": 9.9, "wave_direction": 209, "wind_wave_height": 2.08, "swell_wave_height": 1.88, "swell_wave_direction": 218, "swell_wave_period": 9.85, "sea_surface_temperature": 13.7, "wind_speed_10m": 13.7, "wind_direction_10m": 259, "wind_gusts_10m": 25.6}, {"time": "2026-09-09T02:00", "wave_height": 3.0, "wave_period": 10.15, "wave_direction": 210, "wind_wave_height": 1.94, "swell_wave_height": 1.92, "swell_wave_direction": 217, "swell_wave_period": 9.65, "sea_surface_temperature": 13.7, "wind_speed_10m": 20.6, "wind_direction_10m": 228, "wind_gusts_10m": 39.6}, {"time": "2026-09-09T03:00", "wave_height": 3.0, "wave_period": 10.4, "wave_direction": 210, "wind_wave_height": 1.82, "swell_wave_height": 1.96, "swell_wave_direction": 216, "swell_wave_period": 9.7, "sea_surface_temperature": 13.7, "wind_speed_10m": 27.8, "wind_direction_10m": 212, "wind_gusts_10m": 54.7}, {"time": "2026-09-09T04:00", "wave_height": 3.0, "wave_period": 10.65, "wave_direction": 210, "wind_wave_height": 1.72, "swell_wave_height": 2.12, "swell_wave_direction": 216, "swell_wave_period": 10.25, "sea_surface_temperature": 13.7, "wind_speed_10m": 28.8, "wind_direction_10m": 210, "wind_gusts_10m": 56.9}, {"time": "2026-09-09T05:00", "wave_height": 3.02, "wave_period": 10.9, "wave_direction": 211, "wind_wave_height": 1.64, "swell_wave_height": 2.3, "swell_wave_direction": 216, "swell_wave_period": 11.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 28.5, "wind_direction_10m": 211, "wind_gusts_10m": 55.8}, {"time": "2026-09-09T06:00", "wave_height": 3.02, "wave_period": 11.1, "wave_direction": 211, "wind_wave_height": 1.54, "swell_wave_height": 2.46, "swell_wave_direction": 216, "swell_wave_period": 11.7, "sea_surface_temperature": 13.7, "wind_speed_10m": 26.6, "wind_direction_10m": 207, "wind_gusts_10m": 55.8}, {"time": "2026-09-09T07:00", "wave_height": 3.04, "wave_period": 11.3, "wave_direction": 211, "wind_wave_height": 1.54, "swell_wave_height": 2.54, "swell_wave_direction": 216, "swell_wave_period": 11.85, "sea_surface_temperature": 13.7, "wind_speed_10m": 28.1, "wind_direction_10m": 204, "wind_gusts_10m": 54.7}, {"time": "2026-09-09T08:00", "wave_height": 3.04, "wave_period": 11.45, "wave_direction": 211, "wind_wave_height": 1.56, "swell_wave_height": 2.6, "swell_wave_direction": 216, "swell_wave_period": 11.75, "sea_surface_temperature": 13.7, "wind_speed_10m": 28.8, "wind_direction_10m": 203, "wind_gusts_10m": 65.5}, {"time": "2026-09-09T09:00", "wave_height": 3.06, "wave_period": 11.6, "wave_direction": 211, "wind_wave_height": 1.56, "swell_wave_height": 2.68, "swell_wave_direction": 216, "swell_wave_period": 11.6, "sea_surface_temperature": 13.7, "wind_speed_10m": 32.2, "wind_direction_10m": 203, "wind_gusts_10m": 70.2}, {"time": "2026-09-09T10:00", "wave_height": 3.08, "wave_period": 11.75, "wave_direction": 211, "wind_wave_height": 1.56, "swell_wave_height": 2.72, "swell_wave_direction": 216, "swell_wave_period": 11.45, "sea_surface_temperature": 13.7, "wind_speed_10m": 28.0, "wind_direction_10m": 201, "wind_gusts_10m": 70.2}, {"time": "2026-09-09T11:00", "wave_height": 3.08, "wave_period": 11.85, "wave_direction": 211, "wind_wave_height": 1.56, "swell_wave_height": 2.74, "swell_wave_direction": 215, "swell_wave_period": 11.25, "sea_surface_temperature": 13.7, "wind_speed_10m": 25.9, "wind_direction_10m": 205, "wind_gusts_10m": 64.1}, {"time": "2026-09-09T12:00", "wave_height": 3.1, "wave_period": 11.95, "wave_direction": 211, "wind_wave_height": 1.56, "swell_wave_height": 2.78, "swell_wave_direction": 215, "swell_wave_period": 11.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 26.6, "wind_direction_10m": 207, "wind_gusts_10m": 58.7}, {"time": "2026-09-09T13:00", "wave_height": 3.1, "wave_period": 12.05, "wave_direction": 211, "wind_wave_height": 1.48, "swell_wave_height": 2.82, "swell_wave_direction": 215, "swell_wave_period": 11.15, "sea_surface_temperature": 13.7, "wind_speed_10m": 26.7, "wind_direction_10m": 207, "wind_gusts_10m": 61.6}, {"time": "2026-09-09T14:00", "wave_height": 3.12, "wave_period": 12.15, "wave_direction": 210, "wind_wave_height": 1.42, "swell_wave_height": 2.86, "swell_wave_direction": 214, "swell_wave_period": 11.25, "sea_surface_temperature": 13.7, "wind_speed_10m": 26.3, "wind_direction_10m": 207, "wind_gusts_10m": 59.8}, {"time": "2026-09-09T15:00", "wave_height": 3.12, "wave_period": 12.3, "wave_direction": 210, "wind_wave_height": 1.34, "swell_wave_height": 2.9, "swell_wave_direction": 214, "swell_wave_period": 11.3, "sea_surface_temperature": 13.6, "wind_speed_10m": 26.1, "wind_direction_10m": 210, "wind_gusts_10m": 59.0}, {"time": "2026-09-09T16:00", "wave_height": 3.1, "wave_period": 12.45, "wave_direction": 210, "wind_wave_height": 1.04, "swell_wave_height": 2.96, "swell_wave_direction": 213, "swell_wave_period": 11.15, "sea_surface_temperature": 13.6, "wind_speed_10m": 23.2, "wind_direction_10m": 213, "wind_gusts_10m": 57.6}, {"time": "2026-09-09T17:00", "wave_height": 3.06, "wave_period": 12.65, "wave_direction": 210, "wind_wave_height": 0.76, "swell_wave_height": 3.0, "swell_wave_direction": 211, "swell_wave_period": 10.85, "sea_surface_temperature": 13.6, "wind_speed_10m": 23.8, "wind_direction_10m": 214, "wind_gusts_10m": 51.1}, {"time": "2026-09-09T18:00", "wave_height": 3.04, "wave_period": 12.8, "wave_direction": 210, "wind_wave_height": 0.46, "swell_wave_height": 3.06, "swell_wave_direction": 210, "swell_wave_period": 10.7, "sea_surface_temperature": 13.6, "wind_speed_10m": 22.5, "wind_direction_10m": 213, "wind_gusts_10m": 51.8}, {"time": "2026-09-09T19:00", "wave_height": 2.98, "wave_period": 12.9, "wave_direction": 210, "wind_wave_height": 0.44, "swell_wave_height": 3.02, "swell_wave_direction": 210, "swell_wave_period": 10.75, "sea_surface_temperature": 13.6, "wind_speed_10m": 23.3, "wind_direction_10m": 208, "wind_gusts_10m": 45.0}, {"time": "2026-09-09T20:00", "wave_height": 2.94, "wave_period": 13.0, "wave_direction": 211, "wind_wave_height": 0.4, "swell_wave_height": 2.96, "swell_wave_direction": 210, "swell_wave_period": 10.85, "sea_surface_temperature": 13.6, "wind_speed_10m": 23.8, "wind_direction_10m": 204, "wind_gusts_10m": 46.8}, {"time": "2026-09-09T21:00", "wave_height": 2.88, "wave_period": 13.05, "wave_direction": 211, "wind_wave_height": 0.38, "swell_wave_height": 2.92, "swell_wave_direction": 210, "swell_wave_period": 11.0, "sea_surface_temperature": 13.6, "wind_speed_10m": 24.0, "wind_direction_10m": 199, "wind_gusts_10m": 50.8}, {"time": "2026-09-09T22:00", "wave_height": 2.84, "wave_period": 13.05, "wave_direction": 211, "wind_wave_height": 0.42, "swell_wave_height": 2.86, "swell_wave_direction": 210, "swell_wave_period": 11.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 20.7, "wind_direction_10m": 199, "wind_gusts_10m": 47.2}, {"time": "2026-09-09T23:00", "wave_height": 2.78, "wave_period": 13.05, "wave_direction": 211, "wind_wave_height": 0.44, "swell_wave_height": 2.8, "swell_wave_direction": 211, "swell_wave_period": 11.15, "sea_surface_temperature": 13.7, "wind_speed_10m": 21.6, "wind_direction_10m": 193, "wind_gusts_10m": 41.8}, {"time": "2026-09-10T00:00", "wave_height": 2.74, "wave_period": 13.0, "wave_direction": 211, "wind_wave_height": 0.48, "swell_wave_height": 2.74, "swell_wave_direction": 211, "swell_wave_period": 11.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 20.7, "wind_direction_10m": 191, "wind_gusts_10m": 42.5}, {"time": "2026-09-10T01:00", "wave_height": 2.68, "wave_period": 12.95, "wave_direction": 211, "wind_wave_height": 0.44, "swell_wave_height": 2.68, "swell_wave_direction": 212, "swell_wave_period": 11.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 21.8, "wind_direction_10m": 188, "wind_gusts_10m": 43.6}, {"time": "2026-09-10T02:00", "wave_height": 2.64, "wave_period": 12.9, "wave_direction": 211, "wind_wave_height": 0.42, "swell_wave_height": 2.62, "swell_wave_direction": 212, "swell_wave_period": 10.95, "sea_surface_temperature": 13.7, "wind_speed_10m": 15.5, "wind_direction_10m": 193, "wind_gusts_10m": 42.5}, {"time": "2026-09-10T03:00", "wave_height": 2.58, "wave_period": 12.85, "wave_direction": 211, "wind_wave_height": 0.38, "swell_wave_height": 2.56, "swell_wave_direction": 213, "swell_wave_period": 10.9, "sea_surface_temperature": 13.7, "wind_speed_10m": 10.5, "wind_direction_10m": 217, "wind_gusts_10m": 29.9}, {"time": "2026-09-10T04:00", "wave_height": 2.54, "wave_period": 12.75, "wave_direction": 211, "wind_wave_height": 0.46, "swell_wave_height": 2.5, "swell_wave_direction": 213, "swell_wave_period": 11.0, "sea_surface_temperature": 13.8, "wind_speed_10m": 10.1, "wind_direction_10m": 235, "wind_gusts_10m": 18.4}, {"time": "2026-09-10T05:00", "wave_height": 2.5, "wave_period": 12.65, "wave_direction": 212, "wind_wave_height": 0.54, "swell_wave_height": 2.44, "swell_wave_direction": 213, "swell_wave_period": 11.15, "sea_surface_temperature": 13.8, "wind_speed_10m": 10.2, "wind_direction_10m": 260, "wind_gusts_10m": 18.4}, {"time": "2026-09-10T06:00", "wave_height": 2.46, "wave_period": 12.55, "wave_direction": 212, "wind_wave_height": 0.62, "swell_wave_height": 2.38, "swell_wave_direction": 213, "swell_wave_period": 11.25, "sea_surface_temperature": 13.8, "wind_speed_10m": 10.6, "wind_direction_10m": 268, "wind_gusts_10m": 19.8}, {"time": "2026-09-10T07:00", "wave_height": 2.4, "wave_period": 12.4, "wave_direction": 212, "wind_wave_height": 0.62, "swell_wave_height": 2.32, "swell_wave_direction": 213, "swell_wave_period": 11.15, "sea_surface_temperature": 13.8, "wind_speed_10m": 10.6, "wind_direction_10m": 251, "wind_gusts_10m": 19.4}, {"time": "2026-09-10T08:00", "wave_height": 2.36, "wave_period": 12.3, "wave_direction": 212, "wind_wave_height": 0.64, "swell_wave_height": 2.28, "swell_wave_direction": 213, "swell_wave_period": 11.0, "sea_surface_temperature": 13.8, "wind_speed_10m": 11.4, "wind_direction_10m": 219, "wind_gusts_10m": 26.3}, {"time": "2026-09-10T09:00", "wave_height": 2.3, "wave_period": 12.2, "wave_direction": 212, "wind_wave_height": 0.64, "swell_wave_height": 2.22, "swell_wave_direction": 213, "swell_wave_period": 10.8, "sea_surface_temperature": 13.7, "wind_speed_10m": 14.5, "wind_direction_10m": 202, "wind_gusts_10m": 33.5}, {"time": "2026-09-10T10:00", "wave_height": 2.24, "wave_period": 12.15, "wave_direction": 212, "wind_wave_height": 0.46, "swell_wave_height": 2.18, "swell_wave_direction": 213, "swell_wave_period": 10.55, "sea_surface_temperature": 13.7, "wind_speed_10m": 17.2, "wind_direction_10m": 193, "wind_gusts_10m": 40.3}, {"time": "2026-09-10T11:00", "wave_height": 2.18, "wave_period": 12.2, "wave_direction": 213, "wind_wave_height": 0.26, "swell_wave_height": 2.16, "swell_wave_direction": 213, "swell_wave_period": 10.3, "sea_surface_temperature": 13.7, "wind_speed_10m": 17.5, "wind_direction_10m": 188, "wind_gusts_10m": 41.8}, {"time": "2026-09-10T12:00", "wave_height": 2.12, "wave_period": 12.2, "wave_direction": 213, "wind_wave_height": 0.08, "swell_wave_height": 2.12, "swell_wave_direction": 213, "swell_wave_period": 10.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 16.4, "wind_direction_10m": 189, "wind_gusts_10m": 41.8}, {"time": "2026-09-10T13:00", "wave_height": 2.08, "wave_period": 12.2, "wave_direction": 213, "wind_wave_height": 0.06, "swell_wave_height": 2.08, "swell_wave_direction": 213, "swell_wave_period": 10.05, "sea_surface_temperature": 13.7, "wind_speed_10m": 14.6, "wind_direction_10m": 181, "wind_gusts_10m": 40.0}, {"time": "2026-09-10T14:00", "wave_height": 2.04, "wave_period": 12.25, "wave_direction": 213, "wind_wave_height": 0.06, "swell_wave_height": 2.02, "swell_wave_direction": 213, "swell_wave_period": 10.1, "sea_surface_temperature": 13.7, "wind_speed_10m": 16.1, "wind_direction_10m": 174, "wind_gusts_10m": 39.2}, {"time": "2026-09-10T15:00", "wave_height": 2.0, "wave_period": 12.25, "wave_direction": 213, "wind_wave_height": 0.04, "swell_wave_height": 1.98, "swell_wave_direction": 213, "swell_wave_period": 10.15, "sea_surface_temperature": 13.7, "wind_speed_10m": 18.1, "wind_direction_10m": 175, "wind_gusts_10m": 42.5}, {"time": "2026-09-10T16:00", "wave_height": 1.96, "wave_period": 12.25, "wave_direction": 213, "wind_wave_height": 0.02, "swell_wave_height": 1.94, "swell_wave_direction": 213, "swell_wave_period": 10.15, "sea_surface_temperature": 13.7, "wind_speed_10m": 17.5, "wind_direction_10m": 178, "wind_gusts_10m": 42.5}, {"time": "2026-09-10T17:00", "wave_height": 1.94, "wave_period": 12.2, "wave_direction": 214, "wind_wave_height": 0.02, "swell_wave_height": 1.92, "swell_wave_direction": 214, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 15.7, "wind_direction_10m": 181, "wind_gusts_10m": 40.0}, {"time": "2026-09-10T18:00", "wave_height": 1.9, "wave_period": 12.2, "wave_direction": 214, "wind_wave_height": 0.0, "swell_wave_height": 1.88, "swell_wave_direction": 214, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 16.7, "wind_direction_10m": 186, "wind_gusts_10m": 34.6}, {"time": "2026-09-10T19:00", "wave_height": 1.88, "wave_period": 12.2, "wave_direction": 214, "wind_wave_height": 0.0, "swell_wave_height": 1.84, "swell_wave_direction": 214, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 17.1, "wind_direction_10m": 197, "wind_gusts_10m": 33.1}, {"time": "2026-09-10T20:00", "wave_height": 1.84, "wave_period": 12.15, "wave_direction": 214, "wind_wave_height": 0.0, "swell_wave_height": 1.82, "swell_wave_direction": 215, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 13.5, "wind_direction_10m": 205, "wind_gusts_10m": 32.4}, {"time": "2026-09-10T21:00", "wave_height": 1.82, "wave_period": 12.15, "wave_direction": 214, "wind_wave_height": 0.0, "swell_wave_height": 1.78, "swell_wave_direction": 215, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 8.7, "wind_direction_10m": 220, "wind_gusts_10m": 24.8}, {"time": "2026-09-10T22:00", "wave_height": 1.8, "wave_period": 12.15, "wave_direction": 214, "wind_wave_height": 0.0, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.2, "sea_surface_temperature": 13.7, "wind_speed_10m": 7.3, "wind_direction_10m": 237, "wind_gusts_10m": 15.1}, {"time": "2026-09-10T23:00", "wave_height": 1.8, "wave_period": 12.15, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.25, "sea_surface_temperature": 13.7, "wind_speed_10m": 7.4, "wind_direction_10m": 252, "wind_gusts_10m": 12.2}, {"time": "2026-09-11T00:00", "wave_height": 1.78, "wave_period": 12.2, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.74, "swell_wave_direction": 215, "swell_wave_period": 10.3, "sea_surface_temperature": 13.8, "wind_speed_10m": 7.8, "wind_direction_10m": 266, "wind_gusts_10m": 13.7}, {"time": "2026-09-11T01:00", "wave_height": 1.78, "wave_period": 12.25, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.72, "swell_wave_direction": 215, "swell_wave_period": 10.35, "sea_surface_temperature": 13.8, "wind_speed_10m": 7.0, "wind_direction_10m": 270, "wind_gusts_10m": 13.3}, {"time": "2026-09-11T02:00", "wave_height": 1.78, "wave_period": 12.3, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.72, "swell_wave_direction": 215, "swell_wave_period": 10.4, "sea_surface_temperature": 13.9, "wind_speed_10m": 5.6, "wind_direction_10m": 268, "wind_gusts_10m": 12.2}, {"time": "2026-09-11T03:00", "wave_height": 1.78, "wave_period": 12.4, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.7, "swell_wave_direction": 215, "swell_wave_period": 10.45, "sea_surface_temperature": 13.9, "wind_speed_10m": 4.3, "wind_direction_10m": 272, "wind_gusts_10m": 10.1}, {"time": "2026-09-11T04:00", "wave_height": 1.78, "wave_period": 12.5, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.72, "swell_wave_direction": 215, "swell_wave_period": 10.5, "sea_surface_temperature": 14.0, "wind_speed_10m": 3.8, "wind_direction_10m": 287, "wind_gusts_10m": 8.3}, {"time": "2026-09-11T05:00", "wave_height": 1.8, "wave_period": 12.6, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.72, "swell_wave_direction": 215, "swell_wave_period": 10.55, "sea_surface_temperature": 14.1, "wind_speed_10m": 3.3, "wind_direction_10m": 292, "wind_gusts_10m": 9.0}, {"time": "2026-09-11T06:00", "wave_height": 1.8, "wave_period": 12.65, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.74, "swell_wave_direction": 215, "swell_wave_period": 10.6, "sea_surface_temperature": 14.1, "wind_speed_10m": 3.1, "wind_direction_10m": 301, "wind_gusts_10m": 9.0}, {"time": "2026-09-11T07:00", "wave_height": 1.8, "wave_period": 12.7, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.74, "swell_wave_direction": 215, "swell_wave_period": 10.65, "sea_surface_temperature": 14.1, "wind_speed_10m": 3.4, "wind_direction_10m": 302, "wind_gusts_10m": 9.4}, {"time": "2026-09-11T08:00", "wave_height": 1.8, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.02, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.7, "sea_surface_temperature": 14.0, "wind_speed_10m": 2.7, "wind_direction_10m": 298, "wind_gusts_10m": 10.1}, {"time": "2026-09-11T09:00", "wave_height": 1.8, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.02, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.7, "sea_surface_temperature": 14.0, "wind_speed_10m": 2.5, "wind_direction_10m": 180, "wind_gusts_10m": 11.2}, {"time": "2026-09-11T10:00", "wave_height": 1.8, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.02, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.7, "sea_surface_temperature": 14.0, "wind_speed_10m": 4.4, "wind_direction_10m": 145, "wind_gusts_10m": 16.2}, {"time": "2026-09-11T11:00", "wave_height": 1.78, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.65, "sea_surface_temperature": 13.9, "wind_speed_10m": 6.8, "wind_direction_10m": 130, "wind_gusts_10m": 20.9}, {"time": "2026-09-11T12:00", "wave_height": 1.78, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.65, "sea_surface_temperature": 13.9, "wind_speed_10m": 10.4, "wind_direction_10m": 132, "wind_gusts_10m": 28.1}, {"time": "2026-09-11T13:00", "wave_height": 1.76, "wave_period": 12.75, "wave_direction": 215, "wind_wave_height": 0.0, "swell_wave_height": 1.76, "swell_wave_direction": 215, "swell_wave_period": 10.65, "sea_surface_temperature": 13.9, "wind_speed_10m": 11.7, "wind_direction_10m": 139, "wind_gusts_10m": 31.7}, {"time": "2026-09-11T14:00", "wave_height": 1.76, "wave_period": 12.75, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.74, "swell_wave_direction": 216, "swell_wave_period": 10.7, "sea_surface_temperature": 13.8, "wind_speed_10m": 9.6, "wind_direction_10m": 140, "wind_gusts_10m": 31.3}, {"time": "2026-09-11T15:00", "wave_height": 1.74, "wave_period": 12.75, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.74, "swell_wave_direction": 216, "swell_wave_period": 10.7, "sea_surface_temperature": 13.8, "wind_speed_10m": 7.4, "wind_direction_10m": 137, "wind_gusts_10m": 27.0}, {"time": "2026-09-11T16:00", "wave_height": 1.72, "wave_period": 12.75, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.72, "swell_wave_direction": 216, "swell_wave_period": 10.7, "sea_surface_temperature": 13.8, "wind_speed_10m": 6.1, "wind_direction_10m": 137, "wind_gusts_10m": 22.0}, {"time": "2026-09-11T17:00", "wave_height": 1.7, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.7, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.8, "wind_speed_10m": 5.4, "wind_direction_10m": 143, "wind_gusts_10m": 18.7}, {"time": "2026-09-11T18:00", "wave_height": 1.68, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.68, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.8, "wind_speed_10m": 3.8, "wind_direction_10m": 155, "wind_gusts_10m": 14.8}, {"time": "2026-09-11T19:00", "wave_height": 1.66, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.66, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.8, "wind_speed_10m": 3.6, "wind_direction_10m": 153, "wind_gusts_10m": 6.1}, {"time": "2026-09-11T20:00", "wave_height": 1.64, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.64, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.7, "wind_speed_10m": 3.7, "wind_direction_10m": 157, "wind_gusts_10m": 5.4}, {"time": "2026-09-11T21:00", "wave_height": 1.62, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.0, "swell_wave_height": 1.62, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.7, "wind_speed_10m": 2.4, "wind_direction_10m": 144, "wind_gusts_10m": 5.4}, {"time": "2026-09-11T22:00", "wave_height": 1.6, "wave_period": 12.8, "wave_direction": 216, "wind_wave_height": 0.02, "swell_wave_height": 1.6, "swell_wave_direction": 216, "swell_wave_period": 10.75, "sea_surface_temperature": 13.7, "wind_speed_10m": 0.9, "wind_direction_10m": 180, "wind_gusts_10m": 4.0}, {"time": "2026-09-11T23:00", "wave_height": 1.58, "wave_period": 12.85, "wave_direction": 217, "wind_wave_height": 0.02, "swell_wave_height": 1.58, "swell_wave_direction": 217, "swell_wave_period": 10.75, "sea_surface_temperature": 13.7, "wind_speed_10m": 0.5, "wind_direction_10m": 315, "wind_gusts_10m": 1.8}], "daily": {"time": ["2026-09-09", "2026-09-10", "2026-09-11"], "sunrise": ["2026-09-09T06:34", "2026-09-10T06:32", "2026-09-11T06:30"], "sunset": ["2026-09-09T18:08", "2026-09-10T18:09", "2026-09-11T18:10"]}}

tests/test_breaks.py

@@ -0,0 +1,66 @@
+"""Offline tests for wavereader.breaks (load, validate, resolve, filter)."""
+
+import json
+
+import pytest
+
+from wavereader import breaks as br
+
+
+def test_load_breaks_count_and_sort():
+    breaks = br.load_breaks()
+    assert len(breaks) == 238
+    assert br.load_breaks.last_skipped == 0
+    keys = [(b["state"], b["region"], b["name"]) for b in breaks]
+    assert keys == sorted(keys)
+
+
+def test_all_records_validate_strict():
+    breaks = br.load_breaks(strict=True)  # raises on any invalid record
+    assert len(breaks) == 238
+
+
+def test_is_valid_break_rejects_garbage():
+    assert not br.is_valid_break({"name": "Nope"})
+    bells = br.resolve_break("Bells Beach")
+    assert bells is not None and br.is_valid_break(bells)
+
+
+def test_resolve_break_exact_and_case_insensitive():
+    assert br.resolve_break("Bells Beach")["region"] == "Surf Coast"
+    assert br.resolve_break("bells beach")["name"] == "Bells Beach"
+    assert br.resolve_break("BELLS BEACH", region="surf coast")["name"] == "Bells Beach"
+
+
+def test_resolve_break_fuzzy_and_scoped():
+    assert br.resolve_break("bells")["name"] == "Bells Beach"
+    # Unknown region falls back to the global pool.
+    assert br.resolve_break("Bells Beach", region="No Such Region")["name"] == "Bells Beach"
+    assert br.resolve_break("Bells Beach", region="Surf Coast")["name"] == "Bells Beach"
+    assert br.resolve_break("definitely not a break xyz") is None
+    assert br.resolve_break("") is None
+
+
+def test_resolve_break_region_disambiguates():
+    pool = [
+        {"name": "The Pass", "region": "North", "state": "NSW"},
+        {"name": "The Pass", "region": "South", "state": "NSW"},
+    ]
+    assert br.resolve_break("The Pass", region="south", breaks=pool)["region"] == "South"
+
+
+def test_filter_breaks():
+    breaks = br.load_breaks()
+    vic = br.filter_breaks(breaks, state="victoria")
+    assert vic and all(b["state"] == "Victoria" for b in vic)
+    surf_coast = br.filter_breaks(breaks, region="Surf Coast")
+    assert surf_coast and all(b["region"] == "Surf Coast" for b in surf_coast)
+    assert br.filter_breaks(breaks, state="All") == breaks
+    assert br.filter_breaks(breaks, skill="advanced")
+
+
+def test_get_coords():
+    lat, lng = br.get_coords(br.resolve_break("Bells Beach"))
+    assert lat == pytest.approx(-38.3667)
+    assert lng == pytest.approx(144.2833)
+    assert br.get_coords({}) == (None, None)

tests/test_openmeteo.py

@@ -0,0 +1,119 @@
+"""Offline tests for wavereader.openmeteo (cache, merge, offset contract)."""
+
+import json
+import time
+from pathlib import Path
+
+import pytest
+
+from wavereader import openmeteo as om
+
+FIXTURE = Path(__file__).parent / "fixtures" / "openmeteo_bells.json"
+
+
+def _use_tmp_cache(monkeypatch, tmp_path):
+    monkeypatch.setattr(om, "CACHE_DIR", tmp_path)
+
+
+# ---- Fetch contract ----
+
+def test_marine_fields_include_swell_components():
+    assert "swell_wave_direction" in om.MARINE_HOURLY_FIELDS
+    assert "swell_wave_period" in om.MARINE_HOURLY_FIELDS
+    assert "swell_wave_height" in om.MARINE_HOURLY_FIELDS
+
+
+def test_cache_version_bumped():
+    # Old-shape (v2, no swell_* fields) cache must never serve as fresh.
+    assert om.CACHE_VERSION == 3
+
+
+# ---- Seaward offset (Worker B reuse contract) ----
+
+@pytest.mark.parametrize(
+    ("lat", "lon", "expected"),
+    [
+        (-28.17, 153.55, (0.0, 0.13)),    # east coast → east
+        (-33.80, 115.00, (0.0, -0.13)),   # west coast → west
+        (-35.00, 138.00, (-0.13, 0.0)),   # south coast SA → south
+        (-38.37, 144.28, (-0.13, 0.0)),   # Surf Coast VIC → south
+        (-42.90, 147.30, (-0.13, 0.0)),   # Tasmania → south
+    ],
+)
+def test_seaward_offset_directions(lat, lon, expected):
+    assert om._seaward_offset(lat, lon) == pytest.approx(expected)
+
+
+# ---- Merge ----
+
+def test_build_normalized_merges_and_carries_daily():
+    marine = {
+        "hourly": {
+            "time": ["2026-09-01T00:00", "2026-09-01T01:00"],
+            "wave_height": [1.2, 1.3],
+            "swell_wave_height": [1.0, 1.1],
+            "swell_wave_direction": [180.0, 185.0],
+            "swell_wave_period": [12.0, 12.5],
+        }
+    }
+    weather = {
+        "hourly": {
+            "time": ["2026-09-01T00:00", "2026-09-01T01:00"],
+            "wind_speed_10m": [10.0, 40.0],
+            "wind_direction_10m": [0.0, 90.0],
+            "wind_gusts_10m": [15.0, 50.0],
+        },
+        "daily": {
+            "time": ["2026-09-01"],
+            "sunrise": ["2026-09-01T06:00"],
+            "sunset": ["2026-09-01T18:00"],
+        },
+    }
+    out = om._build_normalized(marine, weather)
+    assert len(out["hourly"]) == 2
+    assert out["hourly"][0]["swell_wave_direction"] == 180.0
+    assert out["hourly"][0]["wind_speed_10m"] == 10.0
+    assert out["daily"]["sunrise"] == ["2026-09-01T06:00"]
+    assert out["daily"]["sunset"] == ["2026-09-01T18:00"]
+
+
+# ---- Disk cache, fully offline ----
+
+def test_get_forecast_serves_fresh_cache_without_network(monkeypatch, tmp_path):
+    _use_tmp_cache(monkeypatch, tmp_path)
+    payload = {"hourly": [{"time": "2026-09-01T12:00", "wave_height": 1.0}], "daily": {}}
+    om._save_cache(-38.37, 144.28, 3, payload)
+    assert om.get_forecast(-38.37, 144.28, days=3) == payload
+
+
+def test_get_forecast_falls_back_to_stale_cache(monkeypatch, tmp_path):
+    _use_tmp_cache(monkeypatch, tmp_path)
+    payload = {"hourly": [{"time": "2026-09-01T12:00", "wave_height": 2.0}]}
+    path = om._cache_path(-38.37, 144.28, 3)
+    tmp_path.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"fetched_at": 0.0, "data": payload}))
+    # httpx.Client raises (conftest) → stale fallback, not an error.
+    assert om.get_forecast(-38.37, 144.28, days=3) == payload
+
+
+def test_get_forecast_raises_with_no_cache_and_no_network(monkeypatch, tmp_path):
+    _use_tmp_cache(monkeypatch, tmp_path)
+    with pytest.raises(Exception):
+        om.get_forecast(-38.37, 144.28, days=3)
+
+
+def test_cache_key_embeds_version():
+    assert om._cache_key(-38.37, 144.28, 3).startswith(f"v{om.CACHE_VERSION}_")
+
+
+# ---- Recorded live fixture ----
+
+def test_recorded_bells_fixture_shape():
+    fc = json.loads(FIXTURE.read_text())
+    assert len(fc["hourly"]) == 72
+    first = fc["hourly"][0]
+    for field in ("swell_wave_height", "swell_wave_direction", "swell_wave_period",
+                  "wave_height", "wind_speed_10m", "wind_direction_10m"):
+        assert field in first, f"fixture missing {field}"
+    assert "sunrise" in fc["daily"] and "sunset" in fc["daily"]
+    assert len(fc["daily"]["time"]) >= 3

tests/test_scoring.py

@@ -0,0 +1,259 @@
+"""Offline tests for scoring v2 (arc distance, logistic wind, daylight,
+p75 summaries, surfable-hours rank, swell preference, monotonicity)."""
+
+import pytest
+
+from wavereader import scoring as sc
+from wavereader.scoring import (
+    daily_summary,
+    enriched_to_scoring_spot,
+    normalize_skill,
+    rank_spots,
+    score_hour,
+    score_week,
+    wind_cap,
+)
+
+
+def _spot(**over):
+    spot = {
+        "name": "Test",
+        "region": "Test Coast",
+        "break_type": "point",
+        "ideal_swell": {"direction": "SW/S/SSW", "size_ft_min": 4.0, "size_ft_max": 12.0},
+        "ideal_wind": {"direction": "N", "type": "offshore"},
+    }
+    for k, v in over.items():
+        if isinstance(v, dict):
+            spot[k] = {**spot[k], **v}
+        else:
+            spot[k] = v
+    return spot
+
+
+def _row(time="2026-09-01T12:00", **over):
+    row = {
+        "time": time,
+        "wave_height": 1.5,
+        "wave_period": 12.0,
+        "wave_direction": 180.0,
+        "wind_speed_10m": 9.0,
+        "wind_direction_10m": 0.0,
+    }
+    row.update(over)
+    return row
+
+
+def _frame(times, **over):
+    return {"hourly": [_row(t, **over) for t in times]}
+
+
+# ---- Adapter shaping ----
+
+def test_enriched_to_scoring_spot_carries_wind_type_and_break_type():
+    b = {
+        "name": "Bells Beach", "region": "Surf Coast", "breakType": "point",
+        "idealSwell": {"direction": ["SW", "S"], "sizeRangeFt": {"min": 4, "max": 12}},
+        "idealWind": {"direction": ["N"], "type": "offshore"},
+        "skillLevel": "advanced",
+    }
+    spot = enriched_to_scoring_spot(b)
+    assert spot["ideal_swell"]["direction"] == "SW/S"
+    assert spot["ideal_wind"] == {"direction": "N", "type": "offshore"}
+    assert spot["break_type"] == "point"
+
+
+def test_normalize_skill():
+    assert normalize_skill("pro-only") == "expert"
+    assert normalize_skill("BEGINNER") == "beginner"
+    assert normalize_skill("made-up") == "intermediate"
+    assert normalize_skill(None) == "intermediate"
+
+
+# ---- Direction arc (not cyclic mean) ----
+
+def test_direction_arc_peaks_at_each_ideal_bearing():
+    spot = _spot(ideal_swell={"direction": "E/SE"})
+    at_e = sc._score_swell_direction(90.0, spot)
+    at_se = sc._score_swell_direction(135.0, spot)
+    at_mid = sc._score_swell_direction(112.5, spot)  # cyclic mean would peak here
+    assert at_e == pytest.approx(10.0)
+    assert at_se == pytest.approx(10.0)
+    assert at_mid < 9.0  # dip between the two ideal bearings
+
+
+def test_direction_arc_min_distance():
+    # Bells-like arc: S is ideal, N is ~opposite → near zero.
+    spot = _spot()
+    assert sc._score_swell_direction(180.0, spot) == pytest.approx(10.0)
+    assert sc._score_swell_direction(0.0, spot) < 1.0
+
+
+def test_dir_to_deg_still_available_legacy():
+    assert sc._dir_to_deg("E") == pytest.approx(90.0)
+
+
+# ---- Wind cap table + logistic roll-off ----
+
+@pytest.mark.parametrize(
+    ("wind_type", "expected"),
+    [("offshore", 18.0), ("cross-shore", 12.0), ("onshore", 8.0), ("light/variable", 10.0)],
+)
+def test_wind_cap_by_type(wind_type, expected):
+    spot = _spot(ideal_wind={"direction": "N", "type": wind_type})
+    assert wind_cap(spot, "expert") == pytest.approx(expected)
+
+
+def test_wind_cap_bounded_by_skill_profile():
+    spot = _spot()  # offshore → 18, but beginners cap at 12
+    assert wind_cap(spot, "beginner") == pytest.approx(12.0)
+
+
+def test_wind_speed_is_smooth_not_a_cliff():
+    spot = _spot()  # offshore cap 18 for advanced (profile max 25)
+    just_under = sc._score_wind(17.0, 0.0, spot, "advanced")
+    at_cap = sc._score_wind(18.0, 0.0, spot, "advanced")
+    just_over = sc._score_wind(19.0, 0.0, spot, "advanced")
+    # No 10→0 cliff: adjacent knots differ by small steps.
+    assert abs(just_under - at_cap) < 2.0
+    assert abs(at_cap - just_over) < 2.0
+    assert just_under > at_cap > just_over
+    # Glassy air still excellent; howling onshore air scores ~0
+    # (speed ~0 and direction 0 averaged: the composite, not speed alone).
+    glassy = sc._score_wind(2.0, 0.0, spot, "advanced")
+    howling_onshore = sc._score_wind(40.0, 180.0, spot, "advanced")
+    assert glassy > 9.0
+    assert howling_onshore < 1.0
+
+
+def test_wind_monotonic_beyond_cap_property():
+    """Stronger offshore-beyond-cap wind scores <= lighter wind."""
+    spot = _spot()
+    scores = [sc._score_wind(ws, 0.0, spot, "advanced") for ws in (18, 20, 25, 30)]
+    assert scores == sorted(scores, reverse=True)
+
+
+# ---- Swell-component preference ----
+
+def test_score_week_prefers_swell_fields():
+    spot = _spot()
+    generic = {"hourly": [_row()]}
+    swell_same = {"hourly": [_row(
+        swell_wave_height=1.5, swell_wave_period=12.0, swell_wave_direction=180.0,
+    )]}
+    assert score_week(generic, spot) == score_week(swell_same, spot)
+
+
+def test_score_week_uses_swell_values_not_generic():
+    spot = _spot()
+    # Generic aggregate is flat small; the real swell is overhead-high.
+    frame = {"hourly": [_row(
+        wave_height=1.5, wave_period=12.0, wave_direction=180.0,
+        swell_wave_height=0.2, swell_wave_period=5.0, swell_wave_direction=0.0,
+    )]}
+    (got,) = score_week(frame, spot, daylight_only=False)
+    assert got["wave_height_m"] == pytest.approx(0.2)
+    assert got["wave_period_s"] == pytest.approx(5.0)
+    assert got["wave_direction_deg"] == pytest.approx(0.0)
+
+
+# ---- Daylight filter ----
+
+def _sunny_frame():
+    return {
+        "hourly": [
+            _row("2026-09-01T02:00"),  # night
+            _row("2026-09-01T12:00"),  # day
+            _row("2026-09-01T23:00"),  # night
+        ],
+        "daily": {
+            "time": ["2026-09-01"],
+            "sunrise": ["2026-09-01T06:00"],
+            "sunset": ["2026-09-01T18:00"],
+        },
+    }
+
+
+def test_score_week_drops_night_hours_by_default():
+    hours = score_week(_sunny_frame(), _spot())
+    assert [h["time"] for h in hours] == ["2026-09-01T12:00"]
+
+
+def test_score_week_daylight_opt_out_keeps_all():
+    hours = score_week(_sunny_frame(), _spot(), daylight_only=False)
+    assert len(hours) == 3
+
+
+def test_score_week_without_daily_keeps_all():
+    hours = score_week(_frame(["2026-09-01T02:00", "2026-09-01T12:00"]), _spot())
+    assert len(hours) == 2
+
+
+# ---- Daily summary (p75) ----
+
+def test_daily_summary_is_p75():
+    hours = [
+        {"time": "2026-09-01T09:00", "score": 2.0},
+        {"time": "2026-09-01T10:00", "score": 4.0},
+        {"time": "2026-09-01T11:00", "score": 6.0},
+        {"time": "2026-09-01T12:00", "score": 8.0},
+        {"time": "2026-09-02T12:00", "score": 9.0},
+    ]
+    (d1, d2) = daily_summary(hours)
+    assert d1["date"] == "2026-09-01"
+    assert d1["p75"] == pytest.approx(6.5)  # linear interp between 6 and 8
+    assert d1["best"] == pytest.approx(8.0)
+    assert d1["n"] == 4
+    assert d1["surfable_hours"] == 2
+    assert d2["p75"] == pytest.approx(9.0)
+
+
+# ---- Rank by surfable hours ----
+
+def test_rank_spots_prefers_surfable_hours_over_single_best():
+    alto = _spot(name="Alto", region="R")
+    bajo = _spot(name="Bajo", region="R")
+    # Alto: one epic hour, otherwise junk. Bajo: many decent hours.
+    alto_frame = {"hourly": [
+        _row("2026-09-01T12:00", wave_height=1.8, wave_period=14.0,
+             wind_speed_10m=5.0, wind_direction_10m=0.0),
+        *[_row(f"2026-09-0{d}T12:00", wave_height=0.1, wave_period=4.0,
+               wind_speed_10m=80.0, wind_direction_10m=180.0) for d in (2, 3, 4, 5)],
+    ]}
+    bajo_frame = {"hourly": [
+        _row(f"2026-09-0{d}T12:00", wave_height=1.8, wave_period=14.0,
+             wind_speed_10m=5.0, wind_direction_10m=0.0) for d in (1, 2, 3, 4, 5)
+    ]}
+    ranked = rank_spots({("Alto", "R"): alto_frame, ("Bajo", "R"): bajo_frame}, [alto, bajo])
+    assert ranked[0]["name"] == "Bajo"
+    assert ranked[0]["surfable_hours"] > ranked[1]["surfable_hours"]
+    assert "best_time" in ranked[0] and "best_hour" in ranked[0]
+
+
+def test_rank_spots_skips_missing_forecasts():
+    ranked = rank_spots({}, [_spot(name="Ghost", region="R")])
+    assert ranked == []
+
+
+# ---- Monotonicity properties ----
+
+def test_bigger_swell_in_window_scores_ge(tmp_path=None):
+    """Bigger swell inside the ideal window scores >= smaller swell."""
+    spot = _spot()
+    scores = [
+        score_hour(h, 14.0, 5.0, 0.0, spot, wave_direction_deg=180.0, skill_level="advanced")["score"]
+        for h in (0.8, 1.2, 1.6, 2.0)
+    ]
+    assert scores == sorted(scores)
+
+
+def test_score_hour_rejects_bad_skill():
+    with pytest.raises(ValueError):
+        score_hour(1.5, 12.0, 5.0, 0.0, _spot(), skill_level="kook")
+
+
+def test_rank_spots_this_week_alias():
+    frame = _frame(["2026-09-01T12:00"])
+    spot = _spot()
+    key = (spot["name"], spot["region"])
+    assert sc.rank_spots_this_week({key: frame}, [spot]) == rank_spots({key: frame}, [spot])

tests/test_seafloor.py

@@ -0,0 +1,123 @@
+"""Offline tests for wavereader.seafloor (slope math, None-skipping).
+
+All grids are synthetic — no network. ``get_grid`` is monkeypatched where
+``get_seafloor`` is exercised.
+"""
+
+import math
+
+import pytest
+
+from wavereader import seafloor as sf
+
+
+def _synthetic_grid(n=5, center=(-38.37, 144.28), ramp=None, none_at=()):
+    """Build a grid via the real _deg_offsets; elev optional ramp fn(i, j)."""
+    dlat, dlon = sf._deg_offsets(center[0], 1.2, n)
+    lats = [round(center[0] + d, 5) for d in dlat]
+    lngs = [round(center[1] + d, 5) for d in dlon]
+    elev = []
+    for i in range(n):
+        for j in range(n):
+            v = float(ramp(i, j)) if ramp else -10.0
+            elev.append(None if (i, j) in none_at else v)
+    return {
+        "lats": lats, "lngs": lngs, "elev": elev, "n": n,
+        "radius_km": 1.2, "dataset": "test",
+        "center": {"lat": center[0], "lng": center[1]},
+    }
+
+
+# ---- Step math ----
+
+def _degree_grid(n=5, center=(-38.37, 144.28), step_deg=0.01, ramp=None, none_at=()):
+    """Grid with EQUAL degree spacing on both axes (not square in km).
+
+    This is the case the v1 slope bug got wrong: at lat -38°, 0.01° of
+    longitude is only ~0.87 km while 0.01° of latitude is 1.11 km.
+    """
+    lats = [round(center[0] + (i - n // 2) * step_deg, 5) for i in range(n)]
+    lngs = [round(center[1] + (j - n // 2) * step_deg, 5) for j in range(n)]
+    elev = []
+    for i in range(n):
+        for j in range(n):
+            v = float(ramp(i, j)) if ramp else -10.0
+            elev.append(None if (i, j) in none_at else v)
+    return {
+        "lats": lats, "lngs": lngs, "elev": elev, "n": n,
+        "radius_km": 1.2, "dataset": "test",
+        "center": {"lat": center[0], "lng": center[1]},
+    }
+
+
+# ---- Step math ----
+
+def test_lon_step_scaled_by_cos_lat():
+    grid = _degree_grid()
+    lat_step, lon_step = sf._grid_steps_km(grid)
+    assert lat_step == pytest.approx(0.01 * 111.0, rel=1e-6)
+    assert lon_step == pytest.approx(0.01 * 111.0 * math.cos(math.radians(-38.37)), rel=1e-6)
+    assert lon_step < lat_step  # meridians converge away from the equator
+
+
+def test_square_grid_steps_approx_equal():
+    # Grids built by _deg_offsets are square in km by construction;
+    # per-axis derivation must recover (approximately) equal steps.
+    grid = _synthetic_grid()
+    lat_step, lon_step = sf._grid_steps_km(grid)
+    assert lat_step == pytest.approx(0.6, abs=0.02)
+    assert lon_step == pytest.approx(0.6, abs=0.02)
+
+
+def test_lon_ramp_scores_steeper_than_equal_lat_ramp():
+    """Equal m-per-degree ramps on a degree grid: E–W must score steeper.
+
+    At lat -38° the same 5 m/cell over 0.01° is a steeper gradient along
+    longitude (~0.87 km) than along latitude (1.11 km). The v1 bug (lat
+    step reused for both axes) reported them equal.
+    """
+    ramp_ew = lambda i, j: -10.0 - 5.0 * j   # varies along longitude
+    ramp_ns = lambda i, j: -10.0 - 5.0 * i   # varies along latitude
+    ew = sf.analyze_grid(_degree_grid(ramp=ramp_ew))["stats"]
+    ns = sf.analyze_grid(_degree_grid(ramp=ramp_ns))["stats"]
+    assert ew["max_slope_m_per_km"] == pytest.approx(5.0 / (0.01 * 111.0 * math.cos(math.radians(-38.37))), rel=0.05)
+    assert ns["max_slope_m_per_km"] == pytest.approx(5.0 / (0.01 * 111.0), rel=0.05)
+    assert ew["max_slope_m_per_km"] > ns["max_slope_m_per_km"] * 1.1
+
+
+# ---- None handling ----
+
+def test_analyze_grid_skips_none_cells():
+    grid = _synthetic_grid(none_at={(0, 0), (2, 2), (4, 4)})
+    out = sf.analyze_grid(grid)
+    assert "stats" in out
+    assert out["stats"]["points"] == 25 - 3
+    assert out["stats"]["center_elev_m"] is None  # centre cell is None
+
+
+def test_analyze_grid_empty():
+    assert sf.analyze_grid({"elev": [None, None], "n": 2}) == {"error": "Empty seafloor grid"}
+    assert sf.analyze_grid({"elev": [], "n": 3}) == {"error": "Empty seafloor grid"}
+
+
+def test_analyze_grid_stats_shape():
+    out = sf.analyze_grid(_synthetic_grid())
+    stats = out["stats"]
+    assert stats["shelf_class"] in (
+        "steep reef edge / drop-off",
+        "moderately sloping reef/shelf",
+        "shallow, gently shelving platform",
+        "gradual sandy shelf",
+    )
+    assert "Seafloor" in out["markdown"]
+
+
+# ---- get_seafloor without network ----
+
+def test_get_seafloor_uses_grid(monkeypatch):
+    grid = _synthetic_grid()
+    monkeypatch.setattr(sf, "get_grid", lambda *a, **k: grid)
+    out = sf.get_seafloor(-38.37, 144.28)
+    assert out["grid"] is grid
+    assert out["stats"]["points"] == 25
+    assert isinstance(out["analysis"], str)

uv.lock

@@ -38,6 +38,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
 ]
 
+[[package]]
+name = "attrs"
+version = "26.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" },
+]
+
 [[package]]
 name = "audioop-lts"
 version = "0.2.2"
@@ -456,6 +465,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/57/b0/0e52c878c53f245edd3a11020f20979b3f490f245af532c7cae3027754b5/idna-3.19-py3-none-any.whl", hash = "sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4", size = 68550, upload-time = "2026-08-18T05:14:22.343Z" },
 ]
 
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
 [[package]]
 name = "jinja2"
 version = "3.1.6"
@@ -504,6 +522,33 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7c/a2/d88de6d313d734a544a7901353ad5db67cb38dcfcd91713b7979dafc345d/jiter-0.16.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0fa25b09b13075c46f5bc174f2690525a925a4fc2f7c82969a2bbabff22386ce", size = 190516, upload-time = "2026-06-29T13:04:38.004Z" },
 ]
 
+[[package]]
+name = "jsonschema"
+version = "4.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.2.0"
@@ -763,6 +808,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e0/2f/6f492108d9955bac97979d9949c1b35eab30fc630b1f22bbdd2c7cacbab4/plotly-7.0.0-py3-none-any.whl", hash = "sha256:78cbf7bd06d1b05bb3b8ec1b709864695229b55151b6f7530fbf55517ead6fdd", size = 9052859, upload-time = "2026-08-25T17:47:24.689Z" },
 ]
 
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
 [[package]]
 name = "pydantic"
 version = "2.13.5"
@@ -837,6 +891,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" },
 ]
 
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -902,6 +972,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
 ]
 
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+]
+
 [[package]]
 name = "requests"
 version = "2.34.2"
@@ -930,6 +1013,72 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
 ]
 
+[[package]]
+name = "rpds-py"
+version = "2026.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/aa/2a/9618a122aeb2a169a28b03889a2995fe297588964333d4a7d67bdf46e147/rpds_py-2026.6.3.tar.gz", hash = "sha256:1cebd1337c242e4ec2293e541f712b2da849b29f48f0c293684b71c0632625d4", size = 64051, upload-time = "2026-06-30T07:17:53.009Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b6/36/7fbe9dcdaf857fb3f63c2a2284b62492d95f5e8334e947e5fb6e7f68c9be/rpds_py-2026.6.3-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:931908d9fc855d8f74783377822be318edb6dcb19e47169dc038f9a1bf60b06e", size = 344510, upload-time = "2026-06-30T07:15:57.921Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/54/f785cc3d3f60839ca57a5af4927a9f347b07b2799c373fc20f7949f87c7e/rpds_py-2026.6.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d7469697dce35be237db177d42e2a2ee26e6dcc5fc052078a6fefabd288c6edd", size = 339495, upload-time = "2026-06-30T07:15:59.238Z" },
+    { url = "https://files.pythonhosted.org/packages/63/ef/d4cdaf309e6b095b43597103cf8c0b951d6cca2acce68c474f75ec12e0c7/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bcfbcf66006befb9fd2aeaa9e01feaf881b4dc330a02ba07d2322b1c11be7b5d", size = 369454, upload-time = "2026-06-30T07:16:01.021Z" },
+    { url = "https://files.pythonhosted.org/packages/96/4a/9559a68b7ee15db09d7981212e8c2e219d2a1d6d4faa0391d813c3496a36/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:847927daf4cffbd4e90e42bc890069897101edd015f956cb8721b3473372edda", size = 374583, upload-time = "2026-06-30T07:16:02.287Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/75/8964aa7d2c6e8ac43eba8eb6e6b0fdda1f46d39f2fc3e6aa9f2cb17f485d/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:aca6c1ef08a82bfe327cc156da694660f599923e2e6665b6d81c9c2d0ac9ffc8", size = 492919, upload-time = "2026-06-30T07:16:03.723Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/97/6908094ac804115e65aedfd90f1b5fee4eebebd3f6c4cfc5419939267565/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ae50181a047c871561212bb97f7932a2d45fb53e947bd9b57ebad85b529cbc53", size = 383725, upload-time = "2026-06-30T07:16:05.305Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/9c/0d1fdc2e7aba23e290d603bc494e97bd205bae262ce33c6b32a69768ed5e/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:dc319e5a1de4b6913aac94bf6a2f9e847371e0a140a43dd4991db1a09bc2d504", size = 367255, upload-time = "2026-06-30T07:16:07.086Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/fe/f0209ca4a9ed074bc8acb44dfd0e81c3122e94c9689f5645b7973a866719/rpds_py-2026.6.3-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:e4316bf32babbed84e691e352faf967ce2f0f024174a8643c37c94a1080374fc", size = 379060, upload-time = "2026-06-30T07:16:08.525Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/8d/f1cc54c616b9d8897de8738aac148d20afca93f68187475fe194d09a71b9/rpds_py-2026.6.3-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8c6e5a2f750cc71c3e3b11d71661f21d6f9bc6cebc6564b1466417a1ec03ec77", size = 395960, upload-time = "2026-06-30T07:16:09.989Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/04/aafff00f73aeca2945f734f1d483c64ab8f472d0864ab02377fd8e89c3b2/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:4470ce197d4090875cf6affbf1f853338387428df97c4fb7b7106317b8214698", size = 545356, upload-time = "2026-06-30T07:16:11.816Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/cc/e229663b9e4ddac5a4acbe9085dd80a71af2a5d356b8b39d6bff233f24b0/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ea964164cc9afa72d4d9b23cc28dafae93693c0a53e0b42acbff15b22c3f9ddd", size = 612319, upload-time = "2026-06-30T07:16:13.586Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/7a/8a0e6d3e6cd066af108b71b43122c3fe158dd9eb86acac626593a2582eb1/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:639c8929aa0afe81be836b04de888460d6bed38b9c54cfc18da8f6bfabf5af5d", size = 573508, upload-time = "2026-06-30T07:16:15.23Z" },
+    { url = "https://files.pythonhosted.org/packages/87/03/2a69ab618a789cf6cf85c86bb844c62d090e700ab1a2aa676b3741b6c516/rpds_py-2026.6.3-cp314-cp314-win32.whl", hash = "sha256:882076c00c0a608b131187055ddc5ae29f2e7eaf870d6168980420d58528a5c8", size = 202504, upload-time = "2026-06-30T07:16:16.893Z" },
+    { url = "https://files.pythonhosted.org/packages/85/62/a3892ba945f4e24c78f352e5de3c7620d8479f73f211406a97263d13c7d2/rpds_py-2026.6.3-cp314-cp314-win_amd64.whl", hash = "sha256:0be972be84cfcaf46c8c6edf690ca0f154ac17babf1f6a955a51579b34ad2dc5", size = 220380, upload-time = "2026-06-30T07:16:18.108Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/e7/c2bd44dc831931815ad11ebb5f430b5a0a4d3caa9de837107876c30c3432/rpds_py-2026.6.3-cp314-cp314-win_arm64.whl", hash = "sha256:2a9c6f195058cb45335e8cc3802745c603d716eb96bc9625950c1aac71c0c703", size = 215976, upload-time = "2026-06-30T07:16:19.654Z" },
+    { url = "https://files.pythonhosted.org/packages/79/9c/fff7b74bce9a091ec9a012a03f9ff5f69364eaf9451060dfc4486da2ffdd/rpds_py-2026.6.3-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:f90938e92afda60266da758ee7d363447f7f0138c9559f9e1811629580582d90", size = 346840, upload-time = "2026-06-30T07:16:21.268Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/44/77bcb1168b33704908295533d27f10eb811e9e3e193e8993dc99572211d3/rpds_py-2026.6.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ec829541c45bca16e61c7ae50c20501f213605beb75d1aba91a6ee37fbbb56a4", size = 340282, upload-time = "2026-06-30T07:16:22.875Z" },
+    { url = "https://files.pythonhosted.org/packages/87/3c/7a9081c7c9e645b39efe19e4ffbeccd80add246327cd9b888aecffd72317/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:afd70d95892096cdb26f15a00c45907b17817577aa8d1c76b2dcc2788391f9e9", size = 370403, upload-time = "2026-06-30T07:16:24.415Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/69/af47021eb7dad6ff3396cb001c08f0f3c4d06c20253f75be6421a59fe6b7/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:29dfa0533a5d4c94d4dfa1b694fcb56c9c63aad8330ffdd816fd225d0a7a162f", size = 376055, upload-time = "2026-06-30T07:16:26.111Z" },
+    { url = "https://files.pythonhosted.org/packages/81/fc/a3bcf517084396a6dd258c592567a3c011ba4557f2fde23dceaf26e74f2e/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:af05d726809bff6b141be124d4c7ce998f9c9c7f30edb1f46c07aa103d540b41", size = 494419, upload-time = "2026-06-30T07:16:27.596Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/eb/13d529d1788135425c7bf207f8463458ca5d92e43f3f701365b83e9dffc1/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9826217f048f620d9a712672818bf231442c1b35d96b227a07eabd11b4bb6945", size = 384848, upload-time = "2026-06-30T07:16:29.183Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/f4/b7ac49f30013aba8f7b9566b1dd07e81de95e708c1374b7bacc5b9bc5c9c/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:536bceea4fa4acf7e1c61da2b5786304367c816c8895be71b8f537c480b0ea1f", size = 371369, upload-time = "2026-06-30T07:16:30.912Z" },
+    { url = "https://files.pythonhosted.org/packages/31/86/6260bafa622f788b07ddec0e52d810305c8b9b0b8c27f58a2ab04bf62b4f/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:bc0011654b91cc4fb2ae701bec0a0ba1e552c0714247fa7af6c59e0ccfa3a4e1", size = 379673, upload-time = "2026-06-30T07:16:32.486Z" },
+    { url = "https://files.pythonhosted.org/packages/19/c3/03f1ee79a047b48daeca157c89a18509cde22b6b951d642b9b0af1be660a/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:539d75de9e0d536c84ff18dfeb805398e58227001ce09231a26a08b9aed1ee0e", size = 397500, upload-time = "2026-06-30T07:16:34.471Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/95/8ed0cd8c377dca12aea498f119fe639fc474d1461545c39d2b5872eb1c0f/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:166cf54d9f44fc6ceb53c7860258dde44a81406646de79f8ed3234fca3b6e538", size = 545978, upload-time = "2026-06-30T07:16:36.45Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/f2/0eb57f0eaa83f8fc152a7e03de968ab77e1f00732bebc892b190c6eebde7/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:d34c20167764fbcf927194d532dd7e0c56772f0a5f943fa5ef9e9afbba8fb9db", size = 613350, upload-time = "2026-06-30T07:16:38.213Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/de/e0674bdbc3ef7634989b3f854c3f34bc1f587d36e5bfdc5c378d57034619/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ea7bb13b7c9a29791f87a0387ba7d3ad3a6d783d827e4d3f27b40a0ff44495e2", size = 576486, upload-time = "2026-06-30T07:16:39.797Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/f6/21101359743cd136ada781e8210a85769578422ba460672eea0e29739200/rpds_py-2026.6.3-cp314-cp314t-win32.whl", hash = "sha256:6de4744d05bd1aa1be4ed7ea1189e3979196808008113bbbf899a460966b925e", size = 201068, upload-time = "2026-06-30T07:16:41.316Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/b2/9574d4d44f7760c2aa32d92a0a4f41698e33f5b204a0bf5c9758f52c79d5/rpds_py-2026.6.3-cp314-cp314t-win_amd64.whl", hash = "sha256:c7b9a2f8f4d8e90af72571d3d495deebdd7e3c75451f5b41719aee166e940fc2", size = 220600, upload-time = "2026-06-30T07:16:43.091Z" },
+    { url = "https://files.pythonhosted.org/packages/08/ae/f23a2697e6ee6340a578b0f136be6483657bef0c6f9497b752bb5c0964bb/rpds_py-2026.6.3-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:e059c5dde6452b44424bd1834557556c226b57781dee1227af23518459722b13", size = 344726, upload-time = "2026-06-30T07:16:44.5Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/63/e7b3a1a5358dd32c930a1062d8e15b67fd6e8922e81df9e91706d66ee5c8/rpds_py-2026.6.3-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:2f7c26fbc5acd2522b95d4177fe4710ffd8e9b20529e703ffbf8db4d93903f05", size = 339587, upload-time = "2026-06-30T07:16:46.255Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/64/10a85681916ca55fffb91b0a211f84e34297c109243484dd6394660a8a7c/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a3086b538543802f84c843911242db20447de00d8752dd0efc936dbcf02218ba", size = 369585, upload-time = "2026-06-30T07:16:48.101Z" },
+    { url = "https://files.pythonhosted.org/packages/76/c2/baf95c7c38823e12ba34407c5f5767a89e5cf2233895e56f608167ae9493/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8f2e5c5ee828d42cb11760761c0af6507927bec42d0ad5458f97c9203b054617", size = 375479, upload-time = "2026-06-30T07:16:49.93Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/94/0aad06c72d65101e11d33528d438cda99a39ce0da99466e156158f2541d3/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ed0c1e5d10cdc7135537988c74a0188da68e2f3c30813ba3744ab1e42e0480f9", size = 492418, upload-time = "2026-06-30T07:16:51.641Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/17/de3f5a479a1f056535d7489819639d8cd591ea6281d700390b43b1abd745/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8c2642a7603ec0b16ed77da4555db3b4b472341904873788327c0b0d7b95f1bb", size = 384123, upload-time = "2026-06-30T07:16:53.622Z" },
+    { url = "https://files.pythonhosted.org/packages/46/7d/bf09bd1b145bb2671c03e1e6d1ab8651858d90d8c7dfeadd85a37a934fd8/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8e4320744c1ffdd95a603def63344bfab2d33edeab301c5007e7de9f9f5b3885", size = 367351, upload-time = "2026-06-30T07:16:55.241Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/ea/1bb734f314b8be319149ddee80b18bd41372bdcfbdf88d28131c0cd37719/rpds_py-2026.6.3-cp315-cp315-manylinux_2_31_riscv64.whl", hash = "sha256:a9f4645593036b81bbdb36b9c8e0ea0d1c3fee968c4d59db0344c14087ef143a", size = 378827, upload-time = "2026-06-30T07:16:56.841Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/93/d9611e5b25e26df9a3649813ed66193ace9347a7c7fc4ab7cf70e94851c0/rpds_py-2026.6.3-cp315-cp315-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e55d236be29255554da47abe5c577637db7c24a02b8b46f0ca9524c855801868", size = 395966, upload-time = "2026-06-30T07:16:58.557Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/cb/99d77e16e5534ae1d90629bbe419ba6ee170833a6a85e3aa1cc41726fbbc/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:24e9c5386e16669b674a69c156c8eeefcb578f3b3397b713b08e6d60f3c7b187", size = 545680, upload-time = "2026-06-30T07:17:00.164Z" },
+    { url = "https://files.pythonhosted.org/packages/59/15/11a29755f790cef7a2f755e8e14f4f0c33f39489e1893a632a2eee59672b/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_i686.whl", hash = "sha256:c60924535c75f1566b6eb75b5c31a48a43fef04fa2d0d201acbad8a9969c6107", size = 611853, upload-time = "2026-06-30T07:17:01.962Z" },
+    { url = "https://files.pythonhosted.org/packages/68/86/0c27547e21644da938fb530f7e1a8148dd24d02db07e7a5f2567a17ce710/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:38a2fea2787428f811719ceb9114cb78964a3138838320c29ac39526c79c16ba", size = 573715, upload-time = "2026-06-30T07:17:03.693Z" },
+    { url = "https://files.pythonhosted.org/packages/29/71/4d8fcf700931815594bce892255bbd973b94efaf0fc1932b0590df18d886/rpds_py-2026.6.3-cp315-cp315-win32.whl", hash = "sha256:d483fe17f01ad64b7bf7cc38fcefff1ca9fb83f8c2b2542b68f97ffe0611b369", size = 202864, upload-time = "2026-06-30T07:17:05.746Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/62/b577562de0edbb55b2be85ce5fd09c33e386b9b13eee09833af4240fd5c4/rpds_py-2026.6.3-cp315-cp315-win_amd64.whl", hash = "sha256:67e3a721ffc5d8d2210d3671872298c4a84e4b8035cfe42ffd7cde35d772b146", size = 220430, upload-time = "2026-06-30T07:17:07.471Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/95/d6d0b2509825141eef60669a5739eec88dbc6a48053d6c92993a5704defe/rpds_py-2026.6.3-cp315-cp315-win_arm64.whl", hash = "sha256:6e84adbcf4bf841aed8116a8264b9f50b4cb3e7bd89b516122e616ac56ca269e", size = 215877, upload-time = "2026-06-30T07:17:09.008Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/bf/f3ea278f0afd615c1d0f19cb69043a41526e2bb600c2b536eb192218eb27/rpds_py-2026.6.3-cp315-cp315t-macosx_10_12_x86_64.whl", hash = "sha256:ae6dd8f10bd17aad820876d24caec9efdafd80a318d16c0a48edb5e136902c6b", size = 346933, upload-time = "2026-06-30T07:17:10.762Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/29/9907bdf1c5346763cf10b7f6852aad86652168c259def904cbe0082c5864/rpds_py-2026.6.3-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:bdbd97738551fca3917c1bd7188bec1920bb520104f28e7e1007f9ceb17b7690", size = 340274, upload-time = "2026-06-30T07:17:12.266Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/2c/8e03767b5778ef25cebf74a7a91a2c3806f8eced4c92cb7406bbe060756d/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8b95977e7211527ab0ba576e286d023389fbeeb32a6b7b771665d333c60e5342", size = 370763, upload-time = "2026-06-30T07:17:14.107Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/e1/df2a7e1ba2efd796af26194250b8d42c821b46592311595162af9ef0528d/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d15fde0e6fb0d88a60d221204873743e5d9f0b7d29165e62cd86d0413ad74ba6", size = 376467, upload-time = "2026-06-30T07:17:15.76Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/de/8a0814d1946af29cb068fb259aa8622f856df1d0bab58429448726b537f5/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a136d453475ac0fcbda502ef1e6504bd28d6d904700915d278deeab0d00fe140", size = 496689, upload-time = "2026-06-30T07:17:17.308Z" },
+    { url = "https://files.pythonhosted.org/packages/df/f3/f19e0c852ba13694f5a79f3b719331051573cb5693feacf8a88ffffc3a71/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f826877d462181e5eb1c26a0026b8d0cab05d99844ecb6d8bf3627a2ca0c0442", size = 385340, upload-time = "2026-06-30T07:17:18.928Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/ae/7ec3a9d2d4351f99e37bcb06b6b6f954512646bfdbf9742e1de727865daf/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:79486287de1730dbaff3dbd124d0ca4d2ef7f9d29bf2544f1f93c09b5bcbbd12", size = 372179, upload-time = "2026-06-30T07:17:20.539Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/ac/9cee911dff2aaa9a5a8354f6610bf2e6a616de9197c5fff4f54f82585f1e/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_31_riscv64.whl", hash = "sha256:808345f53cb952433ca2816f1604ff3515608a81784954f38d4452acfe8e61d5", size = 379993, upload-time = "2026-06-30T07:17:22.212Z" },
+    { url = "https://files.pythonhosted.org/packages/83/6b/7c2a07ba88d1e9a936612f7a5d067467ed03d971d5a06f7d309dff044a7e/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1967debc37f64f2c4dc90a7f563aec558b471966e12adcac4e1c4240496b6ebf", size = 398909, upload-time = "2026-06-30T07:17:23.66Z" },
+    { url = "https://files.pythonhosted.org/packages/97/0b/776ffcb66783637b0031f6d58d6fb55913c8b5abf00aeecd46bf933fb477/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:f0840b5b17057f7fd918b76183a4b5a0635f43e14eb2ce60dce1d4ee4707ea00", size = 546584, upload-time = "2026-06-30T07:17:25.264Z" },
+    { url = "https://files.pythonhosted.org/packages/55/33/ba3bc04d7092bd553c9b2b195624992d2cc4f3de1f380b7b93cbee67bd79/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_i686.whl", hash = "sha256:faa679d19a6696fd54259ad321251ad77a13e70e03dd834daa762a44fb6196ef", size = 614357, upload-time = "2026-06-30T07:17:26.888Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/71/14edf065f04630b1a8472f7653cad03f6c478bcf95ea0e6aed55451e33ea/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:23a439f31ccbeff1574e24889128821d1f7917470e830cf6544dced1c662262a", size = 576533, upload-time = "2026-06-30T07:17:28.546Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/76/65002b08596c389105720a8c0d22298b8dc25a4baf89b2ce431343c8b1de/rpds_py-2026.6.3-cp315-cp315t-win32.whl", hash = "sha256:913ca42ccad3f8cc6e292b587ae8ae49c8c823e5dce51a736252fc7c7cdfa577", size = 201204, upload-time = "2026-06-30T07:17:30.193Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/97/d855d6b3c322d1f27e26f5241c42016b56cf01377ea8ed348285f54652f0/rpds_py-2026.6.3-cp315-cp315t-win_amd64.whl", hash = "sha256:ae3d4fe8c0b9213624fdce7279d70e3b148b682ca20719ebd193a23ebfa47324", size = 220719, upload-time = "2026-06-30T07:17:31.788Z" },
+]
+
 [[package]]
 name = "safehttpx"
 version = "0.1.7"
@@ -1117,17 +1266,29 @@ dependencies = [
     { name = "gradio" },
     { name = "httpx" },
     { name = "huggingface-hub" },
+    { name = "jsonschema" },
     { name = "pandas" },
     { name = "plotly" },
+    { name = "pydantic" },
     { name = "smolagents", extra = ["openai"] },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "gradio", specifier = ">=5.0.0" },
     { name = "httpx", specifier = ">=0.27.0" },
     { name = "huggingface-hub", specifier = ">=1.30.0" },
+    { name = "jsonschema", specifier = ">=4.0.0" },
     { name = "pandas", specifier = ">=3.0.5" },
     { name = "plotly", specifier = ">=7.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0" },
     { name = "smolagents", extras = ["openai"], specifier = ">=1.26.0" },
 ]
+
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=8.0.0" }]

wavereader/__init__.py

@@ -0,0 +1,25 @@
+"""wavereader — pure-core surf forecasting package (typed, tested, no Gradio)."""
+
+from wavereader.breaks import filter_breaks, load_breaks, resolve_break
+from wavereader.openmeteo import get_forecast
+from wavereader.scoring import (
+    daily_summary,
+    rank_spots,
+    rank_spots_this_week,
+    score_hour,
+    score_week,
+)
+from wavereader.seafloor import get_seafloor
+
+__all__ = [
+    "load_breaks",
+    "resolve_break",
+    "filter_breaks",
+    "get_forecast",
+    "score_hour",
+    "score_week",
+    "daily_summary",
+    "rank_spots",
+    "rank_spots_this_week",
+    "get_seafloor",
+]

wavereader/breaks.py

@@ -0,0 +1,169 @@
+"""Surf-break catalogue: load, validate, resolve (wavereader v2 core port).
+
+Ported from ``app/breaks_data.py`` with the pandas dependency dropped:
+plain ``json`` + lists throughout. Every record is validated against
+``data/surf-break-schema.json`` via jsonschema; invalid records are
+skipped (with a count available) unless ``strict=True``.
+
+Public surface::
+
+    load_breaks(path=...) -> list[dict]
+    resolve_break(name, region=None, breaks=None) -> dict | None
+    filter_breaks(breaks, state=None, region=None, skill=None) -> list[dict]
+    get_coords(break_) -> (lat, lng)
+
+Deterministic only: no LLM, no network.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+from pathlib import Path
+
+import jsonschema
+
+DATA_PATH = Path(__file__).resolve().parent.parent / "data" / "australia-surf-breaks-enriched.json"
+SCHEMA_PATH = Path(__file__).resolve().parent.parent / "data" / "surf-break-schema.json"
+
+ALL = "All"
+
+_SCHEMA_CACHE: dict | None = None
+
+
+def load_schema(path: Path = SCHEMA_PATH) -> dict:
+    """Load (and memoize) the surf-break JSON schema."""
+    global _SCHEMA_CACHE
+    if _SCHEMA_CACHE is None:
+        _SCHEMA_CACHE = json.loads(path.read_text(encoding="utf-8"))
+    return _SCHEMA_CACHE
+
+
+def is_valid_break(break_: dict, schema: dict | None = None) -> bool:
+    """True when a record conforms to the surf-break schema."""
+    try:
+        jsonschema.validate(instance=break_, schema=schema or load_schema())
+    except jsonschema.ValidationError:
+        return False
+    return True
+
+
+def load_breaks(path: Path = DATA_PATH, strict: bool = False) -> list[dict]:
+    """Load the enriched break catalogue as a list of validated records.
+
+    Handles the legacy ``{"name | state | region": {...}}`` dict format
+    and drops ``error`` rows, mirroring the v1 loader. Records failing
+    schema validation are skipped (``strict=True`` raises instead).
+    """
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        records = list(data.values())
+    else:
+        records = list(data)
+
+    schema = load_schema()
+    out: list[dict] = []
+    skipped = 0
+    for rec in records:
+        if not isinstance(rec, dict):
+            skipped += 1
+            continue
+        if rec.get("error") is not None:
+            # v1 semantics: rows carrying an "error" marker are dropped.
+            skipped += 1
+            continue
+        try:
+            jsonschema.validate(instance=rec, schema=schema)
+        except jsonschema.ValidationError:
+            if strict:
+                raise
+            skipped += 1
+            continue
+        out.append(rec)
+    out.sort(key=lambda b: (str(b.get("state", "")), str(b.get("region", "")), str(b.get("name", ""))))
+    load_breaks.last_skipped = skipped  # type: ignore[attr-defined]
+    return out
+
+
+# Count of records skipped by the most recent load_breaks() call.
+load_breaks.last_skipped = 0  # type: ignore[attr-defined]
+
+
+def filter_breaks(
+    breaks: list[dict],
+    state: str | None = None,
+    region: str | None = None,
+    skill: str | None = None,
+) -> list[dict]:
+    """Filter breaks by state / region / skill level ("All"/None = no filter)."""
+    out = list(breaks)
+    if state and state != ALL:
+        out = [b for b in out if str(b.get("state", "")).lower() == state.lower()]
+    if region and region != ALL:
+        out = [b for b in out if str(b.get("region", "")).lower() == region.lower()]
+    if skill and skill != ALL:
+        out = [b for b in out if str(b.get("skillLevel", "")).lower() == skill.lower()]
+    return out
+
+
+def _norm(text: str | None) -> str:
+    return str(text or "").strip().lower()
+
+
+def resolve_break(
+    name: str, region: str | None = None, breaks: list[dict] | None = None
+) -> dict | None:
+    """Resolve a break by name (fuzzy, case-insensitive), optionally scoped to a region.
+
+    Match order: exact name (+ region when given) → substring match →
+    difflib close match. Returns the record dict, or None when nothing
+    matches.
+    """
+    pool = breaks if breaks is not None else load_breaks()
+    want = _norm(name)
+    if not want:
+        return None
+    if region is not None:
+        scoped = [b for b in pool if _norm(b.get("region")) == _norm(region)]
+        if scoped:
+            pool = scoped
+
+    for b in pool:
+        if _norm(b.get("name")) == want:
+            return b
+    for b in pool:
+        if want in _norm(b.get("name")):
+            return b
+    names = [_norm(b.get("name")) for b in pool]
+    close = difflib.get_close_matches(want, names, n=1, cutoff=0.6)
+    if close:
+        for b in pool:
+            if _norm(b.get("name")) == close[0]:
+                return b
+    return None
+
+
+def get_coords(break_: dict) -> tuple[float | None, float | None]:
+    """Return ``(lat, lng)`` (None on missing coords)."""
+    try:
+        lat = float(break_["location"]["coordinates"]["lat"])
+    except (KeyError, TypeError, ValueError):
+        lat = None
+    try:
+        lng = float(break_["location"]["coordinates"]["lng"])
+    except (KeyError, TypeError, ValueError):
+        lng = None
+    return lat, lng
+
+
+__all__ = [
+    "DATA_PATH",
+    "SCHEMA_PATH",
+    "ALL",
+    "load_schema",
+    "is_valid_break",
+    "load_breaks",
+    "filter_breaks",
+    "resolve_break",
+    "get_coords",
+]

wavereader/openmeteo.py

@@ -0,0 +1,244 @@
+"""Open-Meteo Marine + weather forecast client (wavereader v2 core port).
+
+Ported verbatim-first from ``app/forecasts.py``. v2 changes:
+
+* marine fetch adds hourly ``swell_wave_direction`` and
+  ``swell_wave_period`` (scoring v2 prefers ``swell_wave_*`` components
+  over the generic ``wave_*`` aggregates when present);
+* ``CACHE_VERSION`` bumped 2 → 3, so old-shape cache entries (without the
+  new swell fields) are never served as fresh.
+
+Two endpoints, merged on ``time``:
+
+* ``marine-api.open-meteo.com`` — hourly ``wave_height`` (m),
+  ``wave_period`` (s), ``wave_direction`` (deg), ``wind_wave_height`` (m),
+  ``swell_wave_height`` (m), ``swell_wave_direction`` (deg),
+  ``swell_wave_period`` (s), ``sea_surface_temperature`` (C, when served).
+* ``api.open-meteo.com`` — hourly ``wind_speed_10m`` (km/h; convert to
+  knots for scoring), ``wind_direction_10m`` (deg),
+  ``wind_gusts_10m`` (km/h, when served), plus ``daily``
+  ``sunrise``/``sunset`` (ISO local, ``timezone=auto``) used by the
+  scoring v2 daylight filter.
+
+Grid points snap ~10 km offshore of a spot's coords: fetch slightly
+seaward of the spot (east-coast breaks shift east, west-coast breaks
+shift west, south-coast breaks (SA/VIC/TAS) shift south).
+
+Cache every response to disk. Fresh cache (within ``CACHE_TTL_SECONDS``)
+is served without a network call; when the API fails, a stale cache
+entry is served as a fallback rather than raising. Horizon: hourly,
+7 days.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import httpx
+
+MARINE_URL = "https://marine-api.open-meteo.com/v1/marine"
+WEATHER_URL = "https://api.open-meteo.com/v1/forecast"
+
+MARINE_HOURLY_FIELDS = (
+    "wave_height",
+    "wave_period",
+    "wave_direction",
+    "wind_wave_height",
+    "swell_wave_height",
+    "swell_wave_direction",
+    "swell_wave_period",
+    "sea_surface_temperature",
+)
+WEATHER_HOURLY_FIELDS = ("wind_speed_10m", "wind_direction_10m", "wind_gusts_10m")
+# Daily sun times come from the same weather endpoint (no new API/key).
+WEATHER_DAILY_FIELDS = ("sunrise", "sunset")
+
+# ~0.13° is roughly 14 km — enough to move off the coast onto a marine grid point.
+_SEAWARD_OFFSET_DEG = 0.13
+
+CACHE_DIR = Path(__file__).resolve().parent.parent / ".cache" / "forecasts"
+CACHE_TTL_SECONDS = 6 * 3600
+# Bumped when the cached frame shape changes (v3: swell_wave_direction /
+# swell_wave_period added) so old-shape entries are never served as fresh.
+CACHE_VERSION = 3
+
+
+def _seaward_offset(lat: float, lon: float) -> tuple[float, float]:
+    """Offset a spot's coords toward open ocean so Open-Meteo resolves a marine grid point.
+
+    Direction is inferred from position: Tasmania and the south coast shift
+    south, the east coast (lon >= 147) shifts east, the west coast
+    (lon <= 125) shifts west.
+
+    Shared with the climatology builder (Worker B): reuse this instead of
+    re-implementing the offset for archive calls.
+    """
+    if lat <= -39.5:  # Tasmania: open ocean to the south
+        dlat, dlon = -_SEAWARD_OFFSET_DEG, 0.0
+    elif lon >= 147:  # east coast (QLD/NSW)
+        dlat, dlon = 0.0, _SEAWARD_OFFSET_DEG
+    elif lon <= 125:  # west coast (WA)
+        dlat, dlon = 0.0, -_SEAWARD_OFFSET_DEG
+    else:  # south coast (SA/VIC)
+        dlat, dlon = -_SEAWARD_OFFSET_DEG, 0.0
+    return dlat, dlon
+
+
+def _round_coords(lat: float, lon: float) -> tuple[float, float]:
+    dlat, dlon = _seaward_offset(lat, lon)
+    return round(lat + dlat, 2), round(lon + dlon, 2)
+
+
+def _cache_key(lat: float, lon: float, days: int) -> str:
+    """Cache key from the *raw* spot coords (offset is a fetch detail only)."""
+    return f"v{CACHE_VERSION}_{round(lat, 2):.2f}_{round(lon, 2):.2f}_{days}"
+
+
+def _cache_path(lat: float, lon: float, days: int) -> Path:
+    return CACHE_DIR / f"{_cache_key(lat, lon, days)}.json"
+
+
+def _load_cache(lat: float, lon: float, days: int) -> tuple[dict, float] | None:
+    """Return ``(data, fetched_at)`` from disk, or None if absent/corrupt.
+
+    Legacy cache files written before the envelope format are returned with
+    ``fetched_at = 0`` so they still work as a stale fallback.
+    """
+    p = _cache_path(lat, lon, days)
+    if not p.exists():
+        return None
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    if isinstance(raw, dict) and "fetched_at" in raw and "data" in raw:
+        return raw["data"], float(raw["fetched_at"])
+    return raw, 0.0
+
+
+def _save_cache(lat: float, lon: float, days: int, data: dict) -> None:
+    """Write the cache envelope atomically (crash-safe write + rename)."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    envelope = {"fetched_at": time.time(), "data": data}
+    tmp = _cache_path(lat, lon, days).with_suffix(".tmp")
+    tmp.write_text(json.dumps(envelope, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp, _cache_path(lat, lon, days))
+
+
+def _build_normalized(marine: dict, weather: dict) -> dict:
+    """Merge marine + weather hourly on ``time`` into a clean frame.
+
+    Also carries ``daily`` sun times (``{"time", "sunrise", "sunset"}``)
+    straight from the weather endpoint, plus optional per-hour
+    ``sea_surface_temperature`` (C) and ``wind_gusts_10m`` (km/h) when
+    the API serves them. Scoring ignores unknown fields, so old
+    consumers keep working.
+    """
+    m = marine["hourly"]
+    w = weather["hourly"]
+    marine_times = m["time"]
+
+    weather_index: dict[str, dict[str, float]] = {}
+    for i, t in enumerate(w["time"]):
+        entry: dict[str, float] = {"time": t}
+        for field in WEATHER_HOURLY_FIELDS:
+            if field in w and i < len(w[field]):
+                entry[field] = w[field][i]
+        weather_index[t] = entry
+
+    frames: list[dict] = []
+    for i, t in enumerate(marine_times):
+        row: dict[str, float | str] = {"time": t}
+        for field in MARINE_HOURLY_FIELDS:
+            if field in m and i < len(m[field]):
+                row[field] = m[field][i]
+        wr = weather_index.get(t)
+        if wr:
+            for field in WEATHER_HOURLY_FIELDS:
+                if field in wr:
+                    row[field] = wr[field]
+        frames.append(row)
+
+    daily: dict = {}
+    w_daily = weather.get("daily") or {}
+    if isinstance(w_daily, dict) and w_daily.get("time"):
+        daily = {
+            k: w_daily.get(k)
+            for k in ("time", *WEATHER_DAILY_FIELDS)
+            if k in w_daily
+        }
+
+    out: dict = {"hourly": frames}
+    if daily:
+        out["daily"] = daily
+    return out
+
+
+def _fetch_open_meteo(rlat: float, rlon: float, days: int) -> dict:
+    """Call both Open-Meteo endpoints and return the merged frame."""
+    params: dict[str, str | int | float] = {
+        "latitude": rlat,
+        "longitude": rlon,
+        "forecast_days": days,
+    }
+
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        resp_m = client.get(MARINE_URL, params={**params, "hourly": ",".join(MARINE_HOURLY_FIELDS)})
+        resp_m.raise_for_status()
+        marine = resp_m.json()
+        resp_w = client.get(
+            WEATHER_URL,
+            params={
+                **params,
+                "hourly": ",".join(WEATHER_HOURLY_FIELDS),
+                "daily": ",".join(WEATHER_DAILY_FIELDS),
+                "timezone": "auto",
+            },
+        )
+        resp_w.raise_for_status()
+        weather = resp_w.json()
+
+    return _build_normalized(marine, weather)
+
+
+def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
+    """Fetch marine + weather hourly data for a coordinate, merged on time.
+
+    Returns a normalised frame: ``{"hourly": [{"time": ..., "wave_height": ...,
+    "swell_wave_height": ..., "wind_speed_10m": ..., ...}, ...], "daily":
+    {"time": [...], "sunrise": [...], "sunset": [...]}}``. Disk-cached by
+    rounded coords + days: entries younger than ``CACHE_TTL_SECONDS`` are
+    served directly; on a network failure the most recent cache entry
+    (however old) is served as a fallback. Raises only when there is no
+    usable data at all.
+    """
+    rlat, rlon = _round_coords(lat, lon)
+    cached = _load_cache(lat, lon, days)
+    if cached is not None and time.time() - cached[1] < CACHE_TTL_SECONDS:
+        return cached[0]
+
+    try:
+        merged = _fetch_open_meteo(rlat, rlon, days)
+    except (httpx.HTTPError, KeyError, ValueError):
+        if cached is not None:
+            return cached[0]
+        raise
+
+    _save_cache(lat, lon, days, merged)
+    return merged
+
+
+__all__ = [
+    "MARINE_URL",
+    "WEATHER_URL",
+    "MARINE_HOURLY_FIELDS",
+    "WEATHER_HOURLY_FIELDS",
+    "WEATHER_DAILY_FIELDS",
+    "CACHE_TTL_SECONDS",
+    "CACHE_VERSION",
+    "_seaward_offset",
+    "get_forecast",
+]

wavereader/scoring.py

@@ -0,0 +1,666 @@
+"""Deterministic surf-quality scoring engine, v2 (wavereader core port).
+
+Merges ``app/adapters.py`` (break-record → spot shaping) with
+``app/scoring.py`` (skill-calibrated Gaussian component curves).
+
+Scoring v2 upgrades over the v1 port:
+
+* **Swell components first** — :func:`score_week` prefers
+  ``swell_wave_height`` / ``swell_wave_direction`` / ``swell_wave_period``
+  when the frame carries them, falling back to the generic ``wave_*``
+  aggregates otherwise.
+* **Direction arc, not cyclic mean** — the ideal direction list is parsed
+  to a *set* of bearings (:func:`_ideal_bearings`) and the score uses the
+  minimum angular distance to *any* of them. A break that takes both E
+  and S no longer scores its middle (SE-ish mean) as perfect.
+* **Wind cap from ``idealWind.type``** — offshore 18 kt, cross-shore 12,
+  onshore 8, light/variable 10 — with a smooth logistic roll-off centred
+  at the cap instead of the old 10→0 cliff. The effective cap is still
+  bounded above by the skill profile's ``max_wind_kt``.
+* **Daylight-only** — :func:`score_week` drops night hours using
+  ``daily.sunrise``/``sunset`` from the forecast frame
+  (``daylight_only=False`` restores all hours).
+* **Daily summary = p75** — :func:`daily_summary` reports the 75th
+  percentile of daylight scores per date (consistency over one lucky
+  hour).
+* **Rank by surfable hours** — :func:`rank_spots` orders by
+  (hours with score ≥ 6, then best score).
+
+Stable public signatures (Worker C builds against these)::
+
+    score_week(forecast, spot, skill_level="intermediate", daylight_only=True)
+    rank_spots(forecasts, spots_list, skill_level="intermediate")
+
+Deterministic only: no LLM, no network.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional
+
+# ---- 16-Point Compass Reference ----
+
+_COMPASS_DEG: dict[str, float] = {
+    "N": 0.0, "NNE": 22.5, "NE": 45.0, "ENE": 67.5,
+    "E": 90.0, "ESE": 112.5, "SE": 135.0, "SSE": 157.5,
+    "S": 180.0, "SSW": 202.5, "SW": 225.0, "WSW": 247.5,
+    "W": 270.0, "WNW": 292.5, "NW": 315.0, "NNW": 337.5,
+}
+
+_WEIGHTS = {
+    "swell_size": 0.30,
+    "swell_direction": 0.20,
+    "wind": 0.30,
+    "period": 0.20,
+}
+
+# Skill Profile Thresholds (values in feet, knots, seconds)
+_SKILL_PROFILES: dict[str, dict[str, Any]] = {
+    "beginner": {
+        "comfort_size_min_ft": 1.0,
+        "comfort_size_max_ft": 3.5,
+        "max_safe_size_ft": 4.5,
+        "max_wind_kt": 12.0,
+        "ideal_period_max_s": 12.0,
+    },
+    "intermediate": {
+        "comfort_size_min_ft": 2.0,
+        "comfort_size_max_ft": 6.5,
+        "max_safe_size_ft": 8.5,
+        "max_wind_kt": 18.0,
+        "ideal_period_max_s": 16.0,
+    },
+    "advanced": {
+        "comfort_size_min_ft": 3.0,
+        "comfort_size_max_ft": 12.0,
+        "max_safe_size_ft": 18.0,
+        "max_wind_kt": 25.0,
+        "ideal_period_max_s": 22.0,
+    },
+    "expert": {
+        "comfort_size_min_ft": 4.0,
+        "comfort_size_max_ft": 30.0,
+        "max_safe_size_ft": 50.0,
+        "max_wind_kt": 35.0,
+        "ideal_period_max_s": 25.0,
+    },
+}
+
+SKILL_LEVELS = tuple(_SKILL_PROFILES.keys())
+_DEFAULT_SKILL_LEVEL = "intermediate"
+
+# Wind caps (kt) by ideal-wind type. Break type is carried on the spot
+# dict for downstream use; the cap itself is driven by wind type.
+_WIND_CAP_BY_TYPE: dict[str, float] = {
+    "offshore": 18.0,
+    "cross-shore": 12.0,
+    "onshore": 8.0,
+    "light/variable": 10.0,
+}
+# Logistic steepness (kt): score falls from ~9.5 to ~0.5 over ±3 kt
+# around the cap.
+_WIND_LOGISTIC_STEEPNESS = 1.0
+
+SURFABLE_THRESHOLD = 6.0
+
+DEFAULT_DIRECTION = "E"
+
+_SCORING_SKILLS = frozenset({"beginner", "intermediate", "advanced", "expert"})
+_FALLBACK_SKILL = "intermediate"
+
+
+# ---- Adapter shaping (ported from app/adapters.py) ----
+
+def normalize_skill(skill: str | None) -> str:
+    """Normalise an enriched ``skillLevel`` to a scoring skill tier."""
+    if skill is None:
+        return _FALLBACK_SKILL
+    s = str(skill).strip().lower()
+    if s in ("pro-only", "pro only", "pro"):
+        return "expert"
+    if s in _SCORING_SKILLS:
+        return s
+    return _FALLBACK_SKILL
+
+
+def _join_direction(directions) -> str:
+    """Join a compass-point list with ``/``; default to ``"E"`` when empty."""
+    if not directions:
+        return DEFAULT_DIRECTION
+    if isinstance(directions, str):
+        text = directions.strip()
+        return text if text else DEFAULT_DIRECTION
+    parts = [str(d).strip() for d in directions if str(d).strip()]
+    return "/".join(parts) if parts else DEFAULT_DIRECTION
+
+
+def _normalize_wind_type(wind_type: str | None) -> str:
+    """Normalise an enriched ``idealWind.type`` to a wind-cap key."""
+    t = str(wind_type or "").strip().lower()
+    if "cross" in t:
+        return "cross-shore"
+    if "onshore" in t or t == "on":
+        return "onshore"
+    if "offshore" in t or t == "off":
+        return "offshore"
+    if "light" in t or "variable" in t:
+        return "light/variable"
+    return "light/variable"
+
+
+def enriched_to_scoring_spot(break_: dict) -> dict:
+    """Convert one enriched break record to the scoring spot shape.
+
+    v2: carries ``ideal_wind.type`` (drives the wind cap) and
+    ``break_type`` through; the legacy flat ``strength_kt_max`` is gone.
+    """
+    swell = break_.get("idealSwell", {}) or {}
+    size = swell.get("sizeRangeFt", {}) or {}
+    wind = break_.get("idealWind", {}) or {}
+    return {
+        "name": break_.get("name", ""),
+        "region": break_.get("region", ""),
+        "break_type": break_.get("breakType", ""),
+        "ideal_swell": {
+            "direction": _join_direction(swell.get("direction")),
+            "size_ft_min": float(size.get("min", 0.0)),
+            "size_ft_max": float(size.get("max", 0.0)),
+        },
+        "ideal_wind": {
+            "direction": _join_direction(wind.get("direction")),
+            "type": _normalize_wind_type(wind.get("type")),
+        },
+    }
+
+
+def get_coords(break_: dict) -> tuple[float | None, float | None]:
+    """Return ``(lat, lng)`` (None on missing coords)."""
+    try:
+        lat = float(break_["location"]["coordinates"]["lat"])
+    except (KeyError, TypeError, ValueError):
+        lat = None
+    try:
+        lng = float(break_["location"]["coordinates"]["lng"])
+    except (KeyError, TypeError, ValueError):
+        lng = None
+    return lat, lng
+
+
+def break_skill(break_: dict) -> str:
+    """Return the normalised skill tier for an enriched break record."""
+    return normalize_skill(break_.get("skillLevel"))
+
+
+def wind_cap(spot: dict, skill_level: str = _DEFAULT_SKILL_LEVEL) -> float:
+    """Effective wind cap (kt) for a spot + skill tier.
+
+    Base cap from ``ideal_wind.type`` (offshore 18 / cross-shore 12 /
+    onshore 8 / light-variable 10), bounded above by the skill profile's
+    ``max_wind_kt``.
+    """
+    wind = spot.get("ideal_wind", {}) or {}
+    base = _WIND_CAP_BY_TYPE.get(
+        _normalize_wind_type(wind.get("type")), _WIND_CAP_BY_TYPE["light/variable"]
+    )
+    try:
+        profile_max = float(_SKILL_PROFILES[skill_level]["max_wind_kt"])
+    except (KeyError, TypeError, ValueError):
+        return base
+    return min(base, profile_max)
+
+
+# ---- Direction helpers ----
+
+def _ideal_bearings(direction: str) -> list[float]:
+    """Parse a slash-separated ideal-direction string to a set of bearings.
+
+    Accepts the ``"SW/S/SSW"`` shape produced by :func:`_join_direction`
+    (also tolerates commas and " to " separators). Unknown tokens are
+    ignored; raises ``ValueError`` when nothing parses.
+    """
+    normalized = (
+        direction.replace(",", "/").replace(" to ", "/").replace(" ", "").upper()
+    )
+    degs = [_COMPASS_DEG[p] for p in normalized.split("/") if p in _COMPASS_DEG]
+    if not degs:
+        raise ValueError(f"Invalid compass direction input: {direction!r}")
+    # Dedupe while preserving order.
+    seen: set[float] = set()
+    out: list[float] = []
+    for d in degs:
+        if d not in seen:
+            seen.add(d)
+            out.append(d)
+    return out
+
+
+def _dir_to_deg(direction: str) -> float:
+    """Mean bearing of a slash-separated direction string (legacy helper).
+
+    Kept for compatibility; scoring v2 uses :func:`_ideal_bearings` (arc
+    distance to the nearest ideal bearing) instead of the cyclic mean.
+    """
+    degs = _ideal_bearings(direction)
+    sin_sum = sum(math.sin(math.radians(d)) for d in degs)
+    cos_sum = sum(math.cos(math.radians(d)) for d in degs)
+    mean_deg = math.degrees(math.atan2(sin_sum, cos_sum)) % 360
+    return round(mean_deg, 1)
+
+
+def _angular_diff(a: float, b: float) -> float:
+    """Shortest arc distance between two bearings in degrees."""
+    d = abs(a - b) % 360.0
+    return d if d <= 180.0 else 360.0 - d
+
+
+def _arc_distance(wave_dir_deg: float, ideal_direction: str) -> float:
+    """Minimum angular distance from a bearing to the ideal-direction arc."""
+    return min(_angular_diff(wave_dir_deg, b) for b in _ideal_bearings(ideal_direction))
+
+
+def _gaussian_decay(value: float, target: float, sigma: float) -> float:
+    """Smooth Gaussian decay yielding 1.0 at target and trailing to 0.0."""
+    return math.exp(-((value - target) ** 2) / (2 * (sigma ** 2)))
+
+
+def _logistic_wind_speed_score(wind_speed_kt: float, cap_kt: float) -> float:
+    """Smooth 0–10 speed score: ~10 well below cap, 5.0 at cap, ~0 above."""
+    return 10.0 / (1.0 + math.exp((wind_speed_kt - cap_kt) / _WIND_LOGISTIC_STEEPNESS))
+
+
+# ---- Core Scoring Components ----
+
+def _score_swell_size(wave_height_m: float, spot: dict, skill_level: str) -> float:
+    """Evaluates swell size considering spot ideals and surfer safety constraints."""
+    profile = _SKILL_PROFILES[skill_level]
+    wave_height_ft = wave_height_m * 3.28084
+
+    spot_ideal = spot["ideal_swell"]
+    spot_min_ft = float(spot_ideal["size_ft_min"])
+    spot_max_ft = float(spot_ideal["size_ft_max"])
+
+    # 1. Spot Suitability (Does the spot work?)
+    if spot_min_ft <= wave_height_ft <= spot_max_ft:
+        spot_score = 10.0
+    elif wave_height_ft < spot_min_ft:
+        sigma = max(1.0, spot_min_ft * 0.4)
+        spot_score = 10.0 * _gaussian_decay(wave_height_ft, spot_min_ft, sigma)
+    else:
+        sigma = max(1.5, spot_max_ft * 0.5)
+        spot_score = 10.0 * _gaussian_decay(wave_height_ft, spot_max_ft, sigma)
+
+    # 2. Safety & Comfort Filter
+    comf_min = profile["comfort_size_min_ft"]
+    comf_max = profile["comfort_size_max_ft"]
+    max_safe = profile["max_safe_size_ft"]
+
+    if wave_height_ft > max_safe:
+        # Zero tolerance for dangerous wave heights relative to skill
+        return 0.0
+
+    skill_mult = 1.0
+    if wave_height_ft < comf_min:
+        skill_mult = max(0.2, wave_height_ft / comf_min)
+    elif wave_height_ft > comf_max:
+        # Smooth penalty down to zero at max_safe_size
+        overage = wave_height_ft - comf_max
+        allowed_headroom = max_safe - comf_max
+        skill_mult = max(0.0, 1.0 - (overage / allowed_headroom) ** 1.5)
+
+    return round(spot_score * skill_mult, 2)
+
+
+def _score_swell_direction(wave_dir_deg: float, spot: dict) -> float:
+    """Directional match = Gaussian falloff from the *nearest* ideal bearing.
+
+    v2 replaces the cyclic mean: a break ideal at ``"E/SE"`` scores 10.0
+    at exactly E *or* SE, instead of peaking at the ESE midpoint.
+    """
+    diff = _arc_distance(wave_dir_deg, spot["ideal_swell"]["direction"])
+
+    # Half-width tolerance angle before severe drop-off (e.g., 45 degrees)
+    tolerance_deg = 45.0
+    score = 10.0 * _gaussian_decay(diff, 0.0, tolerance_deg / 1.5)
+    return max(0.0, min(10.0, score))
+
+
+def _score_wind(
+    wind_speed_kt: float,
+    wind_dir_deg: float,
+    spot: dict,
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+    gust_kt: float | None = None,
+) -> float:
+    """Scores wind as the mean of a speed score and a direction score.
+
+    Speed: logistic roll-off centred at the effective cap
+    (:func:`wind_cap` — wind type table bounded by the skill profile),
+    so glassy air scores ~10 and howling air scores ~0 with no cliff.
+    Direction: cosine falloff from the nearest ideal (offshore) bearing
+    to absolute onshore. Gusts (optional, kt): gust > limit+10 knocks
+    2 points off, gust > limit+5 knocks 1 point off — same limit, no new
+    thresholds.
+    """
+    limit = wind_cap(spot, skill_level)
+
+    offshore_arc = spot["ideal_wind"]["direction"]
+    diff = _arc_distance(wind_dir_deg, offshore_arc)
+    dir_score = 10.0 * max(0.0, math.cos(math.radians(diff / 2.0)))
+
+    speed_score = _logistic_wind_speed_score(wind_speed_kt, limit)
+
+    base = round((speed_score + dir_score) / 2.0, 2)
+    if gust_kt is not None:
+        try:
+            gust = float(gust_kt)
+        except (TypeError, ValueError):
+            gust = None
+        if gust is not None:
+            if gust > limit + 10:
+                base = max(0.0, round(base - 2.0, 2))
+            elif gust > limit + 5:
+                base = max(0.0, round(base - 1.0, 2))
+    return base
+
+
+def _score_period(period_s: float, skill_level: str = _DEFAULT_SKILL_LEVEL) -> float:
+    """Evaluates swell period quality: 0 below 4 s, 10 from 14 s up.
+
+    Long groundswell is never penalised for experienced surfers — there
+    is no falloff above 14 s. Beginners get a gentle cap above their
+    ``ideal_period_max_s`` (12 s): very long-period power is harder to
+    handle, so the score eases down to a floor of ~5 instead of 10.
+    """
+    if period_s <= 4.0:
+        return 0.0
+    if period_s >= 14.0:
+        base = 10.0
+    else:
+        base = round(10.0 * (period_s - 4.0) / 10.0, 2)
+    try:
+        ideal_max = float(_SKILL_PROFILES[skill_level]["ideal_period_max_s"])
+    except (KeyError, TypeError, ValueError):
+        return base
+    if skill_level == "beginner" and period_s > ideal_max:
+        base = max(5.0, round(base - (period_s - ideal_max) * 0.4, 2))
+    return base
+
+
+# ---- Daylight filtering ----
+
+def _daylight_windows(daily: dict | None) -> dict[str, tuple[str, str]]:
+    """Map ``date → (sunrise_hhmm, sunset_hhmm)`` from a daily sun frame."""
+    out: dict[str, tuple[str, str]] = {}
+    if not isinstance(daily, dict):
+        return out
+    times = daily.get("time") or []
+    rises = daily.get("sunrise") or []
+    sets = daily.get("sunset") or []
+    for i, day in enumerate(times):
+        try:
+            rise, set_ = rises[i], sets[i]
+        except IndexError:
+            continue
+        if not (isinstance(rise, str) and isinstance(set_, str)):
+            continue
+        # ISO local "YYYY-MM-DDTHH:MM" — compare the HH:MM slice.
+        out[str(day)[:10]] = (rise[11:16], set_[11:16])
+    return out
+
+
+def is_daylight(iso_time: str, windows: dict[str, tuple[str, str]]) -> bool:
+    """True when an hourly ISO timestamp falls between sunrise and sunset."""
+    day = str(iso_time)[:10]
+    window = windows.get(day)
+    if window is None:
+        return True  # fail-open when the frame carries no sun times
+    rise, set_ = window
+    hhmm = str(iso_time)[11:16]
+    return rise <= hhmm <= set_
+
+
+# ---- Main Interface Functions ----
+
+def score_hour(
+    wave_height_m: float,
+    wave_period_s: float,
+    wind_speed_kt: float,
+    wind_direction_deg: float,
+    spot: dict,
+    wave_direction_deg: Optional[float] = None,
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+    gust_kt: Optional[float] = None,
+) -> dict[str, Any]:
+    """Computes composite surf score (0-10) for a given hour and skill tier."""
+    if skill_level not in _SKILL_PROFILES:
+        raise ValueError(f"Invalid skill_level {skill_level!r}. Expected one of {SKILL_LEVELS}")
+
+    c_size = _score_swell_size(wave_height_m, spot, skill_level)
+    c_dir = (
+        _score_swell_direction(wave_direction_deg, spot)
+        if wave_direction_deg is not None
+        else None
+    )
+    c_wind = _score_wind(wind_speed_kt, wind_direction_deg, spot, skill_level, gust_kt=gust_kt)
+    c_period = _score_period(wave_period_s, skill_level)
+
+    components: dict[str, Optional[float]] = {
+        "swell_size": round(c_size, 2),
+        "swell_direction": round(c_dir, 2) if c_dir is not None else None,
+        "wind": round(c_wind, 2),
+        "period": round(c_period, 2),
+    }
+
+    # Weight redistribution when optional components are missing
+    active_weights = {k: v for k, v in _WEIGHTS.items() if components[k] is not None}
+    weight_sum = sum(active_weights.values())
+
+    composite = sum(
+        components[k] * (weight / weight_sum)  # type: ignore
+        for k, weight in active_weights.items()
+    )
+
+    return {
+        "score": round(composite, 2),
+        "components": components,
+        "skill_level": skill_level,
+        "wave_height_m": wave_height_m,
+        "wave_period_s": wave_period_s,
+        "wind_speed_kt": wind_speed_kt,
+        "wind_direction_deg": wind_direction_deg,
+        "wave_direction_deg": wave_direction_deg,
+        "gust_kt": gust_kt,
+    }
+
+
+def _pick_height(row: dict) -> float | None:
+    """Prefer the swell component; fall back to the generic aggregate."""
+    for key in ("swell_wave_height", "wave_height"):
+        v = row.get(key)
+        if v is not None:
+            return v
+    return None
+
+
+def _pick_direction(row: dict) -> float | None:
+    """Prefer the swell direction; fall back to the generic aggregate."""
+    for key in ("swell_wave_direction", "wave_direction"):
+        v = row.get(key)
+        if v is not None:
+            return v
+    return None
+
+
+def _pick_period(row: dict) -> float | None:
+    """Prefer the swell period; fall back to the generic aggregate."""
+    for key in ("swell_wave_period", "wave_period"):
+        v = row.get(key)
+        if v is not None:
+            return v
+    return None
+
+
+def score_week(
+    forecast: dict, spot: dict, skill_level: str = _DEFAULT_SKILL_LEVEL,
+    daylight_only: bool = True,
+) -> list[dict[str, Any]]:
+    """Score every (daylight) hour in a forecast frame for a target spot.
+
+    ``daylight_only=True`` (default) drops night hours using
+    ``forecast["daily"]`` sunrise/sunset; pass ``False`` to score every
+    hour. Each returned hour carries its ``"time"``. Hours missing any
+    required field are skipped.
+    """
+    rows = forecast.get("hourly", [])
+    windows = _daylight_windows(forecast.get("daily")) if daylight_only else {}
+    results = []
+
+    for row in rows:
+        if daylight_only and not is_daylight(str(row.get("time", "")), windows):
+            continue
+        wave_height = _pick_height(row)
+        wave_period = _pick_period(row)
+        wind_speed = row.get("wind_speed_10m")
+        wind_dir = row.get("wind_direction_10m")
+
+        if None in (wave_height, wave_period, wind_speed, wind_dir):
+            continue
+
+        gust_raw = row.get("wind_gusts_10m")
+        try:
+            gust_kt = float(gust_raw) * 0.539957 if gust_raw is not None else None
+        except (TypeError, ValueError):
+            gust_kt = None
+
+        scored = score_hour(
+            wave_height_m=float(wave_height),
+            wave_period_s=float(wave_period),
+            wind_speed_kt=float(wind_speed) * 0.539957,  # km/h to knots conversion
+            wind_direction_deg=float(wind_dir),
+            spot=spot,
+            wave_direction_deg=(
+                float(_pick_direction(row))
+                if _pick_direction(row) is not None
+                else None
+            ),
+            skill_level=skill_level,
+            gust_kt=gust_kt,
+        )
+        scored["time"] = row["time"]
+        results.append(scored)
+
+    return results
+
+
+def _percentile(xs: list[float], q: float) -> float:
+    """Linear-interpolation percentile (q in 0..1) over a non-empty list."""
+    s = sorted(xs)
+    if len(s) == 1:
+        return float(s[0])
+    rank = q * (len(s) - 1)
+    lo = int(math.floor(rank))
+    hi = int(math.ceil(rank))
+    if lo == hi:
+        return float(s[lo])
+    frac = rank - lo
+    return float(s[lo] * (1 - frac) + s[hi] * frac)
+
+
+def daily_summary(scored_hours: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Per-date summary of scored hours: p75 score (consistency signal).
+
+    Returns ``[{"date", "p75", "best", "n", "surfable_hours"}]`` sorted by
+    date, where ``surfable_hours`` counts hours with score ≥ 6.
+    """
+    by_date: dict[str, list[float]] = {}
+    for h in scored_hours:
+        t = h.get("time")
+        if not isinstance(t, str):
+            continue
+        try:
+            score = float(h["score"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        by_date.setdefault(t[:10], []).append(score)
+
+    out = []
+    for date in sorted(by_date):
+        scores = by_date[date]
+        out.append(
+            {
+                "date": date,
+                "p75": round(_percentile(scores, 0.75), 2),
+                "best": round(max(scores), 2),
+                "n": len(scores),
+                "surfable_hours": sum(1 for s in scores if s >= SURFABLE_THRESHOLD),
+            }
+        )
+    return out
+
+
+def rank_spots(
+    forecasts: dict[tuple[str, str], dict],
+    spots_list: list[dict],
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+) -> list[dict[str, Any]]:
+    """Rank spots by (surfable hours with score ≥ 6, then best score).
+
+    ``forecasts`` maps ``(name, region)`` → forecast frame. Spots with no
+    frame are skipped. Ties on surfable hours break toward the higher
+    single-hour best.
+    """
+    ranked = []
+
+    for spot in spots_list:
+        key = (spot["name"], spot["region"])
+        if key not in forecasts:
+            continue
+
+        hours = score_week(forecasts[key], spot, skill_level=skill_level)
+        best_hour = max(hours, key=lambda h: h["score"]) if hours else None
+        surfable = sum(1 for h in hours if h["score"] >= SURFABLE_THRESHOLD)
+
+        ranked.append(
+            {
+                "name": spot["name"],
+                "region": spot["region"],
+                "skill_level": skill_level,
+                "surfable_hours": surfable,
+                "total_hours": len(hours),
+                "best_score": best_hour["score"] if best_hour else 0.0,
+                "best_time": best_hour["time"] if best_hour else None,
+                "best_hour": best_hour,
+            }
+        )
+
+    ranked.sort(key=lambda x: (x["surfable_hours"], x["best_score"]), reverse=True)
+    return ranked
+
+
+# Backwards-compatible alias for the v1 entry point name.
+def rank_spots_this_week(
+    forecasts: dict[tuple[str, str], dict],
+    spots_list: list[dict],
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+) -> list[dict[str, Any]]:
+    """Alias of :func:`rank_spots` (v1 name)."""
+    return rank_spots(forecasts, spots_list, skill_level=skill_level)
+
+
+__all__ = [
+    "SKILL_LEVELS",
+    "SURFABLE_THRESHOLD",
+    "DEFAULT_DIRECTION",
+    "normalize_skill",
+    "enriched_to_scoring_spot",
+    "get_coords",
+    "break_skill",
+    "wind_cap",
+    "is_daylight",
+    "score_hour",
+    "score_week",
+    "daily_summary",
+    "rank_spots",
+    "rank_spots_this_week",
+]

wavereader/seafloor.py

@@ -0,0 +1,459 @@
+"""Seafloor world-model: bathymetry grid + deterministic shape analysis (v2 port).
+
+Ported verbatim-first from ``app/seafloor.py``. v2 fixes:
+
+* **lon step in slope math** — the v1 code used the latitude step for
+  both axes (``step_km = lat_step_km  # approx square grid``). The
+  per-axis steps are now derived from the grid's own coordinates: the
+  latitude step × 111 km/deg, and the longitude step × 111 km/deg scaled
+  by ``cos(center latitude)``. (Numerically close to square for grids
+  built by :func:`_deg_offsets`, but exact for any grid.)
+* **None-cell skipping** — every elevation read goes through
+  :func:`_cell`, so missing cells are skipped in the slope walk (not just
+  the anchor cell) instead of raising ``TypeError`` on ``float(None)``.
+
+Data source: OpenTopoData ``gebco2020`` (GEBCO 2020 grid, ~450 m cells,
+negative = below sea level), with ``etopo1`` as fallback. Free, no key,
+100 locations per call — so a 9x9 grid (81 pts) fits in ONE request.
+
+Pattern mirrors ``wavereader.openmeteo``: disk cache under
+``.cache/seafloor``, stale-fallback on network failure. Static data →
+long TTL (30 days).
+
+The LLM never owns numbers: this module computes every stat + Plotly fig
+deterministically; callers (UI tab, agent tool) only narrate the results.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import time
+from pathlib import Path
+
+import httpx
+
+OPENTOPO_URL = "https://api.opentopodata.org/v1/{dataset}"
+PRIMARY_DATASET = "gebco2020"
+FALLBACK_DATASET = "etopo1"
+
+CACHE_DIR = Path(__file__).resolve().parent.parent / ".cache" / "seafloor"
+CACHE_TTL_SECONDS = 30 * 24 * 3600
+CACHE_VERSION = 1
+
+GRID_N_DEFAULT = 9  # 9x9 = 81 pts, one API call
+RADIUS_KM_DEFAULT = 1.2  # ~300 m spacing at 9x9
+MAX_LOCATIONS_PER_CALL = 100
+
+_KM_PER_DEG_LAT = 111.0
+
+
+def _deg_offsets(lat: float, radius_km: float, n: int) -> tuple[list[float], list[float]]:
+    """Lat/lng offsets for an n x n grid spanning ±radius_km."""
+    half = radius_km
+    dlat = half / 111.0
+    # Guard cos() near poles; breaks are all Australian latitudes anyway.
+    dlon = half / max(20.0, 111.0 * math.cos(math.radians(lat)))
+    if n <= 1:
+        return [0.0], [0.0]
+    lats = [((i / (n - 1)) * 2 - 1) * dlat for i in range(n)]
+    lngs = [((j / (n - 1)) * 2 - 1) * dlon for j in range(n)]
+    return lats, lngs
+
+
+def _cache_key(lat: float, lng: float, radius_km: float, n: int, dataset: str) -> str:
+    return f"v{CACHE_VERSION}_{dataset}_{round(lat, 4):.4f}_{round(lng, 4):.4f}_{radius_km:.2f}km_{n}x{n}"
+
+
+def _cache_path(lat: float, lng: float, radius_km: float, n: int, dataset: str) -> Path:
+    safe = _cache_key(lat, lng, radius_km, n, dataset).replace("/", "_")
+    return CACHE_DIR / f"{safe}.json"
+
+
+def _load_cache(lat, lng, radius_km, n, dataset) -> tuple[dict, float] | None:
+    p = _cache_path(lat, lng, radius_km, n, dataset)
+    if not p.exists():
+        return None
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    if isinstance(raw, dict) and "fetched_at" in raw and "data" in raw:
+        return raw["data"], float(raw["fetched_at"])
+    return raw, 0.0
+
+
+def _save_cache(lat, lng, radius_km, n, dataset, data: dict) -> None:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    envelope = {"fetched_at": time.time(), "data": data}
+    tmp = _cache_path(lat, lng, radius_km, n, dataset).with_suffix(".tmp")
+    tmp.write_text(json.dumps(envelope, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp, _cache_path(lat, lng, radius_km, n, dataset))
+
+
+def _fetch_dataset(lats: list[float], lngs: list[float], dataset: str) -> list[float | None]:
+    """Fetch one n x n grid; returns row-major elevations (m, None on miss)."""
+    locs = [f"{la:.5f},{lo:.5f}" for la in lats for lo in lngs]
+    out: list[float | None] = []
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        for i in range(0, len(locs), MAX_LOCATIONS_PER_CALL):
+            chunk = locs[i : i + MAX_LOCATIONS_PER_CALL]
+            resp = client.get(
+                OPENTOPO_URL.format(dataset=dataset),
+                params={"locations": "|".join(chunk)},
+            )
+            resp.raise_for_status()
+            body = resp.json()
+            if body.get("status") != "OK":
+                raise ValueError(f"OpenTopoData {dataset}: {body.get('status')}")
+            for r in body.get("results", []):
+                out.append(r.get("elevation"))
+            time.sleep(1.05)  # OpenTopoData free tier: 1 call/sec
+    return out
+
+
+def get_grid(
+    lat: float, lng: float, radius_km: float = RADIUS_KM_DEFAULT, n: int = GRID_N_DEFAULT
+) -> dict:
+    """Fetch + cache the bathymetry grid around a point.
+
+    Returns ``{"lats", "lngs", "elev", "n", "radius_km", "dataset",
+    "center"}`` with ``elev`` row-major (lat-major) in metres.
+    Serves fresh cache without network; stale cache on API failure.
+    """
+    n = max(3, min(10, int(n)))  # 10x10=100 fits one call; 11x11 would split
+    radius_km = max(0.3, min(5.0, float(radius_km)))
+    dlat, dlon = _deg_offsets(lat, radius_km, n)
+    grid_lats = [round(lat + d, 5) for d in dlat]
+    grid_lngs = [round(lng + d, 5) for d in dlon]
+
+    for dataset in (PRIMARY_DATASET, FALLBACK_DATASET):
+        cached = _load_cache(lat, lng, radius_km, n, dataset)
+        if cached is not None and time.time() - cached[1] < CACHE_TTL_SECONDS:
+            return cached[0]
+        try:
+            elev = _fetch_dataset(grid_lats, grid_lngs, dataset)
+            data = {
+                "lats": grid_lats,
+                "lngs": grid_lngs,
+                "elev": elev,
+                "n": n,
+                "radius_km": radius_km,
+                "dataset": dataset,
+                "center": {"lat": lat, "lng": lng},
+            }
+            _save_cache(lat, lng, radius_km, n, dataset, data)
+            return data
+        except (httpx.HTTPError, ValueError, KeyError):
+            if cached is not None:
+                return cached[0]
+            continue  # try fallback dataset
+    raise RuntimeError("Seafloor fetch failed (GEBCO + ETOPO1 unreachable, no cache)")
+
+
+def _finite(vals: list) -> list[float]:
+    return [float(v) for v in vals if v is not None]
+
+
+def _cell(elev: list, idx: int) -> float | None:
+    """Elevation at a flat index, or None when missing/out of range."""
+    if 0 <= idx < len(elev):
+        v = elev[idx]
+        if v is None:
+            return None
+        try:
+            return float(v)
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def _grid_steps_km(grid: dict) -> tuple[float, float]:
+    """Per-axis grid spacing in km: (lat_step, lon_step).
+
+    Derived from the grid's own coordinates — the longitude step is the
+    degree spacing × 111 km/deg scaled by ``cos(center latitude)`` —
+    instead of reusing the latitude step for both axes.
+    Falls back to the nominal ``radius_km`` spacing when coordinates are
+    degenerate.
+    """
+    n = int(grid.get("n", GRID_N_DEFAULT))
+    lats = grid.get("lats") or []
+    lngs = grid.get("lngs") or []
+    center = grid.get("center") or {}
+    try:
+        center_lat = float(center.get("lat", -30.0))
+    except (TypeError, ValueError):
+        center_lat = -30.0
+    nominal = (2 * float(grid.get("radius_km", RADIUS_KM_DEFAULT))) / max(1, n - 1)
+
+    lat_step = nominal
+    if len(lats) >= 2:
+        try:
+            lat_step = abs(float(lats[1]) - float(lats[0])) * _KM_PER_DEG_LAT
+        except (TypeError, ValueError, IndexError):
+            lat_step = nominal
+
+    lon_step = nominal
+    if len(lngs) >= 2:
+        try:
+            lon_step = (
+                abs(float(lngs[1]) - float(lngs[0]))
+                * _KM_PER_DEG_LAT
+                * math.cos(math.radians(center_lat))
+            )
+        except (TypeError, ValueError, IndexError):
+            lon_step = nominal
+
+    return max(1e-6, lat_step), max(1e-6, lon_step)
+
+
+def analyze_grid(grid: dict) -> dict:
+    """Deterministic shape stats + markdown over a fetched grid."""
+    elev = grid.get("elev") or []
+    vals = _finite(elev)
+    if not vals:
+        return {"error": "Empty seafloor grid"}
+    n = int(grid.get("n", GRID_N_DEFAULT))
+    depths = [-v for v in vals if v < 0]  # positive-down metres
+    land = [v for v in vals if v >= 0]
+
+    def _pct(xs: list[float], q: float) -> float:
+        s = sorted(xs)
+        return s[max(0, min(len(s) - 1, int(q * len(s))))]
+
+    # Center cell depth
+    ci = (n // 2) * n + (n // 2)
+    center_elev = _cell(elev, ci)
+
+    # Slope: max neighbour gradient across the grid (m per km), with the
+    # correct per-axis step (lon scaled by cos(lat)). None cells skipped.
+    lat_step_km, lon_step_km = _grid_steps_km(grid)
+    max_slope = 0.0
+    slopes: list[float] = []
+    for i in range(n):
+        for j in range(n):
+            v = _cell(elev, i * n + j)
+            if v is None:
+                continue
+            for di, dj, step_km in ((1, 0, lat_step_km), (0, 1, lon_step_km)):
+                ni, nj = i + di, j + dj
+                if ni >= n or nj >= n:
+                    continue
+                w = _cell(elev, ni * n + nj)
+                if w is None:
+                    continue
+                s = abs(w - v) / max(1e-6, step_km)
+                slopes.append(s)
+                max_slope = max(max_slope, s)
+    med_slope = _pct(slopes, 0.5) if slopes else 0.0
+
+    # Shelf vs steep classification on median + max slope
+    if med_slope >= 40:
+        shelf = "steep reef edge / drop-off"
+    elif med_slope >= 15:
+        shelf = "moderately sloping reef/shelf"
+    elif depths and _pct(depths, 0.5) <= 5:
+        shelf = "shallow, gently shelving platform"
+    else:
+        shelf = "gradual sandy shelf"
+
+    # Offshore range = relief across the box
+    relief = max(vals) - min(vals)
+
+    # Channel hint: deep outlier cells (>2x median depth) clustered off-center
+    channel_hint = False
+    if depths:
+        med_d = _pct(depths, 0.5)
+        deep_cells = sum(1 for d in depths if d > max(8.0, 2.0 * med_d))
+        channel_hint = deep_cells >= max(3, len(depths) // 8)
+
+    stats = {
+        "dataset": grid.get("dataset"),
+        "box_km": round(2 * float(grid.get("radius_km", 1.2)), 2),
+        "points": len(vals),
+        "center_elev_m": round(float(center_elev), 1) if center_elev is not None else None,
+        "min_elev_m": round(min(vals), 1),
+        "max_elev_m": round(max(vals), 1),
+        "mean_elev_m": round(sum(vals) / len(vals), 1),
+        "max_depth_m": round(max(depths), 1) if depths else 0.0,
+        "median_depth_m": round(_pct(depths, 0.5), 1) if depths else 0.0,
+        "land_fraction": round(len(land) / len(vals), 2),
+        "relief_m": round(relief, 1),
+        "median_slope_m_per_km": round(med_slope, 1),
+        "max_slope_m_per_km": round(max_slope, 1),
+        "shelf_class": shelf,
+        "channel_hint": channel_hint,
+    }
+
+    md = (
+        f"**Seafloor ({stats['dataset']}, {stats['box_km']} km box, {stats['points']} pts)** — "
+        f"centre {stats['center_elev_m']} m · "
+        f"deepest {stats['max_depth_m']} m · median depth {stats['median_depth_m']} m · "
+        f"relief {stats['relief_m']} m · land {stats['land_fraction'] * 100:.0f}%.\n\n"
+        f"- **Shape:** {shelf} (median slope {stats['median_slope_m_per_km']} m/km, "
+        f"max {stats['max_slope_m_per_km']} m/km).\n"
+        f"- **Channels:** {'possible deeper gutter(s) — compare the blue pockets on the map' if channel_hint else 'no strong channel signal at this resolution'}.\n"
+        f"- **Surf read:** {('steep drops focus swell fast — expect punchier, more tide-sensitive peaks' if 'steep' in shelf else ('mid-slope reef — swell jacks up over the edge, check the transect' if 'moderately' in shelf else 'gentle shelf spreads energy — softer, more forgiving, needs more swell'))}."
+    )
+    return {"stats": stats, "markdown": md}
+
+
+# ---- Plotly builders ----
+
+_EARTH_COLORSCALE = [
+    [0.0, "#08306b"],
+    [0.25, "#2171b5"],
+    [0.45, "#6baed6"],
+    [0.55, "#fef0d9"],
+    [0.75, "#a8ddb5"],
+    [1.0, "#006d2c"],
+]
+
+_NO_DATA_FIG_TEXT = "No seafloor data"
+
+
+def _empty_fig():
+    import plotly.graph_objects as go
+
+    fig = go.Figure()
+    fig.add_annotation(text=_NO_DATA_FIG_TEXT, showarrow=False, font={"size": 16})
+    return fig
+
+
+def _grid_z(grid: dict) -> list[list[float | None]]:
+    n = int(grid.get("n", GRID_N_DEFAULT))
+    elev = grid.get("elev") or []
+    return [[elev[i * n + j] if i * n + j < len(elev) else None for j in range(n)] for i in range(n)]
+
+
+def build_depth_fig(grid: dict, name: str = ""):
+    """2D depth map (blue = deep, green = land) with centre marker."""
+    import plotly.graph_objects as go
+
+    if not grid.get("elev"):
+        return _empty_fig()
+    z = _grid_z(grid)
+    fig = go.Figure(
+        go.Heatmap(
+            x=grid["lngs"],
+            y=grid["lats"],
+            z=z,
+            colorscale=_EARTH_COLORSCALE,
+            colorbar={"title": "m"},
+            hovertemplate="lat %{y:.4f}<br>lng %{x:.4f}<br>elev %{z:.0f} m<extra></extra>",
+            name="depth",
+        )
+    )
+    c = grid.get("center") or {}
+    if c:
+        fig.add_trace(
+            go.Scatter(
+                x=[c.get("lng")],
+                y=[c.get("lat")],
+                mode="markers",
+                marker={"size": 12, "color": "#FFD700", "symbol": "star",
+                        "line": {"width": 1, "color": "#0b2c5c"}},
+                hovertemplate=f"{name} takeoff zone<extra></extra>",
+                name="break",
+            )
+        )
+    fig.update_layout(
+        title=f"Depth around {name}" if name else "Depth",
+        height=340,
+        margin={"l": 50, "r": 50, "t": 50, "b": 40},
+        xaxis={"title": "lng"},
+        yaxis={"title": "lat", "scaleanchor": "x", "scaleratio": 1},
+        paper_bgcolor="white",
+        plot_bgcolor="white",
+    )
+    return fig
+
+
+def build_surface_fig(grid: dict, name: str = ""):
+    """3D seafloor surface (the 'world model' view)."""
+    import plotly.graph_objects as go
+
+    if not grid.get("elev"):
+        return _empty_fig()
+    z = _grid_z(grid)
+    fig = go.Figure(
+        go.Surface(
+            x=grid["lngs"],
+            y=grid["lats"],
+            z=z,
+            colorscale=_EARTH_COLORSCALE,
+            colorbar={"title": "m"},
+            hovertemplate="elev %{z:.0f} m<extra></extra>",
+        )
+    )
+    fig.update_layout(
+        title=f"3D seafloor — {name}" if name else "3D seafloor",
+        height=380,
+        margin={"l": 0, "r": 0, "t": 50, "b": 0},
+        scene={"xaxis": {"title": "lng"}, "yaxis": {"title": "lat"},
+               "zaxis": {"title": "m"}, "aspectmode": "auto"},
+        paper_bgcolor="white",
+    )
+    return fig
+
+
+def build_transect_fig(grid: dict, name: str = ""):
+    """Shore-normal-ish transects: W–E + S–N slices through the centre row/col."""
+    import plotly.graph_objects as go
+
+    if not grid.get("elev"):
+        return _empty_fig()
+    n = int(grid.get("n", GRID_N_DEFAULT))
+    z = _grid_z(grid)
+    mid = n // 2
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=grid["lngs"], y=z[mid], mode="lines+markers",
+            line={"color": "#1f77b4", "width": 2},
+            name="W–E slice", hovertemplate="lng %{x:.4f}<br>elev %{y:.0f} m<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=grid["lats"], y=[row[mid] for row in z], mode="lines+markers",
+            line={"color": "#ff7f0e", "width": 2},
+            name="S–N slice", hovertemplate="lat %{x:.4f}<br>elev %{y:.0f} m<extra></extra>",
+        )
+    )
+    fig.add_hline(y=0, line_width=1, line_dash="dash", line_color="#888")
+    fig.update_layout(
+        title=f"Transects through {name}" if name else "Transects",
+        height=260,
+        margin={"l": 50, "r": 30, "t": 50, "b": 40},
+        xaxis={"title": "degrees"},
+        yaxis={"title": "elevation (m, 0 = sea level)"},
+        paper_bgcolor="white",
+        plot_bgcolor="white",
+        legend={"orientation": "h", "y": 1.12, "x": 1.0, "xanchor": "right"},
+    )
+    return fig
+
+
+def get_seafloor(
+    lat: float, lng: float, radius_km: float = RADIUS_KM_DEFAULT, n: int = GRID_N_DEFAULT
+) -> dict:
+    """One-call fetch + analysis: ``{"grid", "analysis", "stats"}``."""
+    grid = get_grid(lat, lng, radius_km=radius_km, n=n)
+    analysis = analyze_grid(grid)
+    return {"grid": grid, "analysis": analysis.get("markdown", ""),
+            "stats": analysis.get("stats", {})}
+
+
+__all__ = [
+    "GRID_N_DEFAULT",
+    "RADIUS_KM_DEFAULT",
+    "get_grid",
+    "analyze_grid",
+    "build_depth_fig",
+    "build_surface_fig",
+    "build_transect_fig",
+    "get_seafloor",
+]