feat(globe): port to CeliumJS

docs/POLAR_FINDINGS.md

@@ -0,0 +1,157 @@
+# Predictor behaviour at the poles
+
+Measured 2026-08-03 against the full local stack (`./run-stack.py`): Go predictor
+on :8080 with GFS dataset `2026-08-03T00:00:00Z` (`gfs-0p50-3h`, 130/130 units,
+2.05 GB), Django on :8000, the Cesium build of this SPA on :5173.
+
+Reproduce the browser half with:
+
+```bash
+npx playwright test tests/e2e/polar.spec.ts --reporter=list
+```
+
+That spec requires the real stack (it overrides `baseURL` to `http://localhost:5173`
+— see "CSRF" below).
+
+## 1. What the predictor returns near the poles
+
+Direct `GET /api/v1/prediction`, launch longitude 0.1, 2026-08-03T12:00:00Z,
+ascent 5 m/s, burst 30 km, descent 5 m/s:
+
+| launch lat | points | latitude range | longitude range | NaN/Inf | above 85.051129° | frozen |
+|---|---|---|---|---|---|---|
+| 62.1234 | 148 | 62.1219 … 62.3342 | 0.100 … 1.737 | 0 | no | no |
+| 85.0 | 148 | 85.0000 … 85.1535 | 0.100 … 5.560 | 0 | **yes** | no |
+| 89.5 | 148 | 88.8092 … 89.5000 | 0.100 … 55.922 | 0 | **yes** | no |
+| 89.99 | 148 | 88.9926 … 89.9900 | 0.100 … 79.279 | 0 | **yes** | no |
+
+**No NaN, no Inf, no frozen tracks.** Today's polar wind blows southward, so
+every balloon drifted away from the pole and never reached latitude 90°, where
+the defects below would trigger. The failure modes are latent, not constant.
+
+Note the longitude amplification: at 89.99°N the track sweeps 79° of longitude
+while moving 1° of latitude. That is **physically correct**, not a bug — the
+parallel at 89.99°N is only ~7 km long, so a few km of drift is a large change
+in longitude.
+
+## 2. What the globe now renders
+
+`tests/e2e/polar.spec.ts` reads back the coordinates Cesium actually holds in
+the rendered workspace polyline:
+
+```
+[89.5N]  vertices=148 max=89.50000 min=88.80919
+[89.99N] vertices=148 max=89.99000 min=88.99262
+```
+
+These match the predictor's API output exactly. Under the previous
+MapLibre renderer every one of these vertices would have been clamped to
+85.051129° by `@maplibre/geojson-vt`'s `projectY()` and the track would have
+rendered as a straight line along that parallel.
+
+Screenshots: `test-results/polar-89.5N.png`, `test-results/polar-89.99N.png`.
+
+## 3. Known limitation: no basemap above 85.051129°
+
+The polar cap renders as a featureless surface. Both configured basemaps —
+OpenStreetMap raster and Esri World Imagery — are Web Mercator tile pyramids,
+which do not extend past ±85.051129°. The trajectory, markers and bounding
+boxes draw correctly there (they are geographic vector data, not tiles), but
+there is no map detail underneath. The same limitation means **Antarctica can
+never be drawn in full** from these sources; its true extent reaches −90°.
+
+Fixing this needs a polar-projection basemap (NASA GIBS serves EPSG:3413 for
+the Arctic and EPSG:3031 for the Antarctic), which is a separate piece of work.
+
+## 4. Predictor defects found by reading the source
+
+These live in the `predictor` repo and are **not fixed**. Verified by source
+reading plus a unit probe run against the real `Axis` geometry (GFS 0p50:
+lat −90…90 step 0.5, N=361).
+
+### 4.1 The wind error is swallowed into a zero derivative — worst of the three
+
+`internal/engine/models.go:85-88`
+
+```go
+sample, err := field.Wind(t, s.Lat, s.Lng, s.Altitude)
+if err != nil {
+    return State{}          // zero derivative; error discarded
+}
+```
+
+`internal/numerics/grid.go:40` (`Axis.Locate`) is correct — it returns an
+explicit error rather than reading out of bounds:
+
+```
+lat=89     OK          lat=90      ERROR: lat=90 out of range
+lat=89.5   OK          lat=90.05   ERROR: lat=90.05 out of range
+lat=89.99  OK          lat=91      ERROR: lat=91 out of range
+```
+
+But the caller drops it, so the propagator returns a zero derivative and the
+balloon **silently freezes horizontally** with no error and no event in
+`events[]`:
+
+```
+lat=89.99  dLat=8.95e-05  dLng=0.5128576395811134
+lat=90     dLat=0         dLng=0    <-- silently zeroed
+lat=90.05  dLat=0         dLng=0    <-- silently zeroed
+lat=91     dLat=0         dLng=0    <-- silently zeroed
+```
+
+A plausible-looking wrong answer is more dangerous than a crash.
+
+### 4.2 Latitude is never bounded, so there is no pole crossing
+
+`internal/numerics/vec.go:71-73` — `GeoAdd` wraps longitude through `PyMod` but
+adds latitude unguarded:
+
+```
+step 1: lat=89.9500   step 3: lat=90.0500   step 5: lat=90.1500
+step 2: lat=90.0000   step 4: lat=90.1000   step 6: lat=90.2000
+```
+
+The state leaves the sphere. Correct pole crossing is `lat → 180 − lat`,
+`lng → lng + 180`; that logic does not exist.
+
+### 4.3 1/cos(lat) divergence against a fixed integration step
+
+`internal/numerics/vec.go:87`
+
+```go
+dLng = degPerRad * u / (r * math.Cos(lat*piOver180))
+```
+
+For a 10 m/s eastward wind at 30 km:
+
+| lat | cos(lat) | dLng °/s | ° per 60 s step |
+|---|---|---|---|
+| 0 | 1 | 8.951054359255286e-05 | 0.0054 |
+| 60 | 0.5000000000000001 | 0.00017902108718510567 | 0.0107 |
+| 85.051129 | 0.08626673450528127 | 0.0010376020850432562 | 0.062 |
+| 89.99 | 1.745329251907294e-05 | 5.128576370030803 | 307.7 |
+| 90 | 6.123233995736757e-17 | 1.461818112044611e+12 | 8.77e+13 |
+| 90.0000001 | −1.7453291532541063e-09 | −51285.766599190494 | −3.08e+06 |
+
+At exactly 90° the result is **large but finite, not NaN** — `math.Cos(π/2)` in
+float64 is `6.123233995736757e-17`, not zero. Past 90° the cosine goes negative
+and the drift direction inverts.
+
+`internal/numerics/ode.go:15` integrates with classical fixed-step RK4 — no
+adaptive step, no error control — so truncation error grows without bound as the
+derivative stiffens. At 89.999° a single 60 s step advances longitude by more
+than a full revolution. Scaling the step by `cos(lat)` would bound it.
+
+## 5. Environment notes
+
+**CSRF.** `run-stack.py` binds Vite to `127.0.0.1` but never sets
+`CSRF_TRUSTED_ORIGINS`, whose default (`stratoflights/settings.py:195`) is
+`http://localhost:5173, http://localhost:8000`. Reaching the app as
+`127.0.0.1:5173` therefore gets **403 on every POST**, including
+`/api/predictions/`. Use `localhost:5173`, or add the origin to the env block in
+`run-stack.py`. (The default value also has a leading space in its second entry
+after `split(',')`.)
+
+`ALLOWED_HOSTS` has the same shape: it defaults to `localhost` only, so
+`curl 127.0.0.1:8000` returns 400 while `curl localhost:8000` returns 200.