npm - @aeroswarm/client - Versions diffs - 0.1.15 → 0.1.17 - Mend

@aeroswarm/client 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +631 -617
package/dist/{index-CeayQnTp.d.ts → index-DH3DH1Nj.d.ts} +9 -0
package/dist/index.d.ts +1 -1
package/dist/index.js +7 -1
package/dist/index.js.map +1 -1
package/dist/react/index.d.ts +1 -1
package/dist/react/index.js +7 -1
package/dist/react/index.js.map +1 -1
package/dist/sdk/index.d.ts +1 -1
package/dist/sdk/index.js +7 -1
package/dist/sdk/index.js.map +1 -1
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -1,617 +1,631 @@
-# @aeroswarm/client
-TypeScript SDK and React bindings for consuming AeroSwarm data: live track streaming over WebSocket, REST/tRPC/GraphQL APIs, alerts, replay, and map-ready track state management.
-This is the **only** package frontends should use — surveillance decoding, Kafka, and Redis all stay server-side; the SDK consumes the normalized event stream.
-## Installation
-```bash
-pnpm add @aeroswarm/client
-```
-## Entry points
-| Import | Contents |
-|--------|----------|
-| `@aeroswarm/client` | Everything from `/sdk` + shared types/utils |
-| `@aeroswarm/client/sdk` | `AeroSwarm` class, `AeroWsClient`, `TrackCache` |
-| `@aeroswarm/client/react` | React hooks, `AeroSwarmProvider`, Zustand track store |
-## SDK usage (framework-agnostic)
-```ts
-import { AeroSwarm } from "@aeroswarm/client/sdk";
-const client = new AeroSwarm({
-  endpoint: "http://192.168.2.231:8070", // REST/tRPC/GraphQL base
-  token: "<viewer-or-source-token>",
-  // wsEndpoint?: string          — defaults to endpoint with ws:// scheme
-  // encoding?: "json" | "msgpack"
-  // reconnect?: boolean, maxReconnectDelay?: number (ms, default 30 000)
-  // staleAfterMs?, removeAfterMs? — client-side track lifecycle overrides
-  // onTokenExpired?: () => Promise<string> — refresh hook
-});
-const unsubscribe = client.tracks.subscribe(
-  {
-    bbox: [94, -11, 141, 6.5],   // lonMin, latMin, lonMax, latMax
-    source: "fused",             // "fused" | "normalized"
-    minConfidence: 0.5,
-    maxTracks: 500,              // server-side top-N
-    maxUpdateHz: 5,              // per-track update cap — see performance notes
-    mode: "delta",               // "delta" (updates) | "full" (periodic snapshots)
-    includeAlerts: false,
-  },
-  {
-    onSnapshot:    (tracks) => console.log("initial state", tracks.length),
-    onTrackUpdate: (track)  => console.log(track.trackId, track.lat, track.lon),
-    onTrackRemoved:(ev)     => console.log("removed", ev.trackId),
-    onStatusChange:(status) => console.log("ws:", status),
-    onError:       (err)    => console.error(err.code, err.message),
-  },
-);
-// later
-unsubscribe();
-client.disconnect();
-```
-### `AeroSwarm` surface
-| Member | Description |
-|--------|-------------|
-| `tracks.subscribe(opts, callbacks)` | Live WS stream (`/ws/tracks/live`); returns unsubscribe fn. Auto-reconnects with backoff; server sends a fresh authoritative snapshot on reconnect |
-| `tracks.stream(opts)` | Same live stream as an `AsyncIterable<LabeledTrack>` (`for await`) |
-| `tracks.updateFilter(opts)` | Change bbox / minConfidence / maxUpdateHz / maxTracks without reconnecting |
-| `tracks.reconnect()` | Force an immediate reconnect (skips backoff, re-subscribes with the last options, resumes after `disconnect()`); `false` if never subscribed. Also `AeroSwarm.reconnect()` and `useAeroTracks().reconnect` |
-| `tracks.snapshot(input?)` | One-shot current state via tRPC (`airportId`, `bbox`, `source`, `minConfidence`, `limit`, `offset`) |
-| `tracks.history(input)` | Persisted position history for one track (`trackId`, `airportId?`, `limit?`) — federated airports are served by their own backend |
-| `airports.*` | Airport registry: `list/create/update/delete` + `surface`/`setSurface` (runway/taxiway/apron GeoJSON for the map) |
-| `sources.*` | Register/list (optionally by `airportId`)/delete data sources (returns per-source auth tokens) |
-| `alerts.*` | Alert history + live alert subscription |
-| `rules.*` | Detection-rule CRUD — **global or per-airport** (see example below) |
-| `routes.*` | Route conformance: pre-defined ground routes + live track clearances (deviation alerts) |
-| `analytics.movements()` | Takeoffs/landings per hour + peak hour, per airport |
-| `webhooks.*` | Webhook CRUD |
-| `replay.days(input?)` | Data-availability calendar — which days have recorded tracks (see example below) |
-| `replay.range/seek/window` | Historical replay metadata: range summary, point-in-time seek, time-bucketed window for scrubbing |
-| `replay.stream(opts, cb)` | **Server-paced WS playback** — historical tracks streamed like live (see example below) |
-| `system.*` | `stats`, `infraHealth`, `getConfig`/`setConfig`, `clearTable`, `ingestHistory` |
-| `trpc` / `rest` / `graphql` | Direct typed API clients for anything not wrapped above — **untyped** (`createTRPCProxyClient<any>`), so prefer the wrappers above; fall back to `client.trpc.<router>.<procedure>.query/mutate(...)` only for endpoints not yet wrapped |
-| `cache` | A `TrackCache` instance (see below) |
-| `getStatus()` / `getLastUpdateAt()` / `getError()` / `getSourceStatus()` | Connection introspection |
-| `disconnect()` | Tear down the WS connection |
-### Label category / color
-Every track from `tracks.subscribe` / `tracks.stream` callbacks, the cache and `useAeroTracks` carries `labelCategory` and `labelColor`, derived after merging deltas so a delta without `flightPlan` never changes the color:
-| Category | Color | When |
-|---|---|---|
-| `ARRIVAL` | `#FACC15` yellow | `flightPlan.phase === "ARRIVAL"` |
-| `DEPARTURE` | `#22C55E` green | `flightPlan.phase === "DEPARTURE"` |
-| `GROUND_VEHICLE` | `#3B82F6` blue | `targetType === "vehicle"` |
-| `LOST` | `#FFFFFF` white | `status === "lost"` (takes priority) |
-| `UNKNOWN` | `#FFFFFF` white | no flight plan / overflight |
-Also exported: `LABEL_COLORS`, `getLabelCategory(track)`, `withLabel(track)`.
-### Response data (live WS)
-The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client validates them, drops out-of-order `seq`, and re-requests a snapshot after a gap. You never see envelopes — you get typed callbacks:
-| Callback | Payload | Notes |
-|---|---|---|
-| `onSnapshot` | `LabeledTrack[]` | Full authoritative state; sent on subscribe and on every reconnect |
-| `onTrackUpdate` | `LabeledTrack` | Delta **merged with the previous state** of that track (fields the delta omits keep their last value). Also fires when `status` becomes `"lost"` (the track is then evicted from `cache`) |
-| `onTrackRemoved` | `{ trackId, reason }` | Server dropped the track |
-| `onSourceStatus` | `{ sourceId, status }` | `healthy` \| `degraded` \| `offline` |
-| `onStatusChange` | `AeroConnectionStatus` | `idle` \| `connecting` \| `connected` \| `reconnecting` \| `degraded` \| `offline` |
-| `onDegraded` | `reason: string` | e.g. `heartbeat_timeout` |
-| `onError` | `{ code, message, recoverable }` | |
-`LabeledTrack` = `CurrentTrack` + label fields:
-```jsonc
-{
-  "trackId": "fused-4b1a2c",
-  "source": "FUSED",              // ADSB | ASTERIX_CAT010/011/020/021/048/062 | FUSED
-  "icao24": "8a0123",             // string | null
-  "callsign": "GIA123",           // string | null
-  "squawk": "1200",               // string | null
-  "targetType": "aircraft",       // optional: aircraft | vehicle | unknown
-  "vehicleFleet": 3,              // optional, only for vehicles
-  "airportId": "WARR",            // optional ICAO scope
-  "dataSource": { "sac": 32, "sic": 136 },  // optional: the sensor behind the position shown (ASTERIX feeds)
-  "lat": -7.3797, "lon": 112.7868,// number | null
-  "altitudeFt": 0,
-  "groundSpeedKt": 12,
-  "headingDeg": 90,
-  "verticalRateFpm": 0,
-  "confidence": 0.98,             // 0..1
-  "lastSeenAt": 1761640000000,    // epoch ms
-  "status": "active",             // active | stale | lost
-  "flightPlan": {                 // optional: only when correlated with an AFTN plan
-    "id": "GIA123|WARR|WIII|20261028",
-    "adep": "WARR", "ades": "WIII",
-    "status": "filed",            // filed | delayed | departed | arrived | cancelled
-    "phase": "DEPARTURE"          // ARRIVAL | DEPARTURE | OVERFLIGHT | UNKNOWN (relative to airportId)
-  },
-  // added by the client:
-  "labelCategory": "DEPARTURE",   // ARRIVAL | DEPARTURE | GROUND_VEHICLE | LOST | UNKNOWN
-  "labelColor": "#22C55E"
-}
-```
-`status` and `labelColor` change only when the track's category or status actually changes — position-only deltas leave them untouched, so a label painted from `labelColor` does not flicker.
-`dataSource` is the ASTERIX System Area / System Identification Code (SAC/SIC) of the sensor that reported the position shown (for a merged track, the sensor that is currently preferred). `formatDataSource(track)` gives the display string `"ADSB 32/136"` (`sourceLabel(track.source)` gives just the kind: `ADSB`, `SURFACE` for CAT010/011, `MLAT`, `RADAR`, `SYSTEM`, `FUSED`); without a SAC/SIC it is the kind alone.
-## Per-domain usage examples
-Everything below assumes `const client = new AeroSwarm({ endpoint, token })`.
-### Airports (multi-airport tenancy)
-```ts
-const { airports } = await client.airports.list();
-// [{ id: "WARR", name: "Juanda International Airport", city, lat, lon, bbox, timezone }, …]
-await client.airports.create({
-  id: "WARR", name: "Juanda International Airport",
-  lat: -7.3798, lon: 112.7869, bbox: [112.7, -7.42, 112.86, -7.33],
-});
-await client.airports.update({ id: "WARR", city: "Surabaya" });
-await client.airports.delete({ id: "WARR" });
-// Runway/taxiway/apron GeoJSON for the map's surface layer
-const { surface } = await client.airports.surface({ id: "WARR" });
-```
-Most other calls accept an `airportId` (ICAO code) to scope to one airport; omitting it means "all airports".
-### Rules — global vs per-airport
-Rules with no `airportId` are **global**: the safety engine evaluates them against tracks from every airport. With an `airportId` they only apply to tracks stamped with that airport.
-```ts
-// GLOBAL geofence — applies everywhere
-const { ruleId } = await client.rules.create({
-  name: "Restricted area — national",
-  type: "geofence",                       // geofence | altitude | speed | squawk | custom
-  severity: "high",                       // low | medium | high | critical
-  conditions: { kind: "restricted", polygon: [[lon, lat], …] },
-  actions: [],
-});
-// Airport-scoped geofence — WARR tracks only
-await client.rules.create({
-  name: "South Apron",
-  type: "geofence",
-  severity: "medium",
-  conditions: { kind: "apron", polygon: [[lon, lat], …] },
-  actions: [],
-  airportId: "WARR",
-});
-await client.rules.list();                        // every rule
-await client.rules.list({ airportId: "WARR" });   // one airport's rules
-await client.rules.update({ id: ruleId, enabled: false });
-await client.rules.delete({ id: ruleId });
-```
-Geofence `conditions`: `kind` (`runway | taxiway | apron | restricted | custom`), `polygon` (`[lon, lat]` ring), optional `maxSpeedKt`, `appliesTo` (`all | aircraft | vehicle`), `runwayId` (ties a runway zone to active-runway suppression). Note: the safety engine currently evaluates `geofence` rules (plus built-in emergency-squawk/STCA/deviation); other types are stored but not evaluated.
-### Routes — assigned-route conformance (deviation alerts)
-Routes are polylines of `[lat, lon]` vertices per airport (seeded from real OSM taxiways for WARR/WAHS/WAHI). Assign one to a live track and the safety engine starts emitting `deviation` alerts whenever the track strays beyond `maxDeviationM`; taxiway/apron incursion alerts are suppressed while the track conforms.
-```ts
-// Route definitions
-const { routes } = await client.routes.list({ airportId: "WARR" });
-const { id } = await client.routes.create({
-  airportId: "WARR",
-  name: "Stand A1 → RWY 10",
-  kind: "taxi",                            // taxi | departure | arrival
-  points: [[-7.3822, 112.7794], [-7.3820, 112.7900], …],  // [lat, lon]
-  maxDeviationM: 50,
-});
-await client.routes.delete({ id });
-// Clearances (live track → route). Stored in Redis; the safety engine
-// refreshes them every 5 s.
-await client.routes.assign({ trackId: "trk_abc", routeId: routes[0].routeId });
-await client.routes.unassign({ trackId: "trk_abc" });
-const { assignments } = await client.routes.assignments();
-// [{ trackId, routeId, assignedAt }, …]
-```
-The resulting `deviation` alerts arrive through the normal alert stream with `details: { routeId, route, deviationM, maxDeviationM, routeProgress }`.
-### Alerts
-```ts
-// History (tRPC)
-const { alerts } = await client.alerts.list({ severity: "high", limit: 50 });
-// Live subscription (WS)
-const stop = client.alerts.subscribe((alert) => {
-  // { alertId, type, severity, trackId, triggeredAt, reason, details }
-  // type: emergency | area_penetration | runway_incursion |
-  //       taxiway_incursion | deviation | stca | …
-  showToast(alert);
-});
-stop();
-```
-### Movement analytics (takeoffs/landings per hour)
-```ts
-const stats = await client.analytics.movements({ airportId: "WARR", day: "2026-07-14" });
-// {
-//   day: "2026-07-14",
-//   hours:  [{ hour: "2026-07-14T07:00:00.000Z", takeoffs: 21, landings: 17 }, …],
-//   totals: { takeoffs: 132, landings: 128 },
-//   peak:   { hour: "2026-07-14T07:00:00.000Z", count: 38 },   // jam puncak + jumlah
-// }
-```
-Omit `airportId` for all airports; omit `day` for today (UTC). Movements are detected server-side by the shared `MovementDetector` (`@aeroswarm/core`) from fused-track transitions.
-### Replay — server-paced WS playback
-The server streams historical tracks **at the requested speed** using the same envelopes as the live stream, so any renderer that handles live data can render a replay unchanged. Drive your playhead from `onProgress` (the server's clock) — never a local timer.
-```ts
-const handle = await client.replay.stream(
-  {
-    from: "2026-07-14T02:00:00Z",
-    to:   "2026-07-14T03:00:00Z",
-    speed: 2,                    // 2× real time (server-paced, drift-free)
-    airportId: "WARR",           // federated airport → its own backend serves this
-    // sessionId: "…"            // resume a previous session (kept 1 h in Redis)
-  },
-  {
-    onSnapshot:     (tracks) => seedMap(tracks),        // state AT `from`
-    onTrackUpdate:  (t)      => upsertMarker(t),
-    onTrackRemoved: (ev)     => removeMarker(ev.trackId),
-    onProgress:     (p)      => setPlayhead(p.at, p.pct),  // ISO time + 0-100 %
-    onDone:         ()       => setFinished(),
-    onError:        (err)    => showError(err.message),
-  },
-);
-// `stream()` is async — it first resolves whether `airportId` is a
-// federated airport (see "Federated history" below), which needs a lookup.
-handle.pause();
-handle.resume();
-handle.seek(new Date("2026-07-14T02:45:00Z"));  // server restarts the paced stream there
-handle.stop();                                   // ends the session, closes the socket
-handle.sessionId;                                // save to resume after a page reload
-```
-For range pickers, the metadata endpoints are still available:
-```ts
-// Which days actually HAVE data (populate/validate the date picker)
-const { days } = await client.replay.days({ airportId: "WARR", lookbackDays: 60 });
-// [{ day: "2026-07-14", eventCount: 51230, trackCount: 42,
-//    firstAt: "2026-07-14T01:58:03Z", lastAt: "2026-07-14T09:12:44Z" }, …]
-// A date absent from the list has no recorded data — don't offer it.
-const range = await client.replay.range({ from, to });
-// { earliest, latest, eventCount, trackCount }
-```
-Not using the SDK? The wire protocol is plain JSON on `/ws/tracks/replay` — documented in `docs/sdk/websocket.md` (§ Replay Streaming). `AeroReplayClient` is also exported standalone.
-### Federated history
-An airport can serve its **own** replay/history instead of AeroSwarm's — its own backend, its
-own database, reached directly (see `docs/development/federation/`). `replay.stream`,
-`replay.days`, `replay.range`, `tracks.history`, and `alerts.list` all resolve this
-automatically, in priority order:
-1. **Explicit override** — pass `endpoint` and the registry is skipped entirely:
-   ```ts
-   await client.replay.days({ endpoint: "http://192.168.2.225:4000/aero" });
-   ```
-2. **Registry** — if the airport's `history_endpoint` is set (`client.airports.list()` /
-   dashboard's Airports tab), calls for that `airportId` go there instead:
-   ```ts
-   const handle = await client.replay.stream({ from, to, airportId: "WARR" }, callbacks);
-   // WARR has history_endpoint set → connects to that backend's WS replay, transparently
-   ```
-3. **AeroSwarm itself** — the default, unchanged behavior, for any airport with no endpoint set.
-A lookup failure (e.g. `airports.list()` errors) always falls back to AeroSwarm's own endpoint
-rather than breaking replay — federation degrades safely.
-`replay.window` and `replay.seek` are **not** part of the federation contract — they throw for a
-federated airport; use `replay.stream` (which covers the same "jump to a point in time" need via
-`seek()` on the returned handle) instead.
-Building the receiving side (an airport's own backend)? See
-[`@aeroswarm/replay-server`](../../server/replay-server/README.md) — mounts this exact protocol
-on top of your own database with a few lines of code.
-**Multi-airport.** Every replay call accepts `airportId` as *optional*. For a **federated**
-airport (one with a `historyEndpoint` — see the next section) it selects which airport backend
-to connect to; always pass it for those. Against AeroSwarm's own endpoint (dev/single-node
-mode) it's a row filter on the local database — omitting it returns all local rows. There is no
-cross-backend "all airports" merged replay: each federated airport's history lives behind its
-own backend, replayed one airport at a time.
-### Sources & webhooks
-A **source** is a registered sensor/feed (radar, ADS-B, synthetic, …) identified by a bearer
-token (`sourceToken`). Tag it with `airportId` at creation and that token **carries its airport
-with it** from then on — anything that authenticates with it (WS `/ws/tracks/live`,
-`/ws/tracks/replay`, tRPC, REST) is automatically scoped to that airport, with no need to keep
-passing `airportId` on every call:
-```ts
-const { sources } = await client.sources.list();               // all sources
-const { sources: warrSources } = await client.sources.list({ airportId: "WARR" });
-const created = await client.sources.create({
-  name: "WARR ASTERIX feed",
-  sourceType: "ASTERIX_CAT021",
-  airportId: "WARR",                        // ← ties this token to WARR
-});
-// { ok: true, data: { sourceId: "src_...", sourceToken: "srctk_...", airportId: "WARR" } }
-// Later, a client connecting with that token doesn't need to pass airportId at all:
-const scoped = new AeroSwarm({ endpoint, wsEndpoint, token: created.data.sourceToken });
-await scoped.tracks.stream({}); // already scoped to WARR — the token carries it
-await client.sources.health("src_abc");
-// Reassign (or clear, with null) a source's airport after the fact — takes
-// effect immediately, no need to wait out the token cache TTL.
-await client.sources.update({ id: "src_abc", airportId: "CGK" });
-await client.sources.update({ id: "src_abc", airportId: null });
-await client.webhooks.create({ url: "https://ops.example/hook", events: ["alert"] });
-const hooks = await client.webhooks.list();
-await client.webhooks.delete({ id: hooks[0].id });
-```
-`airportId` is required on `sources.create` — a source is a sensor physically at one airport, so
-a token that isn't tied to any airport is more footgun than feature. (Sources created before this
-was enforced may still have `airportId: null`; `sources.update` can backfill one.) For access
-that spans multiple airports, use the viewer/dashboard token instead — it's never auto-scoped
-this way, regardless of any source's configuration, and always sees whatever `airportId` (or lack
-thereof) it explicitly asks for.
-### `TrackCache`
-In-memory `Map`-backed track store with a typed emitter — the primitive the React store builds on:
-`applyUpdate(track)`, `applyRemoved(ev)`, `applySnapshot(tracks)` (authoritative — replaces contents), `getAll()`, `get(id)`, `getRenderable()` (only tracks with valid lat/lon), `size`, `clear()`, plus `update`/`removed`/`snapshot` events.
-### `AeroWsClient`
-Low-level WebSocket client (subscribe payloads, sequence tracking, heartbeats, reconnect/backoff, JSON + msgpack). Use `AeroSwarm.tracks.subscribe` unless you're building your own state layer.
-## React usage
-```tsx
-import { AeroSwarmProvider, useAeroTracks } from "@aeroswarm/client/react";
-function App() {
-  return (
-    <AeroSwarmProvider endpoint="http://…:8070" token={token}>
-      <LiveMap />
-    </AeroSwarmProvider>
-  );
-}
-function LiveMap() {
-  const { tracks, status, error, lastUpdateAt } = useAeroTracks({
-    bbox: [94, -11, 141, 6.5],
-    minConfidence: 0.5,
-    maxUpdateHz: 5,
-  });
-  if (status !== "connected") return <p>{status}…</p>;
-  return <ul>{tracks.map((t) => <li key={t.trackId}>{t.callsign ?? t.icao24}</li>)}</ul>;
-}
-```
-### Hooks (`@aeroswarm/client/react`)
-| Hook | Purpose |
-|------|---------|
-| `useAeroTracks(opts?)` (alias `useTracks`) | Live track list + connection state for a subscription |
-| `useAeroTrack(trackId)` | Single track by id |
-| `useAeroSnapshot(opts?)` | One-shot snapshot fetch |
-| `useAeroStatus()` | Connection status only |
-| `useTrackCount()` | Track count only (cheap selector) |
-| `useSourceHealth(sourceId?)` | Source health/status |
-| `useAlerts(opts?)` | Live alerts |
-| `useRules(opts?)` / `useRule(id, opts?)` | Alert rules |
-| `useWebhooks(opts?)` | Webhooks |
-| `useReplayStatus(sessionId, opts?)` / `useReplayStop()` | Replay session control |
-| `useLineage(eventId, opts?)` / `useLineageTrace(trackId, opts?)` | Event lineage/provenance |
-| `useTrackHistory(options)` | **Map animation engine** — see below |
-| `useAeroSwarmContext()` | Raw client from the provider |
-### `useTrackStore` — Zustand store
-Shared live-track state; feed it from your subscription callbacks and read it imperatively (maps) or via selectors (React):
-| Member | Notes |
-|--------|-------|
-| `tracks: Map<string, LabeledTrack>` | Current state (each track carries `labelCategory` / `labelColor`) |
-| `applyUpdate(track)` | One store write per event — prefer `applyBatch` at high rates |
-| `applyBatch(updates, removedIds)` | **One Map clone per batch** — use this from buffered/throttled feeds |
-| `applyRemoved({trackId})` / `applySnapshot(tracks)` | Snapshot is authoritative (replaces state — ghosts from a dropped connection are cleared) |
-| `pruneStale(maxAgeMs)` | Remove tracks not updated within `maxAgeMs`; returns removed ids. **Call on an interval** (e.g. 60 s sweep every 10 s) — track ids churn on feed/replay restarts and abandoned ids never get a `removed` event, so without pruning they linger as ghost icons |
-| `setStatus` / `setSourceStatus` / `setError` / `setDegraded` / `clear` | Connection metadata |
-| Selectors | `selectAllTracks`, `selectRenderableTracks`, `selectTrack(id)`, `selectTrackCount`, `selectStatus`, `selectIsDegraded`, `selectLastUpdateAt`, `selectError` |
-### REST errors: `AeroApiError`
-Every failed REST call (`client.rest.*`, federated `tracks.history` and the like) throws an `AeroApiError` that keeps what the server said, instead of just `GET /x → 500`:
-```ts
-try { await client.tracks.history({ trackId, airportId: "WARR" }); }
-catch (e) {
-  if (e instanceof AeroApiError) {
-    e.status;       // 403
-    e.code;         // "FORBIDDEN" — stable, for switch; a newer server may send a code you do not know
-    e.recoverable;  // retrying later may help (rate limit, server busy)
-    e.message;      // "Federated request /tracks/t1/history → 403: not your airport"
-    e.details;      // whatever the server attached
-  }
-}
-```
-Servers answer either in the standard format (`{ ok, data, meta }` / `{ ok: false, error: { code, message, recoverable } }`, see `@aeroswarm/core/api`) or in the older shape (bare data, `{ ok: false, error: "text" }`); both are read. Federated calls send `x-aero-envelope: 1` to get the standard format. `parseApiResponse(res)` and `readApiBody(res)` are exported for your own `fetch` calls.
-### `tracks.trail` / `createTrailPoller` / `useTrackTrail` — the path an aircraft has flown
-The airport's backend builds the trail (memory first, stored history as a fallback), so the client computes nothing: it gets a GeoJSON `FeatureCollection` with one `LineString` (`[lon, lat, altitude m]`) and a `Point` per time mark, each with `properties.label` already written in the time zone you ask for.
-```ts
-const { trail } = await client.tracks.trail({
-  trackId,
-  endpoint: "https://asmgcs.example/aero",   // the airport backend (or an airportId with a historyEndpoint)
-  tz: "Asia/Jakarta",                        // labels such as "01-11-26 11:16"; default UTC
-});
-// whole flight by default. fromMs/toMs: a period. stepM: coarser line. limit: at most n points. labelEveryMs: marks (default 2 min)
-```
-Keep it current while an aircraft is selected: the first request is the whole trail, after that only what is new is fetched (`sinceMs`), so polling every few seconds costs a few hundred bytes.
-```ts
-const poller = createTrailPoller(
-  (sinceMs) => client.tracks.trail({ trackId, endpoint, tz: "Asia/Jakarta", sinceMs }),
-  { pollMs: 5000, onUpdate: (trail) => draw(trail) },   // draw the line, and each mark's properties.label
-);
-poller.stop();                                          // when it is deselected
-```
-React: `const { trail, loading, error } = useTrackTrail(selectedTrackId, { endpoint, tz: "Asia/Jakarta" })` (pass `null` while nothing is selected). A fixed period (`toMs`) is fetched once. A trail already shown stays when a request fails; polling stops for good when the server says the track is unknown (`NOT_FOUND`). `mergeTrail(prev, delta)` and `trailEnd(trail)` are exported if you manage the polling yourself. To end the line at the icon, draw one more segment from the trail's last point to `createTrackMotion().sample(trackId)`.
-### `useTrackMotion` / `createTrackMotion` — smooth live tracks
-Feeds update a track once a second (MLAT, ADS-B) or once per antenna sweep (radar, ~7.5 s). Drawn as they arrive, icons jump. `createTrackMotion` (no React needed) shows where the aircraft *probably is right now* and eases corrections in, like a flight tracker:
-```ts
-import { createTrackMotion } from "@aeroswarm/client";
-const motion = createTrackMotion();                     // all options optional
-client.tracks.subscribe(opts, {
-  onSnapshot: (tracks, meta) => tracks.forEach((t) => motion.update(t, meta)),
-  onTrackUpdate: (t, meta) => motion.update(t, meta),   // meta.serverTime keeps the clocks aligned
-  onTrackRemoved: ({ trackId }) => motion.remove(trackId),
-});
-const stop = motion.start(({ changed }) => {            // ~30 frames/s, only tracks that moved
-  for (const [id, s] of changed) layer.put(id, s.lat, s.lon, s.headingDeg);
-});
-```
-React: `const motion = useTrackMotion({ onFrame })`, then call `motion.update(...)` from the subscription. Nothing here renders React.
-What it does:
-| | |
-|---|---|
-| **Dead reckoning** | From the last fix, speed and heading carry the position forward, up to `maxExtrapolateMs` (20 s in the air, 8 s on the surface). `lost` tracks freeze. |
-| **Eased corrections** | A new fix does not snap the icon. The gap between where it was shown and where the fix says it should be becomes an offset that fades out (smoothstep over `blendMs`, 1.5 s). The icon keeps moving at its own speed meanwhile, so there is no stop-and-go at every update. A correction larger than `snapDistanceM` (5 km) is a glitch and jumps. |
-| **Heading** | Eases along the shortest arc (`headingSmoothMs`, 0.8 s); keeps the last heading when the track stops. |
-| **Server clock** | `lastSeenAt` is the server's clock. `meta.serverTime` of each message lets the engine learn the offset to the browser clock (the estimate with the least network delay wins), so a wrong browser clock does not stretch or shrink the prediction. |
-| **Cheap frames** | Tracks that stand still, or whose picture changed by less than `epsilonM` (0.5 m) / 0.5°, are not reported; no timer runs while nothing moves; `frameHz` caps the rate (30). |
-Options (`MotionOptions`): `blendMs`, `headingSmoothMs`, `maxExtrapolateMs`, `minMovingKt` (5), `snapDistanceM`, `frameHz`, `epsilonM`, `extrapolate` (`false` shows raw positions, for comparing sources), `isSurface`, `clock` (inject the replay clock to play back at another speed), `scheduler` (tests). `motion.sample(id)` gives the shown position at any time without touching frame state, e.g. to attach a trail's head to the icon.
-### `useTrackHistory` — smooth map animation (deprecated: use `useTrackMotion`)
-Maintains per-track position interpolation (tweening), dead-reckoning between updates, and bounded trail history, emitting animation frames outside React render:
-```ts
-const { processUpdate, processRemove } = useTrackHistory({
-  maxHistoryPoints: 500,   // trail length cap per track
-  minDeltaDeg: 0.0001,     // ignore sub-threshold jitter
-  maxJumpDeg: 5.0,         // discard implausible teleports
-  onFrame: ({ currentPositions, history, isMoving }) => drawMarkers(...),
-});
-```
-Update gaps longer than 30 s (lost coverage, socket offline) restart the track's trail instead of drawing a straight line across the map. Speeds beyond 1 200 kt (misdecodes, or position deltas divided by a compressed replay clock) are rejected and never drive dead reckoning.
-## Frontend recipes
-### Live map, end to end
-The proven wiring (this is what the reference dashboard does):
-```tsx
-// 1. Subscription → store, batched (never setState per message)
-const pending = new Map<string, CurrentTrack>();
-const removed = new Set<string>();
-client.tracks.subscribe(opts, {
-  onSnapshot:     (ts) => useTrackStore.getState().applySnapshot(ts),
-  onTrackUpdate:  (t)  => { pending.set(t.trackId, t); removed.delete(t.trackId); },
-  onTrackRemoved: (ev) => { pending.delete(ev.trackId); removed.add(ev.trackId); },
-});
-setInterval(() => {
-  useTrackStore.getState().applyBatch([...pending.values()], [...removed]);
-  pending.clear(); removed.clear();
-}, 250);
-// 2. Ghost cleanup — ids churn on feed/replay restarts
-setInterval(() => { useTrackStore.getState().pruneStale(60_000); }, 10_000);
-// 3. Store → animation engine → map markers (imperative, no React re-render)
-const { processUpdate, processRemove } = useTrackHistory({ onFrame: drawMarkers });
-useTrackStore.subscribe((state, prev) => {
-  for (const [id, t] of state.tracks) if (prev.tracks.get(id) !== t) processUpdate(t);
-  for (const id of prev.tracks.keys()) if (!state.tracks.has(id)) processRemove(id);
-});
-```
-### Replay in the same map
-Feed `replay.stream` callbacks into the **same** store/animation path and pause the live subscription while a session is active — replay then looks exactly like live. Batch `onTrackUpdate` into ~250 ms flushes the same way.
-### Assigned-route overlay
-```ts
-const { routes } = await client.routes.list({ airportId });
-const { assignments } = await client.routes.assignments();
-const route = routes.find(r => r.routeId === assignments.find(a => a.trackId === selectedId)?.routeId);
-// draw route.points ([lat, lon][]) as a dashed LineString: points.map(([lat, lon]) => [lon, lat])
-```
-## Performance notes (important for dashboards)
-- **Don't call a React `setState` per WS message.** At realistic rates (hundreds of tracks × several Hz) that renders your page thousands of times per second. Buffer updates and flush on an interval (~250 ms to the store for the map, ~1 s to React state for panels), using `applyBatch`.
-- **Request only the rate you need** — `maxUpdateHz: 5` with client-side interpolation looks identical to 20 Hz on a map and cuts WS traffic 4×.
-- Drive map markers **imperatively** from `useTrackStore.subscribe(...)` + `useTrackHistory`, not through React props.
-## Wire encoding
-`json` (default) or `msgpack` (binary, lower bandwidth) — set once in `AeroSwarmOptions.encoding` or per-subscription.
-## Environment variables (Vite frontends)
-| Variable | Description |
-|----------|-------------|
-| `VITE_AEROSWARM_API_URL` | REST/tRPC/GraphQL base URL |
-| `VITE_AEROSWARM_WS_URL` | WebSocket base URL |
-| `VITE_AEROSWARM_API_KEY` | Viewer token |
-These are baked into the bundle at build time (Vite), not read at runtime.
-## Building & testing
-```bash
-pnpm run build     # tsup → dist/ (index + /sdk + /react)
-pnpm run typecheck
-pnpm test
-```
+# @aeroswarm/client
+TypeScript SDK and React bindings for consuming AeroSwarm data: live track streaming over WebSocket, REST/tRPC/GraphQL APIs, alerts, replay, and map-ready track state management.
+This is the **only** package frontends should use — surveillance decoding, Kafka, and Redis all stay server-side; the SDK consumes the normalized event stream.
+## Installation
+```bash
+pnpm add @aeroswarm/client
+```
+## Entry points
+| Import | Contents |
+|--------|----------|
+| `@aeroswarm/client` | Everything from `/sdk` + shared types/utils |
+| `@aeroswarm/client/sdk` | `AeroSwarm` class, `AeroWsClient`, `TrackCache` |
+| `@aeroswarm/client/react` | React hooks, `AeroSwarmProvider`, Zustand track store |
+## SDK usage (framework-agnostic)
+```ts
+import { AeroSwarm } from "@aeroswarm/client/sdk";
+const client = new AeroSwarm({
+  endpoint: "http://192.168.2.231:8070", // REST/tRPC/GraphQL base
+  token: "<viewer-or-source-token>",
+  // wsEndpoint?: string          — defaults to endpoint with ws:// scheme
+  // encoding?: "json" | "msgpack"
+  // reconnect?: boolean, maxReconnectDelay?: number (ms, default 30 000)
+  // staleAfterMs?, removeAfterMs? — client-side track lifecycle overrides
+  // onTokenExpired?: () => Promise<string> — refresh hook
+});
+const unsubscribe = client.tracks.subscribe(
+  {
+    bbox: [94, -11, 141, 6.5],   // lonMin, latMin, lonMax, latMax
+    source: "fused",             // "fused" | "normalized"
+    minConfidence: 0.5,
+    maxTracks: 500,              // server-side top-N
+    maxUpdateHz: 5,              // per-track update cap — see performance notes
+    mode: "delta",               // "delta" (updates) | "full" (periodic snapshots)
+    includeAlerts: false,
+  },
+  {
+    onSnapshot:    (tracks) => console.log("initial state", tracks.length),
+    onTrackUpdate: (track)  => console.log(track.trackId, track.lat, track.lon),
+    onTrackRemoved:(ev)     => console.log("removed", ev.trackId),
+    onStatusChange:(status) => console.log("ws:", status),
+    onError:       (err)    => console.error(err.code, err.message),
+  },
+);
+// later
+unsubscribe();
+client.disconnect();
+```
+### `AeroSwarm` surface
+| Member | Description |
+|--------|-------------|
+| `tracks.subscribe(opts, callbacks)` | Live WS stream (`/ws/tracks/live`); returns unsubscribe fn. Auto-reconnects with backoff; server sends a fresh authoritative snapshot on reconnect |
+| `tracks.stream(opts)` | Same live stream as an `AsyncIterable<LabeledTrack>` (`for await`) |
+| `tracks.updateFilter(opts)` | Change bbox / minConfidence / maxUpdateHz / maxTracks without reconnecting |
+| `tracks.reconnect()` | Force an immediate reconnect (skips backoff, re-subscribes with the last options, resumes after `disconnect()`); `false` if never subscribed. Also `AeroSwarm.reconnect()` and `useAeroTracks().reconnect` |
+| `tracks.snapshot(input?)` | One-shot current state via tRPC (`airportId`, `bbox`, `source`, `minConfidence`, `limit`, `offset`) |
+| `tracks.history(input)` | Persisted position history for one track (`trackId`, `airportId?`, `limit?`) — federated airports are served by their own backend |
+| `airports.*` | Airport registry: `list/create/update/delete` + `surface`/`setSurface` (runway/taxiway/apron GeoJSON for the map) |
+| `sources.*` | Register/list (optionally by `airportId`)/delete data sources (returns per-source auth tokens) |
+| `alerts.*` | Alert history + live alert subscription |
+| `rules.*` | Detection-rule CRUD — **global or per-airport** (see example below) |
+| `routes.*` | Route conformance: pre-defined ground routes + live track clearances (deviation alerts) |
+| `analytics.movements()` | Takeoffs/landings per hour + peak hour, per airport |
+| `webhooks.*` | Webhook CRUD |
+| `replay.days(input?)` | Data-availability calendar — which days have recorded tracks (see example below) |
+| `replay.range/seek/window` | Historical replay metadata: range summary, point-in-time seek, time-bucketed window for scrubbing |
+| `replay.stream(opts, cb)` | **Server-paced WS playback** — historical tracks streamed like live (see example below) |
+| `system.*` | `stats`, `infraHealth`, `getConfig`/`setConfig`, `clearTable`, `ingestHistory` |
+| `trpc` / `rest` / `graphql` | Direct typed API clients for anything not wrapped above — **untyped** (`createTRPCProxyClient<any>`), so prefer the wrappers above; fall back to `client.trpc.<router>.<procedure>.query/mutate(...)` only for endpoints not yet wrapped |
+| `cache` | A `TrackCache` instance (see below) |
+| `getStatus()` / `getLastUpdateAt()` / `getError()` / `getSourceStatus()` | Connection introspection |
+| `disconnect()` | Tear down the WS connection |
+### Label category / color
+Every track from `tracks.subscribe` / `tracks.stream` callbacks, the cache and `useAeroTracks` carries `labelCategory` and `labelColor`, derived after merging deltas so a delta without `flightPlan` never changes the color:
+| Category | Color | When |
+|---|---|---|
+| `ARRIVAL` | `#FACC15` yellow | `flightPlan.phase === "ARRIVAL"` |
+| `DEPARTURE` | `#22C55E` green | `flightPlan.phase === "DEPARTURE"` |
+| `GROUND_VEHICLE` | `#3B82F6` blue | `targetType === "vehicle"` |
+| `LOST` | `#FFFFFF` white | `status === "lost"` (takes priority) |
+| `UNKNOWN` | `#FFFFFF` white | no flight plan / overflight |
+Also exported: `LABEL_COLORS`, `getLabelCategory(track)`, `withLabel(track)`.
+### Response data (live WS)
+The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client validates them, drops out-of-order `seq`, and re-requests a snapshot after a gap. You never see envelopes — you get typed callbacks:
+| Callback | Payload | Notes |
+|---|---|---|
+| `onSnapshot` | `LabeledTrack[]` | Full authoritative state; sent on subscribe and on every reconnect |
+| `onTrackUpdate` | `LabeledTrack` | Delta **merged with the previous state** of that track (fields the delta omits keep their last value). Also fires when `status` becomes `"lost"` (the track is then evicted from `cache`) |
+| `onTrackRemoved` | `{ trackId, reason }` | Server dropped the track |
+| `onSourceStatus` | `{ sourceId, status }` | `healthy` \| `degraded` \| `offline` |
+| `onStatusChange` | `AeroConnectionStatus` | `idle` \| `connecting` \| `connected` \| `reconnecting` \| `degraded` \| `offline` |
+| `onDegraded` | `reason: string` | e.g. `heartbeat_timeout` |
+| `onError` | `{ code, message, recoverable }` | |
+`LabeledTrack` = `CurrentTrack` + label fields:
+```jsonc
+{
+  "trackId": "fused-4b1a2c",
+  "source": "FUSED",              // ADSB | ASTERIX_CAT010/011/020/021/048/062 | FUSED
+  "icao24": "8a0123",             // string | null
+  "callsign": "GIA123",           // string | null
+  "squawk": "1200",               // string | null
+  "targetType": "aircraft",       // optional: aircraft | vehicle | unknown
+  "vehicleFleet": 3,              // optional, only for vehicles
+  "airportId": "WARR",            // optional ICAO scope
+  "dataSource": { "sac": 32, "sic": 136 },  // optional: the sensor behind the position shown (ASTERIX feeds)
+  "lat": -7.3797, "lon": 112.7868,// number | null
+  "altitudeFt": 0,
+  "groundSpeedKt": 12,
+  "headingDeg": 90,
+  "verticalRateFpm": 0,
+  "confidence": 0.98,             // 0..1
+  "lastSeenAt": 1761640000000,    // epoch ms
+  "status": "active",             // active | stale | lost
+  "flightPlan": {                 // optional: only when correlated with an AFTN plan
+    "id": "GIA123|WARR|WIII|20261028",
+    "adep": "WARR", "ades": "WIII",
+    "status": "filed",            // filed | delayed | departed | arrived | cancelled
+    "phase": "DEPARTURE"          // ARRIVAL | DEPARTURE | OVERFLIGHT | UNKNOWN (relative to airportId)
+  },
+  // added by the client:
+  "labelCategory": "DEPARTURE",   // ARRIVAL | DEPARTURE | GROUND_VEHICLE | LOST | UNKNOWN
+  "labelColor": "#22C55E"
+}
+```
+`status` and `labelColor` change only when the track's category or status actually changes — position-only deltas leave them untouched, so a label painted from `labelColor` does not flicker.
+`dataSource` is the ASTERIX System Area / System Identification Code (SAC/SIC) of the sensor that reported the position shown (for a merged track, the sensor that is currently preferred). `formatDataSource(track)` gives the display string `"ADSB 32/136"` (`sourceLabel(track.source)` gives just the kind: `ADSB`, `SURFACE` for CAT010/011, `MLAT`, `RADAR`, `SYSTEM`, `FUSED`); without a SAC/SIC it is the kind alone.
+## Per-domain usage examples
+Everything below assumes `const client = new AeroSwarm({ endpoint, token })`.
+### Airports (multi-airport tenancy)
+```ts
+const { airports } = await client.airports.list();
+// [{ id: "WARR", name: "Juanda International Airport", city, lat, lon, bbox, timezone }, …]
+await client.airports.create({
+  id: "WARR", name: "Juanda International Airport",
+  lat: -7.3798, lon: 112.7869, bbox: [112.7, -7.42, 112.86, -7.33],
+});
+await client.airports.update({ id: "WARR", city: "Surabaya" });
+await client.airports.delete({ id: "WARR" });
+// Runway/taxiway/apron GeoJSON for the map's surface layer
+const { surface } = await client.airports.surface({ id: "WARR" });
+```
+Most other calls accept an `airportId` (ICAO code) to scope to one airport; omitting it means "all airports".
+### Rules — global vs per-airport
+Rules with no `airportId` are **global**: the safety engine evaluates them against tracks from every airport. With an `airportId` they only apply to tracks stamped with that airport.
+```ts
+// GLOBAL geofence — applies everywhere
+const { ruleId } = await client.rules.create({
+  name: "Restricted area — national",
+  type: "geofence",                       // geofence | altitude | speed | squawk | custom
+  severity: "high",                       // low | medium | high | critical
+  conditions: { kind: "restricted", polygon: [[lon, lat], …] },
+  actions: [],
+});
+// Airport-scoped geofence — WARR tracks only
+await client.rules.create({
+  name: "South Apron",
+  type: "geofence",
+  severity: "medium",
+  conditions: { kind: "apron", polygon: [[lon, lat], …] },
+  actions: [],
+  airportId: "WARR",
+});
+await client.rules.list();                        // every rule
+await client.rules.list({ airportId: "WARR" });   // one airport's rules
+await client.rules.update({ id: ruleId, enabled: false });
+await client.rules.delete({ id: ruleId });
+```
+Geofence `conditions`: `kind` (`runway | taxiway | apron | restricted | custom`), `polygon` (`[lon, lat]` ring), optional `maxSpeedKt`, `appliesTo` (`all | aircraft | vehicle`), `runwayId` (ties a runway zone to active-runway suppression). Note: the safety engine currently evaluates `geofence` rules (plus built-in emergency-squawk/STCA/deviation); other types are stored but not evaluated.
+### Routes — assigned-route conformance (deviation alerts)
+Routes are polylines of `[lat, lon]` vertices per airport (seeded from real OSM taxiways for WARR/WAHS/WAHI). Assign one to a live track and the safety engine starts emitting `deviation` alerts whenever the track strays beyond `maxDeviationM`; taxiway/apron incursion alerts are suppressed while the track conforms.
+```ts
+// Route definitions
+const { routes } = await client.routes.list({ airportId: "WARR" });
+const { id } = await client.routes.create({
+  airportId: "WARR",
+  name: "Stand A1 → RWY 10",
+  kind: "taxi",                            // taxi | departure | arrival
+  points: [[-7.3822, 112.7794], [-7.3820, 112.7900], …],  // [lat, lon]
+  maxDeviationM: 50,
+});
+await client.routes.delete({ id });
+// Clearances (live track → route). Stored in Redis; the safety engine
+// refreshes them every 5 s.
+await client.routes.assign({ trackId: "trk_abc", routeId: routes[0].routeId });
+await client.routes.unassign({ trackId: "trk_abc" });
+const { assignments } = await client.routes.assignments();
+// [{ trackId, routeId, assignedAt }, …]
+```
+The resulting `deviation` alerts arrive through the normal alert stream with `details: { routeId, route, deviationM, maxDeviationM, routeProgress }`.
+### Alerts
+```ts
+// History (tRPC)
+const { alerts } = await client.alerts.list({ severity: "high", limit: 50 });
+// Live subscription (WS)
+const stop = client.alerts.subscribe((alert) => {
+  // { alertId, type, severity, trackId, triggeredAt, reason, details }
+  // type: emergency | area_penetration | runway_incursion |
+  //       taxiway_incursion | deviation | stca | …
+  showToast(alert);
+});
+stop();
+```
+### Movement analytics (takeoffs/landings per hour)
+```ts
+const stats = await client.analytics.movements({ airportId: "WARR", day: "2026-07-14" });
+// {
+//   day: "2026-07-14",
+//   hours:  [{ hour: "2026-07-14T07:00:00.000Z", takeoffs: 21, landings: 17 }, …],
+//   totals: { takeoffs: 132, landings: 128 },
+//   peak:   { hour: "2026-07-14T07:00:00.000Z", count: 38 },   // jam puncak + jumlah
+// }
+```
+Omit `airportId` for all airports; omit `day` for today (UTC). Movements are detected server-side by the shared `MovementDetector` (`@aeroswarm/core`) from fused-track transitions.
+### Replay — server-paced WS playback
+The server streams historical tracks **at the requested speed** using the same envelopes as the live stream, so any renderer that handles live data can render a replay unchanged. Drive your playhead from `onProgress` (the server's clock) — never a local timer.
+```ts
+const handle = await client.replay.stream(
+  {
+    from: "2026-07-14T02:00:00Z",
+    to:   "2026-07-14T03:00:00Z",
+    speed: 2,                    // 2× real time (server-paced, drift-free)
+    airportId: "WARR",           // federated airport → its own backend serves this
+    // sessionId: "…"            // resume a previous session (kept 1 h in Redis)
+  },
+  {
+    onSnapshot:     (tracks) => seedMap(tracks),        // state AT `from`
+    onTrackUpdate:  (t)      => upsertMarker(t),
+    onTrackRemoved: (ev)     => removeMarker(ev.trackId),
+    onProgress:     (p)      => setPlayhead(p.at, p.pct),  // ISO time + 0-100 %
+    onDone:         ()       => setFinished(),
+    onError:        (err)    => showError(err.message),
+  },
+);
+// `stream()` is async — it first resolves whether `airportId` is a
+// federated airport (see "Federated history" below), which needs a lookup.
+handle.pause();
+handle.resume();
+handle.seek(new Date("2026-07-14T02:45:00Z"));  // server restarts the paced stream there
+handle.stop();                                   // ends the session, closes the socket
+handle.sessionId;                                // save to resume after a page reload
+```
+For range pickers, the metadata endpoints are still available:
+```ts
+// Which days actually HAVE data (populate/validate the date picker)
+const { days } = await client.replay.days({ airportId: "WARR", lookbackDays: 60 });
+// [{ day: "2026-07-14", eventCount: 51230, trackCount: 42,
+//    firstAt: "2026-07-14T01:58:03Z", lastAt: "2026-07-14T09:12:44Z" }, …]
+// A date absent from the list has no recorded data — don't offer it.
+const range = await client.replay.range({ from, to });
+// { earliest, latest, eventCount, trackCount }
+```
+Not using the SDK? The wire protocol is plain JSON on `/ws/tracks/replay` — documented in `docs/sdk/websocket.md` (§ Replay Streaming). `AeroReplayClient` is also exported standalone.
+### Federated history
+An airport can serve its **own** replay/history instead of AeroSwarm's — its own backend, its
+own database, reached directly (see `docs/development/federation/`). `replay.stream`,
+`replay.days`, `replay.range`, `tracks.history`, and `alerts.list` all resolve this
+automatically, in priority order:
+1. **Explicit override** — pass `endpoint` and the registry is skipped entirely:
+   ```ts
+   await client.replay.days({ endpoint: "http://192.168.2.225:4000/aero" });
+   ```
+2. **Registry** — if the airport's `history_endpoint` is set (`client.airports.list()` /
+   dashboard's Airports tab), calls for that `airportId` go there instead:
+   ```ts
+   const handle = await client.replay.stream({ from, to, airportId: "WARR" }, callbacks);
+   // WARR has history_endpoint set → connects to that backend's WS replay, transparently
+   ```
+3. **AeroSwarm itself** — the default, unchanged behavior, for any airport with no endpoint set.
+A lookup failure (e.g. `airports.list()` errors) always falls back to AeroSwarm's own endpoint
+rather than breaking replay — federation degrades safely.
+**Credential for the airport's backend.** By default the airport's backend gets the same `token`
+as AeroSwarm. When it expects something else — typically the user's login JWT, checked by the
+airport's gateway — pass `backendToken`; a function is read on **every** request, so a refreshed
+login is picked up without rebuilding the client. It falls back to `token` when it returns nothing.
+It applies only to calls that go to an airport's backend (`tracks.history`, `tracks.trail`,
+`replay.days`/`range`), never to AeroSwarm's own endpoint or the live WebSocket.
+```ts
+const client = new AeroSwarm({
+  endpoint, token,
+  backendToken: () => useAuthStore.getState().accessToken,
+});
+```
+`replay.window` and `replay.seek` are **not** part of the federation contract — they throw for a
+federated airport; use `replay.stream` (which covers the same "jump to a point in time" need via
+`seek()` on the returned handle) instead.
+Building the receiving side (an airport's own backend)? See
+[`@aeroswarm/replay-server`](../../server/replay-server/README.md) — mounts this exact protocol
+on top of your own database with a few lines of code.
+**Multi-airport.** Every replay call accepts `airportId` as *optional*. For a **federated**
+airport (one with a `historyEndpoint` — see the next section) it selects which airport backend
+to connect to; always pass it for those. Against AeroSwarm's own endpoint (dev/single-node
+mode) it's a row filter on the local database — omitting it returns all local rows. There is no
+cross-backend "all airports" merged replay: each federated airport's history lives behind its
+own backend, replayed one airport at a time.
+### Sources & webhooks
+A **source** is a registered sensor/feed (radar, ADS-B, synthetic, …) identified by a bearer
+token (`sourceToken`). Tag it with `airportId` at creation and that token **carries its airport
+with it** from then on — anything that authenticates with it (WS `/ws/tracks/live`,
+`/ws/tracks/replay`, tRPC, REST) is automatically scoped to that airport, with no need to keep
+passing `airportId` on every call:
+```ts
+const { sources } = await client.sources.list();               // all sources
+const { sources: warrSources } = await client.sources.list({ airportId: "WARR" });
+const created = await client.sources.create({
+  name: "WARR ASTERIX feed",
+  sourceType: "ASTERIX_CAT021",
+  airportId: "WARR",                        // ← ties this token to WARR
+});
+// { ok: true, data: { sourceId: "src_...", sourceToken: "srctk_...", airportId: "WARR" } }
+// Later, a client connecting with that token doesn't need to pass airportId at all:
+const scoped = new AeroSwarm({ endpoint, wsEndpoint, token: created.data.sourceToken });
+await scoped.tracks.stream({}); // already scoped to WARR — the token carries it
+await client.sources.health("src_abc");
+// Reassign (or clear, with null) a source's airport after the fact — takes
+// effect immediately, no need to wait out the token cache TTL.
+await client.sources.update({ id: "src_abc", airportId: "CGK" });
+await client.sources.update({ id: "src_abc", airportId: null });
+await client.webhooks.create({ url: "https://ops.example/hook", events: ["alert"] });
+const hooks = await client.webhooks.list();
+await client.webhooks.delete({ id: hooks[0].id });
+```
+`airportId` is required on `sources.create` — a source is a sensor physically at one airport, so
+a token that isn't tied to any airport is more footgun than feature. (Sources created before this
+was enforced may still have `airportId: null`; `sources.update` can backfill one.) For access
+that spans multiple airports, use the viewer/dashboard token instead — it's never auto-scoped
+this way, regardless of any source's configuration, and always sees whatever `airportId` (or lack
+thereof) it explicitly asks for.
+### `TrackCache`
+In-memory `Map`-backed track store with a typed emitter — the primitive the React store builds on:
+`applyUpdate(track)`, `applyRemoved(ev)`, `applySnapshot(tracks)` (authoritative — replaces contents), `getAll()`, `get(id)`, `getRenderable()` (only tracks with valid lat/lon), `size`, `clear()`, plus `update`/`removed`/`snapshot` events.
+### `AeroWsClient`
+Low-level WebSocket client (subscribe payloads, sequence tracking, heartbeats, reconnect/backoff, JSON + msgpack). Use `AeroSwarm.tracks.subscribe` unless you're building your own state layer.
+## React usage
+```tsx
+import { AeroSwarmProvider, useAeroTracks } from "@aeroswarm/client/react";
+function App() {
+  return (
+    <AeroSwarmProvider endpoint="http://…:8070" token={token}>
+      <LiveMap />
+    </AeroSwarmProvider>
+  );
+}
+function LiveMap() {
+  const { tracks, status, error, lastUpdateAt } = useAeroTracks({
+    bbox: [94, -11, 141, 6.5],
+    minConfidence: 0.5,
+    maxUpdateHz: 5,
+  });
+  if (status !== "connected") return <p>{status}…</p>;
+  return <ul>{tracks.map((t) => <li key={t.trackId}>{t.callsign ?? t.icao24}</li>)}</ul>;
+}
+```
+### Hooks (`@aeroswarm/client/react`)
+| Hook | Purpose |
+|------|---------|
+| `useAeroTracks(opts?)` (alias `useTracks`) | Live track list + connection state for a subscription |
+| `useAeroTrack(trackId)` | Single track by id |
+| `useAeroSnapshot(opts?)` | One-shot snapshot fetch |
+| `useAeroStatus()` | Connection status only |
+| `useTrackCount()` | Track count only (cheap selector) |
+| `useSourceHealth(sourceId?)` | Source health/status |
+| `useAlerts(opts?)` | Live alerts |
+| `useRules(opts?)` / `useRule(id, opts?)` | Alert rules |
+| `useWebhooks(opts?)` | Webhooks |
+| `useReplayStatus(sessionId, opts?)` / `useReplayStop()` | Replay session control |
+| `useLineage(eventId, opts?)` / `useLineageTrace(trackId, opts?)` | Event lineage/provenance |
+| `useTrackHistory(options)` | **Map animation engine** — see below |
+| `useAeroSwarmContext()` | Raw client from the provider |
+### `useTrackStore` — Zustand store
+Shared live-track state; feed it from your subscription callbacks and read it imperatively (maps) or via selectors (React):
+| Member | Notes |
+|--------|-------|
+| `tracks: Map<string, LabeledTrack>` | Current state (each track carries `labelCategory` / `labelColor`) |
+| `applyUpdate(track)` | One store write per event — prefer `applyBatch` at high rates |
+| `applyBatch(updates, removedIds)` | **One Map clone per batch** — use this from buffered/throttled feeds |
+| `applyRemoved({trackId})` / `applySnapshot(tracks)` | Snapshot is authoritative (replaces state — ghosts from a dropped connection are cleared) |
+| `pruneStale(maxAgeMs)` | Remove tracks not updated within `maxAgeMs`; returns removed ids. **Call on an interval** (e.g. 60 s sweep every 10 s) — track ids churn on feed/replay restarts and abandoned ids never get a `removed` event, so without pruning they linger as ghost icons |
+| `setStatus` / `setSourceStatus` / `setError` / `setDegraded` / `clear` | Connection metadata |
+| Selectors | `selectAllTracks`, `selectRenderableTracks`, `selectTrack(id)`, `selectTrackCount`, `selectStatus`, `selectIsDegraded`, `selectLastUpdateAt`, `selectError` |
+### REST errors: `AeroApiError`
+Every failed REST call (`client.rest.*`, federated `tracks.history` and the like) throws an `AeroApiError` that keeps what the server said, instead of just `GET /x → 500`:
+```ts
+try { await client.tracks.history({ trackId, airportId: "WARR" }); }
+catch (e) {
+  if (e instanceof AeroApiError) {
+    e.status;       // 403
+    e.code;         // "FORBIDDEN" — stable, for switch; a newer server may send a code you do not know
+    e.recoverable;  // retrying later may help (rate limit, server busy)
+    e.message;      // "Federated request /tracks/t1/history → 403: not your airport"
+    e.details;      // whatever the server attached
+  }
+}
+```
+Servers answer either in the standard format (`{ ok, data, meta }` / `{ ok: false, error: { code, message, recoverable } }`, see `@aeroswarm/core/api`) or in the older shape (bare data, `{ ok: false, error: "text" }`); both are read. Federated calls send `x-aero-envelope: 1` to get the standard format. `parseApiResponse(res)` and `readApiBody(res)` are exported for your own `fetch` calls.
+### `tracks.trail` / `createTrailPoller` / `useTrackTrail` — the path an aircraft has flown
+The airport's backend builds the trail (memory first, stored history as a fallback), so the client computes nothing: it gets a GeoJSON `FeatureCollection` with one `LineString` (`[lon, lat, altitude m]`) and a `Point` per time mark, each with `properties.label` already written in the time zone you ask for.
+```ts
+const { trail } = await client.tracks.trail({
+  trackId,
+  endpoint: "https://asmgcs.example/aero",   // the airport backend (or an airportId with a historyEndpoint)
+  tz: "Asia/Jakarta",                        // labels such as "01-11-26 11:16"; default UTC
+});
+// whole flight by default. fromMs/toMs: a period. stepM: coarser line. limit: at most n points. labelEveryMs: marks (default 2 min)
+```
+Keep it current while an aircraft is selected: the first request is the whole trail, after that only what is new is fetched (`sinceMs`), so polling every few seconds costs a few hundred bytes.
+```ts
+const poller = createTrailPoller(
+  (sinceMs) => client.tracks.trail({ trackId, endpoint, tz: "Asia/Jakarta", sinceMs }),
+  { pollMs: 5000, onUpdate: (trail) => draw(trail) },   // draw the line, and each mark's properties.label
+);
+poller.stop();                                          // when it is deselected
+```
+React: `const { trail, loading, error } = useTrackTrail(selectedTrackId, { endpoint, tz: "Asia/Jakarta" })` (pass `null` while nothing is selected). A fixed period (`toMs`) is fetched once. A trail already shown stays when a request fails; polling stops for good when the server says the track is unknown (`NOT_FOUND`). `mergeTrail(prev, delta)` and `trailEnd(trail)` are exported if you manage the polling yourself. To end the line at the icon, draw one more segment from the trail's last point to `createTrackMotion().sample(trackId)`.
+### `useTrackMotion` / `createTrackMotion` — smooth live tracks
+Feeds update a track once a second (MLAT, ADS-B) or once per antenna sweep (radar, ~7.5 s). Drawn as they arrive, icons jump. `createTrackMotion` (no React needed) shows where the aircraft *probably is right now* and eases corrections in, like a flight tracker:
+```ts
+import { createTrackMotion } from "@aeroswarm/client";
+const motion = createTrackMotion();                     // all options optional
+client.tracks.subscribe(opts, {
+  onSnapshot: (tracks, meta) => tracks.forEach((t) => motion.update(t, meta)),
+  onTrackUpdate: (t, meta) => motion.update(t, meta),   // meta.serverTime keeps the clocks aligned
+  onTrackRemoved: ({ trackId }) => motion.remove(trackId),
+});
+const stop = motion.start(({ changed }) => {            // ~30 frames/s, only tracks that moved
+  for (const [id, s] of changed) layer.put(id, s.lat, s.lon, s.headingDeg);
+});
+```
+React: `const motion = useTrackMotion({ onFrame })`, then call `motion.update(...)` from the subscription. Nothing here renders React.
+What it does:
+| | |
+|---|---|
+| **Dead reckoning** | From the last fix, speed and heading carry the position forward, up to `maxExtrapolateMs` (20 s in the air, 8 s on the surface). `lost` tracks freeze. |
+| **Eased corrections** | A new fix does not snap the icon. The gap between where it was shown and where the fix says it should be becomes an offset that fades out (smoothstep over `blendMs`, 1.5 s). The icon keeps moving at its own speed meanwhile, so there is no stop-and-go at every update. A correction larger than `snapDistanceM` (5 km) is a glitch and jumps. |
+| **Heading** | Eases along the shortest arc (`headingSmoothMs`, 0.8 s); keeps the last heading when the track stops. |
+| **Server clock** | `lastSeenAt` is the server's clock. `meta.serverTime` of each message lets the engine learn the offset to the browser clock (the estimate with the least network delay wins), so a wrong browser clock does not stretch or shrink the prediction. |
+| **Cheap frames** | Tracks that stand still, or whose picture changed by less than `epsilonM` (0.5 m) / 0.5°, are not reported; no timer runs while nothing moves; `frameHz` caps the rate (30). |
+Options (`MotionOptions`): `blendMs`, `headingSmoothMs`, `maxExtrapolateMs`, `minMovingKt` (5), `snapDistanceM`, `frameHz`, `epsilonM`, `extrapolate` (`false` shows raw positions, for comparing sources), `isSurface`, `clock` (inject the replay clock to play back at another speed), `scheduler` (tests). `motion.sample(id)` gives the shown position at any time without touching frame state, e.g. to attach a trail's head to the icon.
+### `useTrackHistory` — smooth map animation (deprecated: use `useTrackMotion`)
+Maintains per-track position interpolation (tweening), dead-reckoning between updates, and bounded trail history, emitting animation frames outside React render:
+```ts
+const { processUpdate, processRemove } = useTrackHistory({
+  maxHistoryPoints: 500,   // trail length cap per track
+  minDeltaDeg: 0.0001,     // ignore sub-threshold jitter
+  maxJumpDeg: 5.0,         // discard implausible teleports
+  onFrame: ({ currentPositions, history, isMoving }) => drawMarkers(...),
+});
+```
+Update gaps longer than 30 s (lost coverage, socket offline) restart the track's trail instead of drawing a straight line across the map. Speeds beyond 1 200 kt (misdecodes, or position deltas divided by a compressed replay clock) are rejected and never drive dead reckoning.
+## Frontend recipes
+### Live map, end to end
+The proven wiring (this is what the reference dashboard does):
+```tsx
+// 1. Subscription → store, batched (never setState per message)
+const pending = new Map<string, CurrentTrack>();
+const removed = new Set<string>();
+client.tracks.subscribe(opts, {
+  onSnapshot:     (ts) => useTrackStore.getState().applySnapshot(ts),
+  onTrackUpdate:  (t)  => { pending.set(t.trackId, t); removed.delete(t.trackId); },
+  onTrackRemoved: (ev) => { pending.delete(ev.trackId); removed.add(ev.trackId); },
+});
+setInterval(() => {
+  useTrackStore.getState().applyBatch([...pending.values()], [...removed]);
+  pending.clear(); removed.clear();
+}, 250);
+// 2. Ghost cleanup — ids churn on feed/replay restarts
+setInterval(() => { useTrackStore.getState().pruneStale(60_000); }, 10_000);
+// 3. Store → animation engine → map markers (imperative, no React re-render)
+const { processUpdate, processRemove } = useTrackHistory({ onFrame: drawMarkers });
+useTrackStore.subscribe((state, prev) => {
+  for (const [id, t] of state.tracks) if (prev.tracks.get(id) !== t) processUpdate(t);
+  for (const id of prev.tracks.keys()) if (!state.tracks.has(id)) processRemove(id);
+});
+```
+### Replay in the same map
+Feed `replay.stream` callbacks into the **same** store/animation path and pause the live subscription while a session is active — replay then looks exactly like live. Batch `onTrackUpdate` into ~250 ms flushes the same way.
+### Assigned-route overlay
+```ts
+const { routes } = await client.routes.list({ airportId });
+const { assignments } = await client.routes.assignments();
+const route = routes.find(r => r.routeId === assignments.find(a => a.trackId === selectedId)?.routeId);
+// draw route.points ([lat, lon][]) as a dashed LineString: points.map(([lat, lon]) => [lon, lat])
+```
+## Performance notes (important for dashboards)
+- **Don't call a React `setState` per WS message.** At realistic rates (hundreds of tracks × several Hz) that renders your page thousands of times per second. Buffer updates and flush on an interval (~250 ms to the store for the map, ~1 s to React state for panels), using `applyBatch`.
+- **Request only the rate you need** — `maxUpdateHz: 5` with client-side interpolation looks identical to 20 Hz on a map and cuts WS traffic 4×.
+- Drive map markers **imperatively** from `useTrackStore.subscribe(...)` + `useTrackHistory`, not through React props.
+## Wire encoding
+`json` (default) or `msgpack` (binary, lower bandwidth) — set once in `AeroSwarmOptions.encoding` or per-subscription.
+## Environment variables (Vite frontends)
+| Variable | Description |
+|----------|-------------|
+| `VITE_AEROSWARM_API_URL` | REST/tRPC/GraphQL base URL |
+| `VITE_AEROSWARM_WS_URL` | WebSocket base URL |
+| `VITE_AEROSWARM_API_KEY` | Viewer token |
+These are baked into the bundle at build time (Vite), not read at runtime.
+## Building & testing
+```bash
+pnpm run build     # tsup → dist/ (index + /sdk + /react)
+pnpm run typecheck
+pnpm test
+```