feat: Wildlife Sightings layer from iNaturalist and Acartia

Recent community wildlife observations, as a new Wildlife group in the
layer panel.

- Server: keyless iNaturalist proxy (v2 observations with only the
  projected fields; undocumented v1 UTFGrid density tiles, decoded on the
  server) sharing one paced queue (burst 4, ~1/s, 60/min, 8,000/day budget,
  up to four in flight), in-memory caches and upstream-only cooldowns;
  Acartia Salish Sea marine-mammal feed rounded to 0.01 degrees with
  comments dropped.
- Layer: grid counts drawn as a soft view-ranked density glow; real sampled
  sightings as taxon badges at their true positions with ambient photo
  thumbnails and labels; obscured records stay privacy cells; a clicked
  sighting stays pinned through camera moves and refreshes.
- Anchored photo card per selection with the single iNaturalist link;
  attribution in the layer row and the Data attribution popover.
- Filters (CONFIRMED, taxa presets) round-trip in share links with token 9.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/CURRENT-STATE.md

@@ -98,6 +98,93 @@ across the antimeridian, so they cannot use the strict ±180 check as-is, and
 `src/sources/adsbRecords.js` and `server/providers/common/geo.js` keep their own
 implementations.
 
+## Wildlife Sightings — iNaturalist and Acartia
+
+**Wildlife Sightings** (`wildlife-sightings`, share-link token `9`) is off by
+default in the Wildlife group between Events and Weather. CONFIRMED and six
+taxa presets round-trip in share links. Voice is off for this layer for now;
+it is outside analyst queries and DETECT. Community observations are not a
+census; private records are excluded.
+
+`/api/inaturalist/observations` requests verifiable wildlife in view within
+48 h (whales 7 d). Recency uses observation time: the `d1` date filter and a
+strict rolling cutoff. Date-only rows qualify only when their day starts
+within the window. Close views use a cached random sample of at most 200 rows;
+global samples use newest observations first. Observation caches last five
+minutes (global ten minutes), with stale fallback for at most one hour.
+
+Observations and grid tiles share a paced priority queue: a four-call burst,
+then one request per second, at most four in flight, ≤60/minute and a persisted
+8,000/day budget. Superseded consumers leave before dispatch. The recovered
+queue tail isolates failures; ordinary grid failures do not fail observations.
+Provider 429 cooldown is shared; 5xx cooldown is resource-specific. Failed tiles
+retain good cells for at most one hour. Stale replies carry `X-Data-Stale` and
+known `Retry-After`. Failures keep filters and drawn rows, reporting DEGRADED
+with retry timing; logs exclude request URLs and upstream exception text.
+
+`/api/acartia/sightings` adds Salish Sea marine mammals within 45.5–50.5° N,
+126–121° W, cached ten minutes and stale for at most 24 h. WHALES accepts only
+recognized cetaceans; other identified marine mammals appear under ALL or
+MAMMALS. Sensitive iNaturalist locations remain 0.2° privacy cells; Acartia
+positions are rounded to 0.01° on the server. Acartia comments are never retained.
+Observer identity is retained only for photo attribution.
+
+`/api/inaturalist/grid` supplies a dedicated, nonpickable billboard density glow,
+with a view-relative density ramp from cool teal to warm amber. Overlapping
+Gaussian splats span four logical cell widths; mono and CRT styles follow map
+and cockpit vision changes. Empty snapshots paint nothing. Full footprints
+stay inside the globe limb with a 5% radius margin; opacity fades from full at
+3,000 km to zero at 8,000 km camera altitude. Culling and cached coordinates
+add no per-frame work and leave sighting counts intact.
+
+Only real sampled observation rows produce taxon badges at their public
+positions. The badges use 28 px screen buckets, a 22 px overlap check and a
+5,000-observation cap. Tinted circles have a white Material Symbols glyph and
+1.5 px dark outline, remaining 12–22 px at all distances, including selection.
+Glyphs: birds `raven`, mammals `pets`, reptiles `egg_alt`, amphibians
+`water_drop`, fishes `set_meal`, insects `bug_report`, arachnids `pest_control`,
+plants `eco`, fungi `umbrella`, other animals `category`, unknown `question_mark`.
+A plain circle displays while the icon font loads. Row counts read
+“{n} sightings in view”, using visible grid totals when available.
+
+Views request at most six tiles, coarsening zoom for complete coverage. Server
+and client keep bounded 400-tile caches for 15 minutes. Cached, stale and
+adjacent-zoom tiles publish before network waits; each arriving tile replaces
+its covered area, including healthy empty tiles. Grid tiles publish even while
+the independent observation request is pending or failed. Enable waits for one
+camera settle; camera acquisition uses moveEnd with a 600 ms debounce. The
+undocumented UTFGrid endpoint has a schema guard; see `KNOWN-ISSUES.md`.
+
+Ambient cards use a fixed 96 px image width and a short creator name credit,
+with a bounded frame cache. New cards fill free screen regions; visible cards
+survive a random sample refresh until they leave the view or observation
+window. The 110/125 km show/hide thresholds provide hysteresis; cards scale
+and fade gradually through 120 km. Only painted photos suppress their own
+badge and label. Labels yield to painted cards, then compete by ambient score;
+repeated translated names within 80 screen pixels yield to higher-priority
+content. At most 150 labels enter the host. Titles prefer a word boundary for
+ellipses; accessible names remain complete. Selected thumbnails or names use
+the shared selected chrome and paint lane, with no canvas source link.
+
+Clicking a badge, label or photo flies to its supplied position and opens a
+compact anchored photo card. Selection stays pinned across camera, filter and
+sample changes until explicit deselection or layer disable. Its medium image
+uses `object-fit: contain`, with names, compact observed age and creator/licence.
+The card is the single source link to iNaturalist. Obscured sightings also stay
+text-only; Acartia stays text-only with provider credit and whale guidance.
+Placement avoids actual HUD, toolbar and rail rectangles, panning only when
+necessary while preserving zoom. Escape, close or an outside click closes the
+card and clears selection. Camera/layout changes reposition the card without
+an idle frame listener; shell teardown also removes its host and subscription.
+
+Attribution appears in the layer row and Data attribution popover:
+“iNaturalist contributors · licences per record”, plus Acartia when drawn.
+Disable/destroy releases the glow collection, texture atlas, timers, queues and
+style listeners. Synthetic fixtures cover privacy, acquisition, rendering,
+selection and card placement. Deterministic operation checks run in `npm test`;
+wall-clock budgets run in `npm run test:perf`. All 11 locales are supported.
+
+
 ## Prohibited & Restricted Airspace — FAA special-use airspace
 
 The Infrastructure group includes **Prohibited & Restricted Airspace** (`drone-airspace`,
@@ -1541,6 +1628,8 @@ are owned by a renderer-free panel component. The layer manager supplies current
 snapshots, lifecycle actions and row descriptors. Remount and teardown remove
 listeners and row subscriptions; obsolete completions do not repaint old rows.
 The clear control presents busy state while its existing action owns the transaction.
+The Wildlife group follows Events and precedes Weather; Wildlife Sightings
+provides its confirmed toggle, taxa presets and fixed-order, nonempty legend.
 
 ## Sky background
 
@@ -4212,6 +4301,7 @@ its criteria cannot be silently ignored.
 | Ski Pistes ⛷ (`ski-pistes`) | OpenSnowMap piste raster tiles (keyless; CC BY-SA tiles, OSM data ODbL; no bulk download) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) |
 | Fire Perimeters 🔥 | NIFC WFIGS current interagency perimeters (keyless, paged past the 2000-record cap); InciWeb catalog + incident page origin and update time checks for verified incident-page links | `src/layers/perimeters/` via `src/app/layers/perimeters.js` | `/api/fire-perimeters` + `/api/fire-perimeters/inciweb/*` | 5 min (server caches: catalog 1 h; publication 30 min) |
 | Prohibited & Restricted Airspace 🚫 | FAA Special Use Airspace prohibited (P) and restricted (R) zones (keyless FeatureServer, simplified geometry) | `src/layers/droneAirspace/` via `src/app/layers/droneAirspace.js` | `/api/drone-airspace` | 1 h (server cache 1 h; stale-on-error) |
+| Wildlife Sightings 🦉 | iNaturalist wildlife observed within 48 h (whales 7 d), per view; Acartia Salish Sea marine mammal coverage (keyless) | `src/layers/wildlifeSightings/` via `src/app/layers/wildlifeSightings.js` | `/api/inaturalist/observations`, `/api/inaturalist/grid`, `/api/acartia/sightings` | camera moveEnd (600 ms debounce; enable settles 300 ms) + 5 min (observations 5 / 10 min; tiles 15 min; stale ≤ 1 h / 24 h) |
 
 GNSS Integrity samples a 250 nm circle around the Earth point under the screen
 centre. Camera reads debounce for 600 ms with a monotonic 2.5 s minimum gap;

docs/KNOWN-ISSUES.md

@@ -10,6 +10,22 @@ For the roadmap and open backlog, see the repository issue tracker.
 
 ## Open
 
+### Wildlife grid is an undocumented iNaturalist endpoint
+
+Status: Open (guarded fallback)
+
+The operational `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is not part of the
+published v1 Swagger contract. Its 64×64 UTFGrid shape, keys and cell records
+are validated in full at the allow-list proxy. A schema change or unavailable
+tile retains its last good cells for at most one hour; a cold unavailable grid
+uses sampled observations with the same badges and screen buckets, without
+claiming complete worldwide coverage. Tests use
+synthetic fixtures with the locally inspected tile's exact structure. Retest
+and update the schema guard before accepting an upstream shape change. Grid
+and observation calls share the paced queue, provider budget and 429 cooldown;
+ordinary tile failures do not block observation queries.
+
+
 ### Street traffic can be slow/uneven when panning across dense city blocks
 Status: Open (partially mitigated)