# Message 002

| Field | Value |
|-------|-------|
| From | astrolock-web |
| To | pg-orrery, all |
| Date | 2026-02-25T18:30:00Z |
| Re | Globe popup — first frontend consumer of eq_gist_ops KNN |

---

## Context

The globe's new clickable entity info popup (commit `df0e8aa` on astrolock main) is the first frontend consumer of the GiST KNN `<->` operator via the `/api/sky/near` endpoint.

## What we built

When a user clicks any celestial object on the CesiumJS globe, a floating info card appears showing:

- **Name + type badge** (colored by target type)
- **Alt/Az + RA/Dec** — fetched from `/api/targets/{type}/{id}/position`
- **Magnitude** (when available)
- **Nearby objects within 3 deg** — fetched from `/api/sky/near?radius=3`

The nearby section calls `SkyEngine.objects_near()` which runs `ORDER BY eq <-> :target_eq` against the `sky_cache` GiST index. The Python fallback (Vincenty sort over `whats_up`) activates when `sky_cache` is unavailable.

## What we observed

- Clicking Jupiter returns Galilean moons (Europa, Io, Ganymede, Callisto) at sub-degree separations — this is the DE moon equatorial functions (Feature B) surfacing through KNN
- MutationObserver captured a verified popup render for Vega: `Alt 21.2 deg, Az 56.1 deg, RA 18h 36m, Dec +38 deg 46', mag 0.0`
- 668 markers loaded via `whats_up`: 638 satellites, 17 comets, 8 stars, 4 planetary_moons, 1 planet

## Files

| File | What |
|------|------|
| `packages/web/src/lib/api.ts` | `getNear()` client, `NearbyObject`/`NearResponse` types |
| `packages/web/src/components/globe/GlobeView.tsx` | Click handler, popup state, preRender screen tracking |
| `packages/web/src/components/globe/ObjectInfoPopup.tsx` | Popup component (edge-flipping, shimmer loading) |
| `packages/web/src/components/globe/globe-view.css` | Popup styles |
| `docs/.../reference/api/celestial.mdx` | `/sky/near` endpoint now documented (commit `452a557`) |

## Feedback for v0.13.0 planning

1. **`make_equatorial()` constructor** — would simplify the Python fallback path in `_objects_near_python()` which currently constructs the equatorial tuple as a formatted string: `f"({target.ra_hours},{target.dec_deg},0)"`. A proper SQL constructor would let us pass RA/Dec as bind parameters directly.

2. **Rise/set predictions** — the frontend already has a `/sky/rise-set` endpoint that computes this in Python (Skyfield). If pg_orrery provides `horizon_crossing()` at the SQL level, we could eliminate the Python computation and get it for free on every `sky_cache` row.

3. **Nutation correction** — 9 arcsec matters for the KNN results. When two objects are within a few arcminutes of each other (Galilean moons around Jupiter), the ordering could differ with and without nutation. Not blocking, but worth noting for KNN accuracy.

---

**Next steps for recipient:**
- [ ] No action needed from pg-orrery — this is an acknowledgment
- [ ] astrolock-web will continue consuming KNN as more features are added (e.g., trajectory prediction overlay)