@aeroswarm/client 0.1.13 → 0.1.15

package/README.md

@@ -65,6 +65,23 @@ client.disconnect();
 | `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
 
@@ -106,6 +123,7 @@ The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client
   "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,
@@ -127,23 +145,8 @@ The server sends JSON envelopes `{ type, seq, serverTime, payload }`. The client
 ```
 
 `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.
-| `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 |
+
+`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
 
@@ -449,6 +452,49 @@ Shared live-track state; feed it from your subscription callbacks and read it im
 | `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:

package/dist/index-ByNBpjNk.d.ts

@@ -0,0 +1,75 @@
+import { CurrentTrack } from '@aeroswarm/core/types';
+
+/** What the engine reads from a track. */
+type MotionInput = Pick<CurrentTrack, "trackId" | "lat" | "lon" | "groundSpeedKt" | "headingDeg" | "altitudeFt" | "status" | "lastSeenAt"> & {
+    targetType?: CurrentTrack["targetType"];
+};
+interface MotionSample {
+    lat: number;
+    lon: number;
+    /** Degrees 0..360, eased; null until a valid heading has been seen. */
+    headingDeg: number | null;
+    altitudeFt: number | null;
+    /** Speed is above `minMovingKt`. */
+    moving: boolean;
+    /** Position currently comes from dead reckoning (not frozen, limit not reached). */
+    extrapolating: boolean;
+}
+interface MotionFrame {
+    /** Server-aligned time of this frame (ms). */
+    at: number;
+    /** Only tracks whose picture changed since the previous frame. */
+    changed: ReadonlyMap<string, MotionSample>;
+}
+interface MotionScheduler {
+    request(callback: (timestamp: number) => void): unknown;
+    cancel(handle: unknown): void;
+}
+interface MotionOptions {
+    /** How long a correction takes to fade out. Default 1500 ms. */
+    blendMs?: number;
+    /** How long the icon takes to turn to a new heading. Default 800 ms. */
+    headingSmoothMs?: number;
+    /** Dead reckoning stops after this long without a new fix. Default 20 s in the air, 8 s on the surface. */
+    maxExtrapolateMs?: {
+        air: number;
+        surface: number;
+    };
+    /** Below this speed a track is treated as standing still. Default 5 kt. */
+    minMovingKt?: number;
+    /** A correction larger than this is a glitch or a sensor change far away: jump instead of easing. Default 5000 m. */
+    snapDistanceM?: number;
+    /** Frame rate limit for `start()`. Default 30. */
+    frameHz?: number;
+    /** Changes smaller than this are not reported. Default 0.5 m (and 0.5 degrees of heading). */
+    epsilonM?: number;
+    /** false = show raw positions (for comparing against another source). Default true. */
+    extrapolate?: boolean;
+    /** Decides what counts as "on the surface". Default: vehicles, or below 150 ft. */
+    isSurface?: (track: MotionInput) => boolean;
+    /** Browser clock. Default Date.now. Inject the replay clock to play back at another speed. */
+    clock?: () => number;
+    /** Frame timer. Default requestAnimationFrame, else setTimeout. Inject in tests. */
+    scheduler?: MotionScheduler;
+}
+interface TrackMotion {
+    /** `meta.serverTime` (from the WS envelope) keeps the server/browser clock offset current. */
+    update(track: MotionInput, meta?: {
+        serverTime?: number;
+    }): void;
+    remove(trackId: string): void;
+    clear(): void;
+    /** Where the track is shown at `at` (browser time; default now). Pure: does not touch frame state. */
+    sample(trackId: string, at?: number): MotionSample | undefined;
+    /** One frame: the tracks whose picture changed since the previous frame. `start()` calls this for you. */
+    tick(at?: number): ReadonlyMap<string, MotionSample>;
+    /** Runs frames until the returned function is called. Idles (no timer) while nothing moves. */
+    start(onFrame: (frame: MotionFrame) => void): () => void;
+    /** Tracks currently held. */
+    readonly size: number;
+    /** Current server minus browser clock, ms. */
+    offsetMs(): number;
+}
+declare function createTrackMotion(options?: MotionOptions): TrackMotion;
+
+export { type MotionFrame as M, type TrackMotion as T, type MotionInput as a, type MotionOptions as b, type MotionSample as c, type MotionScheduler as d, createTrackMotion as e };

package/dist/{index-BXiTmKdS.d.ts → index-CeayQnTp.d.ts}

@@ -264,6 +264,101 @@ declare class AeroReplayClient {
 declare function createAeroTrpcClient(endpoint: string, token: string): _trpc_client.TRPCClient<any>;
 type AeroTrpcClient = ReturnType<typeof createAeroTrpcClient>;
 
+interface TrailLine {
+    type: "Feature";
+    properties: {
+        kind: "trail";
+        trackId: string;
+        /** epoch ms of the first and the last point */
+        from: number;
+        to: number;
+        /** spacing of the points, metres */
+        stepM: number;
+        /** the line starts at the beginning of the flight (nothing older exists) */
+        fromStart: boolean;
+    };
+    /** [lon, lat, altitude in metres] */
+    geometry: {
+        type: "LineString";
+        coordinates: Array<[number, number, number]>;
+    };
+}
+interface TrailMark {
+    type: "Feature";
+    /** `label` is ready to display, e.g. "01-11-26 11:16" */
+    properties: {
+        kind: "mark";
+        t: number;
+        label: string;
+    };
+    geometry: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+}
+interface TrailFeatureCollection {
+    type: "FeatureCollection";
+    features: Array<TrailLine | TrailMark>;
+}
+interface TrailMeta {
+    serverTime?: number;
+    count?: number;
+    /** the server dropped points to honour `limit` */
+    truncated?: boolean;
+}
+interface TrailResult {
+    trail: TrailFeatureCollection;
+    meta?: TrailMeta;
+}
+interface TrailRequest {
+    trackId: string;
+    /** The airport backend's base URL (its `/aero` mount). Without it `airportId` must have a registered historyEndpoint. */
+    endpoint?: string;
+    airportId?: string;
+    /** A period instead of the whole flight (epoch ms). */
+    fromMs?: number;
+    toMs?: number;
+    /** Only what is newer than this: for keeping a trail current. */
+    sinceMs?: number;
+    /** Coarser spacing than the server stores, metres. */
+    stepM?: number;
+    /** At most this many points. */
+    limit?: number;
+    /** A time mark every this many ms (default 120 000), aligned to the clock. 0 = none. */
+    labelEveryMs?: number;
+    /** Time zone of the labels, e.g. "Asia/Jakarta" (default UTC). */
+    tz?: string;
+    labelFormat?: "datetime" | "time";
+}
+/** Time of the last point of a trail; undefined when it has none. What to pass as `sinceMs`. */
+declare function trailEnd(trail: TrailFeatureCollection): number | undefined;
+/**
+ * Appends a delta (a request with `sinceMs`) to the trail you already have. Returns `prev`
+ * itself when the delta adds nothing, so a caller can tell nothing changed.
+ */
+declare function mergeTrail(prev: TrailFeatureCollection | undefined, delta: TrailFeatureCollection): TrailFeatureCollection;
+interface TrailPollerOptions {
+    /** How often to ask for what is new. Default 5000. 0 or less: fetch once and stop. */
+    pollMs?: number;
+    /** Called with the whole trail, first when it arrives, then each time it grows. */
+    onUpdate: (trail: TrailFeatureCollection) => void;
+    onError?: (err: unknown) => void;
+    /** Stop for good when the server says the track is unknown (it left and its retention ended). Default true. */
+    stopWhenGone?: boolean;
+}
+interface TrailPoller {
+    stop(): void;
+    /** Ask now instead of waiting for the next tick. */
+    refresh(): Promise<void>;
+    /** The trail as it stands. */
+    current(): TrailFeatureCollection | undefined;
+}
+/**
+ * Fetches a trail once and then keeps it current by asking only for what is new.
+ * Framework-free: `useTrackTrail` is a thin wrapper around it.
+ */
+declare function createTrailPoller(fetchTrail: (sinceMs?: number) => Promise<TrailResult>, options: TrailPollerOptions): TrailPoller;
+
 declare class AeroGraphQLClient {
     private readonly endpoint;
     private readonly token;
@@ -332,6 +427,53 @@ declare class TrackCache extends TypedEmitter<{
     })[];
 }
 
+/** Mirrors `API_ERROR_CODES` in @aeroswarm/core/api. A server may send codes this client does not know. */
+type ApiErrorCode = "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "BAD_REQUEST" | "CONFLICT" | "RATE_LIMITED" | "UNAVAILABLE" | "INTERNAL";
+/** The code for an HTTP status when the server sent none. */
+declare function codeForStatus(status: number): ApiErrorCode;
+interface ApiErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    recoverable: boolean;
+    details?: unknown;
+}
+/** A REST call failed. `code` is stable and meant for `switch`; `message` is for people. */
+declare class AeroApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Retrying later may succeed (rate limit, server busy or failing). */
+    readonly recoverable: boolean;
+    readonly details?: unknown;
+    constructor(init: ApiErrorInit);
+}
+/**
+ * The parsed JSON of a response, untouched. Throws `AeroApiError` for a non-2xx status
+ * and for a 2xx that carries `{ ok: false }`. For endpoints whose callers read the
+ * envelope themselves (`r.data.x`).
+ */
+declare function readApiBody(res: Response, label?: string): Promise<unknown>;
+/** What a standard response says about itself (see `meta` in @aeroswarm/core/api). Absent for servers that answer with bare data. */
+interface ApiMetaLike {
+    serverTime?: number;
+    count?: number;
+    nextCursor?: string;
+    truncated?: boolean;
+}
+/**
+ * The data of a response together with its `meta`: unwrapped from `{ ok, data, meta }`, or the body
+ * as it is (and no meta) for servers that answer with bare data. Throws `AeroApiError` on failure.
+ */
+declare function parseApiEnvelope<T>(res: Response, label?: string): Promise<{
+    data: T;
+    meta?: ApiMetaLike;
+}>;
+/**
+ * The data of a response: unwrapped from `{ ok, data }`, or the body as it is for servers
+ * that answer with bare data. Throws `AeroApiError` on failure.
+ */
+declare function parseApiResponse<T>(res: Response, label?: string): Promise<T>;
+
 interface AeroSwarmOptions {
     endpoint: string;
     token: string;
@@ -391,6 +533,7 @@ declare class AeroSwarm {
      *  (a broken airports.list() call must never brick replay/history for
      *  everyone else). */
     private resolveHistoryEndpoint;
+    private federatedRequest;
     private federatedFetch;
     constructor(opts: AeroSwarmOptions);
     readonly tracks: {
@@ -419,6 +562,15 @@ declare class AeroSwarm {
             limit?: number;
             endpoint?: string;
         }) => Promise<TrackHistoryPoint[]>;
+        /**
+         * The path an aircraft has flown, ready to draw: a GeoJSON line plus a point for every time
+         * mark, with the label already written in `tz`. By default the whole flight so far; `fromMs`
+         * and `toMs` choose a period, `sinceMs` fetches only what is new (see `createTrailPoller`),
+         * `stepM` asks for a coarser line. The airport's backend builds it (memory first, history
+         * as a fallback), so nothing is computed here. There is no AeroSwarm-side equivalent:
+         * pass `endpoint` or an `airportId` with a registered `historyEndpoint`.
+         */
+        trail: (input: TrailRequest) => Promise<TrailResult>;
     };
     /** Flight plans received from AFTN feeds. Live tracks that correlate with a
      *  plan (Mode-S address, else callsign) also carry `track.flightPlan`. */
@@ -698,4 +850,4 @@ declare class AeroSwarm {
     reconnect(): boolean;
 }
 
-export { AeroReplayClient as A, type DayAvailability as D, type FlightPlanRow as F, LABEL_COLORS as L, type ReplayCallbacks as R, type SourceRow as S, TrackCache as T, type UseAeroTracksResult as U, AeroSwarm as a, type AeroSwarmOptions as b, AeroWsClient as c, type AftnMessageRow as d, type LabelCategory as e, type LabeledTrack as f, type LiveTrackCallbacks as g, type ReplayHandle as h, type ReplayProgress as i, type ReplayStreamOptions as j, type StreamMeta as k, type SubscribeOptions as l, type TrackCallbacks as m, type TrackHistoryPoint as n, getLabelCategory as o, withLabel as w };
+export { AeroApiError as A, codeForStatus as B, createTrailPoller as C, type DayAvailability as D, getLabelCategory as E, type FlightPlanRow as F, mergeTrail as G, parseApiEnvelope as H, parseApiResponse as I, readApiBody as J, trailEnd as K, LABEL_COLORS as L, withLabel as M, type ReplayCallbacks as R, type SourceRow as S, TrackCache as T, type UseAeroTracksResult as U, AeroReplayClient as a, AeroSwarm as b, type AeroSwarmOptions as c, AeroWsClient as d, type AftnMessageRow as e, type ApiErrorCode as f, type ApiErrorInit as g, type ApiMetaLike as h, type LabelCategory as i, type LabeledTrack as j, type LiveTrackCallbacks as k, type ReplayHandle as l, type ReplayProgress as m, type ReplayStreamOptions as n, type StreamMeta as o, type SubscribeOptions as p, type TrackCallbacks as q, type TrackHistoryPoint as r, type TrailFeatureCollection as s, type TrailLine as t, type TrailMark as u, type TrailMeta as v, type TrailPoller as w, type TrailPollerOptions as x, type TrailRequest as y, type TrailResult as z };

package/dist/index.d.ts

@@ -1,79 +1,26 @@
-export { A as AeroReplayClient, a as AeroSwarm, b as AeroSwarmOptions, c as AeroWsClient, d as AftnMessageRow, D as DayAvailability, F as FlightPlanRow, L as LABEL_COLORS, e as LabelCategory, f as LabeledTrack, g as LiveTrackCallbacks, R as ReplayCallbacks, h as ReplayHandle, i as ReplayProgress, j as ReplayStreamOptions, S as SourceRow, k as StreamMeta, l as SubscribeOptions, T as TrackCache, m as TrackCallbacks, n as TrackHistoryPoint, U as UseAeroTracksResult, o as getLabelCategory, w as withLabel } from './index-BXiTmKdS.js';
+export { A as AeroApiError, a as AeroReplayClient, b as AeroSwarm, c as AeroSwarmOptions, d as AeroWsClient, e as AftnMessageRow, f as ApiErrorCode, g as ApiErrorInit, h as ApiMetaLike, D as DayAvailability, F as FlightPlanRow, L as LABEL_COLORS, i as LabelCategory, j as LabeledTrack, k as LiveTrackCallbacks, R as ReplayCallbacks, l as ReplayHandle, m as ReplayProgress, n as ReplayStreamOptions, S as SourceRow, o as StreamMeta, p as SubscribeOptions, T as TrackCache, q as TrackCallbacks, r as TrackHistoryPoint, s as TrailFeatureCollection, t as TrailLine, u as TrailMark, v as TrailMeta, w as TrailPoller, x as TrailPollerOptions, y as TrailRequest, z as TrailResult, U as UseAeroTracksResult, B as codeForStatus, C as createTrailPoller, E as getLabelCategory, G as mergeTrail, H as parseApiEnvelope, I as parseApiResponse, J as readApiBody, K as trailEnd, M as withLabel } from './index-CeayQnTp.js';
 import { CurrentTrack } from '@aeroswarm/core/types';
-export { AeroConnectionStatus, AeroRecoverableError, Bbox, ConfidenceBudget, CurrentTrack, FlightPhase, FlightPlan, FlightPlanStatus, FlightPlanSummary, FusedTrackEvent, Position, Protocol, SourceHealthEvent, SourceStatus, StreamEnvelope, TrackSource, TrackStatus, Velocity } from '@aeroswarm/core/types';
+export { AeroConnectionStatus, AeroRecoverableError, Bbox, ConfidenceBudget, CurrentTrack, DataSource, FlightPhase, FlightPlan, FlightPlanStatus, FlightPlanSummary, FusedTrackEvent, Position, Protocol, SourceHealthEvent, SourceStatus, StreamEnvelope, TrackSource, TrackStatus, Velocity } from '@aeroswarm/core/types';
 export { clamp, haversineKm, isInsideBbox, isRenderableTrack, toCurrentTrack } from '@aeroswarm/core/utils';
+export { M as MotionFrame, a as MotionInput, b as MotionOptions, c as MotionSample, d as MotionScheduler, T as TrackMotion, e as createTrackMotion } from './index-ByNBpjNk.js';
 import '@trpc/client';
 
-/** What the engine reads from a track. */
-type MotionInput = Pick<CurrentTrack, "trackId" | "lat" | "lon" | "groundSpeedKt" | "headingDeg" | "altitudeFt" | "status" | "lastSeenAt"> & {
-    targetType?: CurrentTrack["targetType"];
-};
-interface MotionSample {
-    lat: number;
-    lon: number;
-    /** Degrees 0..360, eased; null until a valid heading has been seen. */
-    headingDeg: number | null;
-    altitudeFt: number | null;
-    /** Speed is above `minMovingKt`. */
-    moving: boolean;
-    /** Position currently comes from dead reckoning (not frozen, limit not reached). */
-    extrapolating: boolean;
-}
-interface MotionFrame {
-    /** Server-aligned time of this frame (ms). */
-    at: number;
-    /** Only tracks whose picture changed since the previous frame. */
-    changed: ReadonlyMap<string, MotionSample>;
-}
-interface MotionScheduler {
-    request(callback: (timestamp: number) => void): unknown;
-    cancel(handle: unknown): void;
-}
-interface MotionOptions {
-    /** How long a correction takes to fade out. Default 1500 ms. */
-    blendMs?: number;
-    /** How long the icon takes to turn to a new heading. Default 800 ms. */
-    headingSmoothMs?: number;
-    /** Dead reckoning stops after this long without a new fix. Default 20 s in the air, 8 s on the surface. */
-    maxExtrapolateMs?: {
-        air: number;
-        surface: number;
-    };
-    /** Below this speed a track is treated as standing still. Default 5 kt. */
-    minMovingKt?: number;
-    /** A correction larger than this is a glitch or a sensor change far away: jump instead of easing. Default 5000 m. */
-    snapDistanceM?: number;
-    /** Frame rate limit for `start()`. Default 30. */
-    frameHz?: number;
-    /** Changes smaller than this are not reported. Default 0.5 m (and 0.5 degrees of heading). */
-    epsilonM?: number;
-    /** false = show raw positions (for comparing against another source). Default true. */
-    extrapolate?: boolean;
-    /** Decides what counts as "on the surface". Default: vehicles, or below 150 ft. */
-    isSurface?: (track: MotionInput) => boolean;
-    /** Browser clock. Default Date.now. Inject the replay clock to play back at another speed. */
-    clock?: () => number;
-    /** Frame timer. Default requestAnimationFrame, else setTimeout. Inject in tests. */
-    scheduler?: MotionScheduler;
-}
-interface TrackMotion {
-    /** `meta.serverTime` (from the WS envelope) keeps the server/browser clock offset current. */
-    update(track: MotionInput, meta?: {
-        serverTime?: number;
-    }): void;
-    remove(trackId: string): void;
-    clear(): void;
-    /** Where the track is shown at `at` (browser time; default now). Pure: does not touch frame state. */
-    sample(trackId: string, at?: number): MotionSample | undefined;
-    /** One frame: the tracks whose picture changed since the previous frame. `start()` calls this for you. */
-    tick(at?: number): ReadonlyMap<string, MotionSample>;
-    /** Runs frames until the returned function is called. Idles (no timer) while nothing moves. */
-    start(onFrame: (frame: MotionFrame) => void): () => void;
-    /** Tracks currently held. */
-    readonly size: number;
-    /** Current server minus browser clock, ms. */
-    offsetMs(): number;
-}
-declare function createTrackMotion(options?: MotionOptions): TrackMotion;
+/**
+ * Short label for the kind of sensor behind a track.
+ *
+ *   ADSB     ADS-B (CAT021, or raw ADS-B)
+ *   SURFACE  surface movement data (CAT010 / CAT011): SMR, MLAT or an ADS-B station on the ground
+ *   MLAT     multilateration (CAT020)
+ *   RADAR    radar plots and tracks (CAT048)
+ *   SYSTEM   system track (CAT062)
+ *   FUSED    several sensors merged
+ */
+type SourceLabel = "ADSB" | "SURFACE" | "MLAT" | "RADAR" | "SYSTEM" | "FUSED";
+declare function sourceLabel(source: CurrentTrack["source"]): SourceLabel;
+/**
+ * The sensor behind a track as a display string: `"ADSB 32/136"` (kind, then SAC/SIC),
+ * or just `"ADSB"` when the feed gave no SAC/SIC.
+ */
+declare function formatDataSource(track: Pick<CurrentTrack, "source" | "dataSource">): string;
 
-export { type MotionFrame, type MotionInput, type MotionOptions, type MotionSample, type MotionScheduler, type TrackMotion, createTrackMotion };
+export { type SourceLabel, formatDataSource, sourceLabel };