@aeroswarm/client 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -1,696 +1,79 @@
-import * as _aeroswarm_core_types from '@aeroswarm/core/types';
-import { FlightPlan, CurrentTrack, SourceStatus, AeroConnectionStatus, AeroRecoverableError, Bbox } from '@aeroswarm/core/types';
+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';
+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';
-import * as _trpc_client from '@trpc/client';
 export { clamp, haversineKm, isInsideBbox, isRenderableTrack, toCurrentTrack } from '@aeroswarm/core/utils';
+import '@trpc/client';
 
-interface SourceRow {
-    id: string;
-    name: string;
-    type: string;
-    sourceToken: string;
-    createdAt: string;
-    /** Airport this source's data belongs to. When set, anything that
-     *  authenticates with this source's token (WS live/replay, tRPC calls)
-     *  is scoped to this airport automatically. */
-    airportId?: string | null;
-}
-
-/** A flight plan plus the live track it currently correlates with (null = not on radar). */
-type FlightPlanRow = FlightPlan & {
-    trackId: string | null;
-};
-/** One raw AFTN message from the live log (newest first, capped by the service). */
-interface AftnMessageRow {
-    id: string;
-    receivedAt: number;
-    airportId: string | null;
-    feedId: string | null;
-    callsign: string | null;
-    type: string;
-    adep?: string;
-    ades?: string;
-    raw: string;
-}
-declare class AeroRestClient {
-    private readonly endpoint;
-    private readonly token;
-    constructor(endpoint: string, token: string);
-    private req;
-    createSource(body: Record<string, unknown>): Promise<{
-        ok: boolean;
-        data: {
-            sourceId: string;
-            sourceToken: string;
-            airportId?: string | null;
-        };
-    }>;
-    listSources(): Promise<{
-        ok: boolean;
-        data: {
-            sources: SourceRow[];
-        };
-    }>;
-    deleteSource(id: string): Promise<{
-        ok: boolean;
-    }>;
-    createWebhook(body: {
-        url: string;
-        events: string[];
-        secret?: string;
-    }): Promise<{
-        webhookId: string;
-    }>;
-    getTracksCurrent(params?: {
-        bbox?: [number, number, number, number];
-        minConfidence?: number;
-    }): Promise<{
-        tracks: unknown[];
-        count: number;
-    }>;
-    /** Flight plans received from AFTN feeds (FPL/CHG/DLA/DEP/ARR/CNL folded per flight). */
-    listFlightPlans(params?: {
-        airportId?: string;
-        status?: string;
-        callsign?: string;
-        limit?: number;
-    }): Promise<{
-        ok: boolean;
-        data: {
-            flightPlans: FlightPlanRow[];
-            count: number;
-        };
-    }>;
-    getFlightPlan(id: string): Promise<{
-        ok: boolean;
-        data: {
-            flightPlan: FlightPlan;
-        };
-    }>;
-    /** Raw AFTN messages (every parsed ATS message, newest first — the input
-     *  side of the flight-plan pipeline). */
-    listAftnMessages(params?: {
-        airportId?: string;
-        limit?: number;
-    }): Promise<{
-        ok: boolean;
-        data: {
-            messages: AftnMessageRow[];
-            count: number;
-        };
-    }>;
-    health(): Promise<{
-        status: string;
-    }>;
-}
-
-type WsEncoding = "json" | "msgpack";
-interface SubscribeOptions {
-    bbox?: [number, number, number, number];
-    /** Scope the stream to tracks stamped with this ICAO airport code, e.g. "WARR" */
-    airportId?: string;
-    source?: "fused" | "normalized";
-    minConfidence?: number;
-    maxTracks?: number;
-    mode?: "delta" | "full";
-    maxUpdateHz?: number;
-    encoding?: WsEncoding;
-    staleAfterMs?: number;
-    removeAfterMs?: number;
-}
-interface TrackCallbacks {
-    onTrackUpdate?: (track: CurrentTrack) => void;
-    onTrackRemoved?: (event: {
-        trackId: string;
-        reason: string;
-    }) => void;
-    onSnapshot?: (tracks: CurrentTrack[]) => void;
-    onSourceStatus?: (event: {
-        sourceId: string;
-        status: SourceStatus;
-    }) => void;
-    onStatusChange?: (status: AeroConnectionStatus) => void;
-    onError?: (err: AeroRecoverableError) => void;
-    onDegraded?: (reason: string) => void;
-}
-declare class AeroWsClient {
-    private readonly url;
-    private readonly token;
-    private readonly maxReconnectDelay;
-    private readonly heartbeatTimeoutMs;
-    private ws;
-    private attempt;
-    private stopped;
-    private lastSubscribe;
-    private callbacks;
-    private lastSeq;
-    private lastHeartbeat;
-    private heartbeatTimer;
-    private reconnectTimer;
-    private status;
-    constructor(url: string, token: string, maxReconnectDelay?: number, heartbeatTimeoutMs?: number);
-    connect(opts: SubscribeOptions, callbacks: TrackCallbacks): void;
-    updateFilter(opts: Partial<Pick<SubscribeOptions, 'bbox' | 'minConfidence' | 'maxUpdateHz' | 'maxTracks'>>): void;
-    disconnect(): void;
-    /**
-     * Force a fresh connection now, skipping any backoff wait. Re-subscribes with
-     * the last `connect()` options (the server then sends a new snapshot).
-     * Also resumes after `disconnect()`. No-op if `connect()` was never called.
-     * Returns false in that no-op case.
-     */
-    reconnect(): boolean;
-    getStatus(): AeroConnectionStatus;
-    private _setStatus;
-    /** Close the current socket without letting its onclose schedule a reconnect. */
-    private _dropSocket;
-    private _connect;
-    private _handleRaw;
-    private _requestSnapshot;
-    private _resetHeartbeatTimer;
-    private _clearHeartbeatTimer;
-    private _scheduleReconnect;
-    private _clearReconnectTimer;
-}
-
-/**
- * Server-paced WS replay client for `/ws/tracks/replay`.
- *
- * The server streams historical `fused_tracks` events at `speed`× real
- * time (paced server-side against a wall-clock anchor), so the client
- * receives replay frames exactly like live traffic: a `snapshot`
- * envelope with the state at `from`, then `track.updated` /
- * `track.removed` envelopes, plus `replay.progress` heartbeats and a
- * final `replay.done`.
- *
- * The wire protocol is plain JSON, so consumers that don't use this SDK
- * can speak it manually:
- *
- *   → connect  wss://host/ws/tracks/replay?token=TOKEN[&airportId=WARR][&sessionId=ID]
- *   → send     { "type": "replay.start",  "from": ISO, "to": ISO, "speed": 2 }
- *   → send     { "type": "replay.pause" } · { "type": "replay.resume" }
- *   → send     { "type": "replay.seek",   "at": ISO }
- *   → send     { "type": "replay.stop" }
- *   ← recv     { "type": "snapshot",        "payload": { "tracks": [...], "sessionId": ID } }
- *   ← recv     { "type": "track.updated",   "payload": { "track": {...} } }
- *   ← recv     { "type": "track.removed",   "payload": { "trackId": ID, "reason": "dropped" } }
- *   ← recv     { "type": "replay.progress", "payload": { "at": ISO, "pct": 0-100, "sessionId": ID } }
- *   ← recv     { "type": "replay.done",     "payload": { "sessionId": ID } }
- *
- * Reconnecting with the same `sessionId` (within 1 h) resumes a replay
- * from its last saved position.
- */
-interface ReplayStreamOptions {
-    from: Date | string;
-    to: Date | string;
-    /** Playback speed multiplier (1 = realtime). Default 1. */
-    speed?: number;
-    /** Which airport to replay. Federated airports (with a historyEndpoint)
-     *  are resolved by AeroSwarm.replay.stream to their own backend; against
-     *  AeroSwarm's own endpoint this is a row filter on the local DB. */
-    airportId?: string;
-    /** Resume a previous session instead of starting fresh. */
-    sessionId?: string;
-}
-interface ReplayProgress {
-    /** Replay-time position (ISO timestamp) */
-    at: string;
-    /** 0–100 within the requested range */
-    pct: number;
-    sessionId: string;
-}
-interface ReplayCallbacks {
-    /** State at `from` — arrives once per start/seek. */
-    onSnapshot?: (tracks: CurrentTrack[], sessionId: string) => void;
-    onTrackUpdate?: (track: CurrentTrack) => void;
-    onTrackRemoved?: (event: {
-        trackId: string;
-        reason: string;
-    }) => void;
-    onProgress?: (progress: ReplayProgress) => void;
-    onDone?: (sessionId: string) => void;
-    onError?: (error: Error) => void;
-}
-interface ReplayHandle {
-    readonly sessionId: string | null;
-    pause(): void;
-    resume(): void;
-    /** Jump to a replay-time position; the server restarts the paced stream there. */
-    seek(at: Date | string): void;
-    /** End the replay and close the socket. */
-    stop(): void;
-}
-declare class AeroReplayClient {
-    private readonly wsBase;
-    private readonly token;
-    /** Default "/ws/tracks/replay" (AeroSwarm's own endpoint). A federated
-     *  airport backend running @aeroswarm/replay-server's default mount
-     *  uses "/replay" instead — see AeroSwarm.replay.stream's endpoint
-     *  resolution. */
-    private readonly wsPath;
-    constructor(wsBase: string, token: string, 
-    /** Default "/ws/tracks/replay" (AeroSwarm's own endpoint). A federated
-     *  airport backend running @aeroswarm/replay-server's default mount
-     *  uses "/replay" instead — see AeroSwarm.replay.stream's endpoint
-     *  resolution. */
-    wsPath?: string);
-    /** Open a replay stream. Returns a handle for transport control. */
-    stream(opts: ReplayStreamOptions, callbacks: ReplayCallbacks): ReplayHandle;
-}
-
-declare function createAeroTrpcClient(endpoint: string, token: string): _trpc_client.TRPCClient<any>;
-type AeroTrpcClient = ReturnType<typeof createAeroTrpcClient>;
-
-declare class AeroGraphQLClient {
-    private readonly endpoint;
-    private readonly token;
-    constructor(endpoint: string, token: string);
-    query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
-}
-
-/**
- * Callsign-label category of a track, in priority order:
- * LOST (track status "lost") > GROUND_VEHICLE > ARRIVAL / DEPARTURE > UNKNOWN.
- * ARRIVAL/DEPARTURE come from the correlated flight plan, relative to the
- * track's airport (`track.flightPlan.phase`).
- */
-type LabelCategory = "ARRIVAL" | "DEPARTURE" | "GROUND_VEHICLE" | "LOST" | "UNKNOWN";
-declare const LABEL_COLORS: Readonly<Record<LabelCategory, string>>;
-/** A track as the client exposes it: the server's track plus derived label fields. */
-type LabeledTrack = CurrentTrack & {
-    labelCategory: LabelCategory;
-    labelColor: string;
+/** What the engine reads from a track. */
+type MotionInput = Pick<CurrentTrack, "trackId" | "lat" | "lon" | "groundSpeedKt" | "headingDeg" | "altitudeFt" | "status" | "lastSeenAt"> & {
+    targetType?: CurrentTrack["targetType"];
 };
-declare function getLabelCategory(track: Pick<CurrentTrack, "status" | "targetType" | "flightPlan">): LabelCategory;
-/**
- * Attach `labelCategory` / `labelColor`. Always call this on the *merged*
- * track: a delta without `flightPlan` must not downgrade a known category
- * (that is what makes labels flicker).
- */
-declare function withLabel(track: CurrentTrack): LabeledTrack;
-
-type Listener<T> = (payload: T) => void;
-declare class TypedEmitter<T extends Record<string, unknown>> {
-    private listeners;
-    on<K extends keyof T>(event: K, fn: Listener<T[K]>): () => void;
-    emit<K extends keyof T>(event: K, payload: T[K]): void;
-}
-declare class TrackCache extends TypedEmitter<{
-    update: LabeledTrack;
-    removed: {
-        trackId: string;
-    };
-    snapshot: LabeledTrack[];
-    status: AeroConnectionStatus;
-    degraded: {
-        reason: string;
-    };
-    error: AeroRecoverableError;
-    "source.status": {
-        sourceId: string;
-        status: SourceStatus;
+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;
     };
-}> {
-    private tracks;
-    /** Merges into the cached track and returns the labeled result. A "lost"
-     *  track is evicted from the cache but still returned (labelCategory LOST). */
-    applyUpdate(track: CurrentTrack): LabeledTrack;
-    applyRemoved(ev: {
-        trackId: string;
+    /** 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;
-    applySnapshot(tracks: CurrentTrack[]): LabeledTrack[];
-    getAll(): LabeledTrack[];
-    get(id: string): LabeledTrack | undefined;
-    get size(): number;
+    remove(trackId: string): void;
     clear(): void;
-    getRenderable(): (LabeledTrack & {
-        lat: number;
-        lon: number;
-    })[];
-}
-
-interface AeroSwarmOptions {
-    endpoint: string;
-    token: string;
-    wsEndpoint?: string;
-    reconnect?: boolean;
-    maxReconnectDelay?: number;
-    encoding?: "json" | "msgpack";
-    staleAfterMs?: number;
-    removeAfterMs?: number;
-    onTokenExpired?: () => Promise<string>;
-}
-/** Live callbacks: tracks arrive merged with previous state and carry
- *  `status`, `labelCategory` and `labelColor`. */
-interface LiveTrackCallbacks extends Omit<TrackCallbacks, "onTrackUpdate" | "onSnapshot"> {
-    onTrackUpdate?: (track: LabeledTrack) => void;
-    onSnapshot?: (tracks: LabeledTrack[]) => void;
-}
-interface UseAeroTracksResult {
-    tracks: CurrentTrack[];
-    status: AeroConnectionStatus;
-    sourceStatus: Record<string, string>;
-    lastUpdateAt: number | null;
-    error: AeroRecoverableError | null;
-}
-interface TrackHistoryPoint {
-    t: number;
-    lat: number | null;
-    lon: number | null;
-    altFt: number | null;
-    speedKt: number | null;
-    headingDeg: number | null;
-}
-interface DayAvailability {
-    day: string;
-    eventCount: number;
-    trackCount: number;
-    firstAt: string | null;
-    lastAt: string | null;
-}
-declare class AeroSwarm {
-    private readonly opts;
-    readonly trpc: AeroTrpcClient;
-    readonly rest: AeroRestClient;
-    readonly graphql: AeroGraphQLClient;
-    readonly cache: TrackCache;
-    private readonly wsClient;
-    private _status;
-    private _lastUpdateAt;
-    private _error;
-    private _sourceStatus;
-    private airportsCache;
-    private static readonly AIRPORTS_CACHE_TTL_MS;
-    /** Resolves which base URL (if any) should serve a federated call.
-     *  Returns null to mean "use AeroSwarm's own endpoint" — the normal,
-     *  unfederated path, which is also what a lookup failure falls back to
-     *  (a broken airports.list() call must never brick replay/history for
-     *  everyone else). */
-    private resolveHistoryEndpoint;
-    private federatedFetch;
-    constructor(opts: AeroSwarmOptions);
-    readonly tracks: {
-        subscribe: (opts: SubscribeOptions, callbacks: LiveTrackCallbacks) => (() => void);
-        updateFilter: (opts: Partial<SubscribeOptions>) => void;
-        /** Drop the live socket and reconnect immediately (no backoff wait),
-         *  re-subscribing with the last options. Returns false if nothing has
-         *  been subscribed yet. */
-        reconnect: () => boolean;
-        stream: (opts: SubscribeOptions) => AsyncIterable<LabeledTrack>;
-        snapshot: (input?: {
-            airportId?: string;
-            bbox?: Bbox;
-            source?: "fused" | "normalized";
-            minConfidence?: number;
-            limit?: number;
-            offset?: number;
-        }) => any;
-        /** Persisted position history for one track. If the airport has a
-         *  `historyEndpoint` (or `endpoint` is passed explicitly), this calls
-         *  that backend's `@aeroswarm/replay-server` instead of AeroSwarm's
-         *  own local database — see docs/development/federation/003-*.md. */
-        history: (input: {
-            trackId: string;
-            airportId?: string;
-            limit?: number;
-            endpoint?: string;
-        }) => Promise<TrackHistoryPoint[]>;
-    };
-    /** Flight plans received from AFTN feeds. Live tracks that correlate with a
-     *  plan (Mode-S address, else callsign) also carry `track.flightPlan`. */
-    readonly flightPlans: {
-        list: (input?: {
-            airportId?: string;
-            status?: string;
-            callsign?: string;
-            limit?: number;
-        }) => Promise<FlightPlanRow[]>;
-        get: (id: string) => Promise<_aeroswarm_core_types.FlightPlan>;
-    };
-    /** Raw AFTN/ATS messages received by AFTN feeds — the input side of the
-     *  flight-plan pipeline (newest first, capped by the service). */
-    readonly aftn: {
-        messages: (input?: {
-            airportId?: string;
-            limit?: number;
-        }) => Promise<AftnMessageRow[]>;
-    };
-    readonly sources: {
-        /** Registers a source and returns its token, tied to `airportId` — a
-         *  source is a sensor physically at one airport, so this is required.
-         *  Anything that later authenticates with the returned token (WS
-         *  live/replay, tRPC calls) is scoped to that airport automatically,
-         *  with no need to keep passing `airportId` on every subsequent call.
-         *  For access spanning multiple airports, use the viewer/dashboard
-         *  token instead — it's never auto-scoped. */
-        create: (body: {
-            name: string;
-            airportId: string;
-            sourceType?: string;
-            location?: {
-                lat: number;
-                lon: number;
-            };
-            config?: Record<string, unknown>;
-        }) => Promise<{
-            ok: boolean;
-            data: {
-                sourceId: string;
-                sourceToken: string;
-                airportId?: string | null;
-            };
-        }>;
-        health: (sourceId: string) => any;
-        list: (input?: {
-            airportId?: string;
-        }) => any;
-        /** Reassigning `airportId` (including to `null` to clear it) re-caches
-         *  the source's token immediately, so the new scoping takes effect
-         *  without waiting out the token cache's TTL. */
-        update: (input: {
-            id: string;
-            name?: string;
-            airportId?: string | null;
-            location?: {
-                lat: number;
-                lon: number;
-            };
-            config?: Record<string, unknown>;
-        }) => any;
-        delete: (id: string) => any;
-    };
-    /** Airport registry (multi-airport tenancy). */
-    readonly airports: {
-        list: () => Promise<{
-            airports: {
-                id: string;
-                name: string;
-                city: string | null;
-                lat: number;
-                lon: number;
-                bbox: [number, number, number, number];
-                timezone: string;
-                /** Set = this airport serves its own replay/history (federated —
-                 *  see docs/development/federation/003-*.md); `replay.*`/
-                 *  `tracks.history` calls for it connect there directly instead of
-                 *  AeroSwarm's own endpoint. null = AeroSwarm serves it (default). */
-                historyEndpoint: string | null;
-            }[];
-        }>;
-        create: (input: {
-            id: string;
-            name: string;
-            city?: string;
-            lat: number;
-            lon: number;
-            bbox: [number, number, number, number];
-            timezone?: string;
-            historyEndpoint?: string;
-        }) => Promise<{
-            ok: boolean;
-            id: string;
-        }>;
-        update: (input: {
-            id: string;
-            name?: string;
-            city?: string;
-            lat?: number;
-            lon?: number;
-            bbox?: [number, number, number, number];
-            timezone?: string;
-            /** null clears it (reverts to AeroSwarm's own replay); omit to leave unchanged. */
-            historyEndpoint?: string | null;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        delete: (input: {
-            id: string;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        /** Surface geometry (runway/taxiway/apron GeoJSON) for the map. */
-        surface: (input: {
-            id: string;
-        }) => Promise<{
-            surface: unknown | null;
-        }>;
-        setSurface: (input: {
-            id: string;
-            surface: Record<string, unknown>;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-    };
-    readonly replay: {
-        /** Data-availability calendar: which days have recorded tracks.
-         *  Use this to populate/validate replay date pickers — days not in
-         *  the list have no data. Federates to the airport's own backend when
-         *  it has a `historyEndpoint` (or `endpoint` is passed explicitly) —
-         *  see docs/development/federation/003-*.md. */
-        days: (input?: {
-            airportId?: string;
-            lookbackDays?: number;
-            endpoint?: string;
-        }) => Promise<{
-            days: DayAvailability[];
-        }>;
-        range: (input: {
-            from: string;
-            to: string;
-            airportId?: string;
-            endpoint?: string;
-        }) => Promise<{
-            earliest: string | null;
-            latest: string | null;
-            eventCount: number;
-            trackCount: number;
-            from: string;
-            to: string;
-        }>;
-        /** Server-paced WS playback: streams historical tracks at `speed`× in
-         *  the same envelope format as the live stream. Returns a transport
-         *  handle (pause/resume/seek/stop) — a Promise, since resolving which
-         *  backend serves this airport (see docs/development/federation/003-*.md)
-         *  is async. See `AeroReplayClient` for the raw wire protocol if you
-         *  want to speak WS manually instead. */
-        stream: (opts: ReplayStreamOptions & {
-            endpoint?: string;
-        }, callbacks: ReplayCallbacks) => Promise<ReplayHandle>;
-    };
-    /** Movement analytics: takeoffs/landings per hour + peak hour, recorded
-     *  by the pipeline's movement detector. */
-    readonly analytics: {
-        movements: (input?: {
-            airportId?: string;
-            day?: string;
-        }) => Promise<{
-            day: string;
-            hours: {
-                hour: string;
-                takeoffs: number;
-                landings: number;
-            }[];
-            totals: {
-                takeoffs: number;
-                landings: number;
-            };
-            peak: {
-                hour: string;
-                count: number;
-            } | null;
-        }>;
-    };
-    /** Route conformance: pre-defined ground routes + live track clearances.
-     *  Assign a route to a track and the safety engine can detect when it
-     *  strays beyond the route's corridor. */
-    readonly routes: {
-        list: (input?: {
-            airportId?: string;
-        }) => Promise<{
-            routes: {
-                routeId: string;
-                airportId: string;
-                name: string;
-                kind: string;
-                points: [number, number][];
-                maxDeviationM: number;
-                enabled: boolean;
-            }[];
-        }>;
-        create: (input: {
-            airportId: string;
-            name: string;
-            kind?: "taxi" | "departure" | "arrival";
-            points: [number, number][];
-            maxDeviationM?: number;
-        }) => Promise<{
-            id: string;
-        }>;
-        delete: (input: {
-            id: string;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        assign: (input: {
-            trackId: string;
-            routeId: string;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        unassign: (input: {
-            trackId: string;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        assignments: () => Promise<{
-            assignments: {
-                trackId: string;
-                routeId: string;
-                assignedAt: number;
-            }[];
-        }>;
-    };
-    readonly webhooks: {
-        list: () => any;
-        create: (body: {
-            url: string;
-            events: string[];
-            secret?: string;
-        }) => Promise<{
-            ok: boolean;
-            webhookId: string;
-        }>;
-        delete: (input: {
-            id: string;
-        }) => any;
-    };
-    readonly system: {
-        stats: () => any;
-        infraHealth: () => any;
-        ingestHistory: () => any;
-        getConfig: () => Promise<{
-            key: string;
-            value: string;
-            updatedAt: string;
-        }[]>;
-        setConfig: (input: {
-            key: string;
-            value: string;
-        }) => Promise<{
-            ok: boolean;
-        }>;
-        clearTable: (input: {
-            table: "fused_tracks" | "source_health";
-            mode: "all" | "range";
-            from?: string;
-            to?: string;
-        }) => any;
-    };
-    getStatus(): AeroConnectionStatus;
-    getLastUpdateAt(): number | null;
-    getError(): AeroRecoverableError | null;
-    getSourceStatus(): Record<string, string>;
-    disconnect(): void;
-    reconnect(): boolean;
-}
+    /** 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 { AeroReplayClient, AeroSwarm, type AeroSwarmOptions, AeroWsClient, type AftnMessageRow, type DayAvailability, type FlightPlanRow, LABEL_COLORS, type LabelCategory, type LabeledTrack, type LiveTrackCallbacks, type ReplayCallbacks, type ReplayHandle, type ReplayProgress, type ReplayStreamOptions, type SourceRow, type SubscribeOptions, TrackCache, type TrackCallbacks, type TrackHistoryPoint, type UseAeroTracksResult, getLabelCategory, withLabel };
+export { type MotionFrame, type MotionInput, type MotionOptions, type MotionSample, type MotionScheduler, type TrackMotion, createTrackMotion };