GODSIGH/SPEC3.md

# GODSIGH — Wave 3 Build Spec (the layer registry)

**Audience:** Claude Opus 4.8, executing autonomously in this repo.
**Author:** Claude Fable 5, 2026-07-13, after reviewing the completed Wave 1 + Wave 2 builds.
**Prerequisite:** Waves 1–2 are COMPLETE at `403884e`. Read SPEC.md §2/§7/§10 and SPEC2.md §1/§8/§9 first; every rule there still binds (relative URLs, no build step, entities-vs-primitives, `[DEMO]` labeling, per-phase verify-then-commit). Deployment (SPEC.md §9) is unchanged and still gated on John.

---

## 0. Mission & the core idea

Wave 2 proved that most new layers are the same shape: *fetch GeoJSON-ish data on an interval, drop styled entities on the globe, report status.* `quakes.js` and `fires.js` are 90% identical boilerplate. That doesn't scale to the 15+ feeds we want.

**Wave 3 makes adding a layer a data-entry task, not a coding task.** Build a **data-source registry** + a **generic GeoJSON layer factory**, refactor the two Wave 2 real-data layers onto it to prove parity, then seed the registry with a batch of verified new feeds and a collapsible categorized HUD. The bespoke layers (satellites, aircraft, ships, infra, events) stay exactly as they are — they have real per-layer logic that a generic factory shouldn't swallow.

**Done looks like:** a `js/registry.js` manifest where one object literal = one working layer; `quakes`/`fires` rebuilt as registry entries with no behavior change; ~6 new real layers live (military aircraft, severe-weather alerts, global disasters, rocket launches, aurora, NSW bushfires) under a categorized, collapsible HUD; and a NASA GIBS time-dimensioned imagery option. Two feeds (GDELT news, adsb.lol proxying) are investigate-first.

## 1. Ground truth — verified 2026-07-13 by Fable (do not re-probe)

Probed with a browser-like `Origin` header from this machine:

| Feed | URL | CORS | Geometry / shape | Verdict |
|---|---|---|---|---|
| **adsb.lol military** | `https://api.adsb.lol/v2/mil` | **NO ACAO — needs proxy** | `{ac:[{hex,flight,lat,lon,alt_baro,gs,track,...}]}`, ~251 ac | proxy it |
| **NWS alerts (US)** | `https://api.weather.gov/alerts/active?severity=Severe,Extreme` | `ACAO: *` | GeoJSON FeatureCollection; features may have `null` geometry (skip those) | direct |
| **GDACS disasters** | `https://www.gdacs.org/gdacsapi/api/events/geteventlist/MAP` | `ACAO: *` | GeoJSON FeatureCollection, Point geometry | direct |
| **Launch Library 2** | `https://ll.thespacedevs.com/2.2.0/launch/upcoming/?limit=30&mode=list` | `ACAO: *` | JSON `{results:[{name,net,pad:{latitude,longitude,location}}]}` — NOT GeoJSON | direct, custom adapter |
| **NOAA aurora** | `https://services.swpc.noaa.gov/json/ovation_aurora_latest.json` | `ACAO: *` | `{coordinates:[[lon,lat,aurora%],...]}` ~920 KB grid — NOT points | direct, special layer |
| **NSW RFS bushfires** | `https://www.rfs.nsw.gov.au/feeds/majorIncidents.json` | `ACAO: *` | GeoJSON; features carry `GeometryCollection` (Point + Polygon) | direct |
| **NASA GIBS** | `https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/{Layer}/default/{Time}/{TileMatrixSet}/{z}/{y}/{x}.jpg` | `ACAO: *` | WMTS raster tiles, time-dimensioned | direct, imagery |
| **GDELT geo** | `https://api.gdeltproject.org/api/v2/geo/geo?query=…&format=GeoJSON` | 404 on my query formats | GeoJSON when the query is right, but params are finicky | **investigate-first** |

adsb.lol has no rate limit or key (community ADS-B). GIBS/NWS/GDACS/Launch Library/NOAA are all free, keyless, public.

## 2. Locked design decisions

1. **Registry, not inheritance.** `js/registry.js` default-exports an array of plain-object layer specs. `main.js` iterates it and instantiates each via the generic factory. Bespoke layers stay as their own modules in `LAYER_MODULES` — the registry is *additive*, both lists load.
2. **Two generic factories, not one.** `js/layers/geojson-layer.js` (entity layers from point/polygon GeoJSON) and `js/layers/imagery-layer.js` (WMTS/tile overlays like GIBS). A feed that's neither (aurora grid, Launch Library's non-GeoJSON JSON) either gets a small `adapt()` function in its registry entry that returns a normalized feature array, or stays a bespoke module — decide per feed (§5).
3. **Everything relative or full-`https://`.** Same rule as always: same-origin paths relative (`proxy/…`), cross-origin feeds are full `https://` URLs living only in the registry. The subpath audit (`grep -rnE "fetch\(['\"]/|src=['\"]/" js/`) must stay empty.
4. **No behavior regressions.** After refactoring quakes/fires onto the factory, the app must look and behave identically — same counts, colors, time-anchoring, labels, statuses. Verify side-by-side against the current build.
5. **Categories + collapse.** At 12+ layers a flat HUD is unusable. Group rows by category, collapsible, most new layers **default OFF** to keep first paint clean and quota/clutter down.
6. **`[DEMO]` rule still holds** — but note almost everything in this wave is REAL. Only label demo data.

## 3. Phase 1 — the GeoJSON layer factory

New file `js/layers/geojson-layer.js`. Export `createGeoJsonLayer(ctx, spec)` returning the standard `{ id, onClockTick?, ... }` contract object. It must express everything quakes/fires need, driven by `spec`:

```js
// A registry entry consumed by createGeoJsonLayer.
{
  id: 'quakes',
  name: 'Earthquakes (USGS)',
  category: 'Earth',
  defaultOn: true,
  url: 'https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson',
  refreshMs: 300000,
  // Turn a raw response into an array of normalized features. Default assumes
  // GeoJSON FeatureCollection; override for odd shapes.
  adapt: (json) => json.features,
  // Pull geometry → {lon, lat} from one feature (handles Point, Polygon-centroid,
  // GeometryCollection — factor the fires.js/quakes.js logic here as the default).
  // Return null to skip a feature.
  locate: (f) => ({ lon, lat }),
  // Stable id for dedupe across refreshes; return null to rebuild-wholesale each time.
  featureId: (f) => f.id,
  // Optional: availability start for time-anchoring (return a Date/ms, or null for always-on).
  timeAt: (f) => f.properties.time,
  // Visual spec per feature.
  style: (f) => ({
    color: '#ff3b30', pixelSize: 8, // OR glyph: sharedCanvas / billboard opts
    label: 'M5.2 …' | null,          // null = no label (declutter)
    labelFade: [2.0e6, 1.2e7],       // NearFarScalar near/far, optional
    pulseIf: (f) => boolean,          // recent-event pulse, optional
  }),
  description: (f) => '<table>…</table>', // InfoBox HTML
  cap: 400,                              // max entities; drop by a sort key
  sortKey: (f) => f.properties.mag,      // for the cap (keep highest)
  status: ({shown, extra}) => `${shown} quakes${extra}`, // HUD status text
}
```

Requirements the factory must honor (all already solved in quakes.js/fires.js — lift the logic):
- `Promise`-safe polling loop (self-scheduling `setTimeout`, `inFlight` guard, keeps polling regardless of scrub since these are historical/live-record feeds).
- Dedupe-by-id with **revision detection** (rebuild an entity when its content signature changes — quakes.js already does this; make it the default when `featureId` is provided).
- Time-anchoring via `timeAt` (clamp intervals to `[ctx.start, ctx.stop]`, exactly quakes.js's `availabilityFor`).
- Cap by `sortKey` (drop smallest/least-important first).
- Never trust `Content-Type` (EONET lies — §SPEC2). Guard null geometry, null coords, missing props everywhere.
- Full error→status reporting (`ok`/`warn`/`err`), no silent failures.
- Register its HUD row + category via the new UI API (§6).

**Do not build any real feed yet** — just the factory + a trivial inline test spec, verified to render.

## 4. Phase 2 — refactor quakes & fires onto the factory (parity proof)

Rebuild `quakes` and `fires` as **registry entries** (move them into `registry.js`), delete `js/layers/quakes.js` and `js/layers/fires.js`, and remove them from `LAYER_MODULES`. This is the acid test that the factory is expressive enough.

- Quakes entry: `timeAt` = origin time (keeps the appears-as-slider-crosses behavior), amber→red `magColor` ramp in `style`, labels for M≥4.5, revision-aware dedupe, cap 400 by magnitude, the pulse-if-<1h.
- Fires entry: no `timeAt` (wholesale rebuild), flame glyph billboard, aggressive label fade, cap 500.
- **Verify parity in the browser:** counts, colors, labels, time-anchoring (scrub back → quakes vanish), statuses must match the pre-refactor build exactly. Screenshot both before/after if unsure. Commit only when identical.

## 5. Phase 3 — seed the registry with new real layers

Add these as registry entries (or bespoke where noted). Each gets a category, `defaultOn: false` unless noted, verify each renders, commit per feed or in small batches.

**Category "Air":**
- **Military aircraft** (`adsb.lol/v2/mil`) — needs the proxy: add `mil` to `serve.py`'s `UPSTREAMS` (`https://api.adsb.lol/v2/mil`) and an nginx block in SPEC.md §9's list (same resolver caveat — document it). Fetch `proxy/mil`. This is a BillboardCollection primitive like civil aircraft, NOT entities (could be hundreds) — so it may be a **bespoke module reusing aircraft.js's rendering**, or a factory "primitive mode." Judge which is cleaner; if bespoke, factor the shared billboard build out of aircraft.js. Tint military-red `#ff5964`, glyph rotated by `track`, click overlay with `flight`/`hex`/alt/speed. Poll ~60 s (no quota limit). This supersedes Wave 2's callsign-guess military filter — keep that filter for civil OpenSky, but real mil data is separate and better.

**Category "Human":**
- **Severe weather alerts** (`api.weather.gov/alerts/active?severity=Severe,Extreme`) — GeoJSON factory. Many features have polygon geometry AND some have `null` geometry (skip null). Style: amber translucent polygons (`PolygonHierarchy` from the ring) + a point+label at the centroid; `timeAt` = `properties.onset` or `sent` (time-anchored). US-only — note that in the description. `defaultOn: false`.
- **Global disasters** (`gdacs.org/…/geteventlist/MAP`) — GeoJSON factory, Point geometry. Icon/color by `properties` event type (EQ/TC/FL/VO/DR/WF) and alert level (green/orange/red). Label the event name. Global. `timeAt` if a timestamp is present.

**Category "Space":**
- **Rocket launches** (Launch Library 2) — NOT GeoJSON, so `adapt: (j) => j.results` + `locate: (r) => ({lon: r.pad.latitude, lon…})` reading `pad.latitude/longitude`. Time-anchor to `net` (the launch window) so upcoming launches appear as the slider reaches them — but note most `net` values are in the FUTURE beyond the +6h window, so also render them statically at their pad with a "T-…" countdown in the label/description. A rising rocket glyph. `defaultOn: false`.
- **Aurora oval** (NOAA OVATION) — NOT points, it's a ~920 KB `[[lon,lat,prob],...]` grid. This is a **bespoke module**, not a factory layer: sample the grid (every Nth point, prob>10), render as a translucent green point cloud or a coarse polygon band near both poles, alpha ∝ probability. Refresh ~5 min. `defaultOn: false`. Gorgeous in Photo mode.

**Category "Regional — Australia" (collapsed by default):**
- **NSW RFS bushfires** (`rfs.nsw.gov.au/feeds/majorIncidents.json`) — GeoJSON factory. Features carry `GeometryCollection` (Point + Polygon) — `locate` uses the Point; optionally draw the polygon fire-ground. Color by `properties` alert level (advice/watch-act/emergency). Label the incident name. `timeAt` from the pubDate if present. This is John's home-turf detail pack; a stub for adding VIC/QLD equivalents later.

## 6. Phase 4 — categorized collapsible HUD

Extend `js/ui.js`:
- `addLayer(id, name, defaultOn, onToggle, category)` — new optional `category` (default `'Core'`). Rows render grouped under a collapsible category header (▸/▾), with a per-category count and a category-level show/hide-all toggle. Preserve the existing flat API for the bespoke layers (they land in `'Core'`).
- Categories in display order: **Core, Space, Air, Sea, Earth, Human, Regional — Australia**. Bespoke Wave 1 layers map to Core/Space/Air/Sea; quakes→Earth, fires→Earth (or a "Land" category — your call, keep it sensible).
- `getLayerIds`/`getLayerChecked`/`setLayerChecked` must keep working (URL-state depends on them). Collapsed state is UI-only — do NOT serialize it into the hash (keep the hash stable).
- Keep the HUD scrollable and within its existing max-height; categories collapsed-by-default for Regional and any all-off category, expanded for Core.
- CSS: match the existing dark HUD idiom (the category header styled like a quiet section divider). Don't fight Cesium widget CSS.

## 7. Phase 5 — NASA GIBS imagery option

New file `js/layers/imagery-layer.js` + registry support for `kind: 'imagery'` entries. GIBS is time-dimensioned raster — a third basemap-ish skin:
- Add a GIBS `UrlTemplateImageryProvider` whose `{Time}` is driven by the Cesium clock (the current day, `YYYY-MM-DD`; MODIS true-color is daily). Start with `MODIS_Terra_CorrectedReflectance_TrueColor` (`GoogleMapsCompatible_Level9`, `.jpg`), and `VIIRS_SNPP_Thermal_Anomalies_375m_All` as a fire overlay option.
- This is NOT a HUD entity layer — it's an imagery layer with an opacity slider, sitting above the Photo basemap. A small "Imagery" section in the HUD (or a mode addition): off by default; when on, add the layer to `viewer.imageryLayers` with `alpha ~0.85`.
- When the clock is scrubbed to a past day, refetch tiles for that date (GIBS has years of history) — a genuine "satellite imagery time machine." Debounce on day-change, not every tick.
- Attribution: "NASA EOSDIS GIBS" — add to the credits.
- If wiring the clock→time dimension cleanly proves fiddly, ship it fixed to "yesterday" (today's mosaic is often incomplete) with a note, rather than half-working scrubbing.

## 8. Phase 6 — investigate-first: GDELT geocoded news

Time-boxed, same discipline as the Wave 2 GPS-jam stretch:
1. GDELT's GEO 2.0 API returned 404 on my `?query=protest&format=GeoJSON` attempts — the query grammar is particular. Investigate the correct params (it wants a specific `query=` DSL and `format=GeoJSON`; check `https://blog.gdeltproject.org` GEO 2.0 docs). Confirm a working URL that returns GeoJSON points with `ACAO`.
2. If it works: a GeoJSON-factory layer, category "Human", `defaultOn: false`, points at article locations, label = the location name, description links the source articles, `timeAt` from the article time if present. Note GDELT's terms/attribution.
3. If the query grammar stays ambiguous or CORS blocks it: document findings in the README roadmap and stop. Don't scrape around it.

## 9. Verification & workflow

- Per phase: SPEC.md §7 protocol (clean console on fresh load, network 200s, screenshots, HUD statuses, toggle checks) + the phase's own checks. `node --check` every touched JS file. Subpath audit stays empty.
- **Parity is the headline check for Phase 2** — the refactor must be behavior-invisible.
- The preview tab backgrounds itself (`document.hidden`), pausing live polls and rAF — Waves 1–2 documented the workarounds (drive `onClockTick` directly; `viewer.render()` before `toDataURL`; override `document.hidden` to force a poll). Reuse them.
- Commit per phase (`wave3 phase N: …`), push after each. `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
- Update README per phase: the layers table grows a lot — consider grouping it by category to match the HUD. Mark which feeds are REAL (nearly all) vs DEMO (ships/events only). Add attributions for every new source (adsb.lol, NWS, GDACS, Launch Library/The Space Devs, NOAA SWPC, NSW RFS, NASA GIBS).
- **Run an adversarial-review workflow** over the new code before the final commit — the Waves 1–2 recipe (reviewers by dimension → verify each finding → apply confirmed). Focus dimensions: factory correctness/expressiveness, parity of the refactored layers, CORS/subpath safety, HUD state + URL-state interaction, quota/perf (poll cadences, the 920 KB aurora grid, hundreds of mil billboards).

## 10. Deployment note (for whenever John runs SPEC.md §9)

- New same-origin proxy upstream: **`mil` → `https://api.adsb.lol/v2/mil`**. Add the nginx `location` block alongside opensky/celestrak, **with the resolver directive** (the §9 gotcha — a variable in `proxy_pass` forces request-time DNS; no resolver ⇒ 502 while `nginx -t` passes). All other Wave 3 feeds are direct `https://` and need zero prod config.
- Everything else deploys as plain static files. The registry is just JS.

## 11. Out of scope for Wave 3

GPS-jam (still gated on licensing per Wave 2), oil-futures panel, Cesium ion terrain, VPS-side recorder, accounts/auth, live AIS by default, VIC/QLD/other regional packs beyond the NSW stub. Roadmap only.